BillTracker/docs/BRAND.md

# Bill Tracker Brand System

## Position

Bill Tracker is a premium calm household finance app: private, self-hosted, practical, and emotionally quiet. The brand should make money planning feel under control without pretending to be a bank or a consumer fintech toy.

**Name:** Bill Tracker  
**Tagline:** Calm command for household money.  
**Promise:** Know what is due, what is paid, and what remains with less mental load.

## Personality

- Calm, precise, and trustworthy.
- Modern but not flashy.
- Helpful without sounding cute.
- Confident about money without using pressure or shame.
- Private by default; self-hosted is a feature, not a caveat.

Use plain language. Prefer "what changed" and "what to do next" over abstract product copy.

## Visual Direction

The visual lane is **premium calm**.

- Deep ink surfaces, warm paper light mode, quiet graphite borders.
- Trust green is the signature color.
- Teal supports connected systems and data flow.
- Amber means caution or attention.
- Rose means overdue, destructive, or urgent.
- Avoid purple as a primary brand cue.
- Avoid heavy gradients, glassy novelty, and decorative clutter.

## Core Colors

| Token | Hex       | Use                                                 |
| ----- | --------- | --------------------------------------------------- |
| Ink   | `#101417` | Dark app shell, mark background, premium depth      |
| Paper | `#f8faf9` | Light app background, high-contrast text on dark    |
| Trust | `#40c878` | Primary actions, brand mark, success, active states |
| Teal  | `#23b6a8` | Bank sync, data flow, secondary brand accent        |
| Amber | `#d99a24` | Due soon, warnings, drift, review-needed states     |
| Rose  | `#df4661` | Overdue, destructive, high urgency                  |

The app implementation maps these through OKLCH theme tokens in `client/index.css`; do not hardcode the hex values in components unless creating static brand assets.

## Logo Assets

Primary source files live in `client/public/brand/`.

- `lockup.svg` - primary logo for dark surfaces.
- `lockup-light.svg` - primary logo for light surfaces.
- `logo.png` - light-surface raster export of the primary logo for docs and non-SVG contexts.
- `mark.svg` - compact app mark and favicon.
- `mark.png` - raster export of the compact app mark.
- `mark-mono.svg` - single-color mark for constrained contexts.
- `favicon.svg`, `favicon.ico` - browser tab and legacy favicon surfaces.
- `social-preview.svg`, `social-preview.png` - Open Graph, README, release, or marketplace preview.
- `empty-state.svg` - reusable empty-state illustration style.
- `pwa-192.png`, `pwa-512.png`, `pwa-maskable.svg`, `pwa-maskable-512.png`, `apple-touch-icon.png` - install surfaces.
- `glyphs/*.svg` - standalone product glyph source files.

Supporting app artwork:

- `client/public/img/auth.svg` - branded secure-access glyph for OIDC/authentication surfaces.
- `client/public/img/auth.png` - raster fallback export of the secure-access glyph.

Rules:

- Use the full lockup when the product needs to introduce itself.
- Use the mark alone only in constrained chrome: favicon, PWA, compact UI, or avatar-like placement.
- Do not stretch, recolor, outline, or put the mark inside another badge.
- Leave clear space around the logo at least equal to the width of one chart bar.

## Glyph System

Bill Tracker has a small proprietary product glyph set for page identity only:

| Product area      | Asset                                            |
| ----------------- | ------------------------------------------------ |
| Tracker           | `client/public/brand/glyphs/tracker.svg`         |
| Bills             | `client/public/brand/glyphs/bills.svg`           |
| Calendar          | `client/public/brand/glyphs/calendar.svg`        |
| Analytics         | `client/public/brand/glyphs/analytics.svg`       |
| Data / Banking    | `client/public/brand/glyphs/data-banking.svg`    |
| Snowball / Payoff | `client/public/brand/glyphs/snowball-payoff.svg` |
| Admin / Security  | `client/public/brand/glyphs/admin-security.svg`  |

Rules:

- Use brand glyphs for page headers, empty states, onboarding, and brand moments.
- Keep Lucide icons for actions, controls, menus, buttons, tables, and common UI patterns.
- Never replace familiar action icons such as edit, delete, search, settings, upload, download, calendar navigation, or logout.
- Glyphs should reuse the mark language: bars, checks, ledger lines, quiet rounded geometry.
- Avoid third-party-style or novelty images inside core app surfaces unless the product explicitly needs a partner logo.

## Typography

- UI text uses the app sans stack.
- Money and dates use tabular numeric treatment.
- Avoid oversized type in dense operational surfaces.
- Use sentence case for labels and commands unless an existing domain term requires otherwise.

Tone examples:

- Good: "No bills match your filters."
- Good: "Calm command for household money."
- Avoid: "Supercharge your financial destiny."
- Avoid: "Oopsie, payment chaos detected."

## Surface Rules

- Use `surface-premium`, `metric-card`, `PageHeader`, `MetricCard`, `SectionSurface`, and `EmptyState` before adding new one-off surface classes.
- Tables and repeated rows stay dense and scannable.
- Cards are for actual grouped content, not page sections inside page sections.
- Status must not rely on color alone; pair color with text and, where urgent, an icon.
- Motion should be subtle and must respect reduced motion.

## Implementation Sources

- Brand constants: `client/lib/brand.ts`
- Brand components: `client/components/brand/Brand.tsx`
- App primitives: `client/components/ui/app-primitives.tsx`
- Theme tokens and shared surfaces: `client/index.css`
- Static assets: `client/public/brand/`

## Do Not Drift

- Do not create new brand colors outside the token set.
- Do not create page-specific hero art unless it becomes a reusable brand pattern.
- Do not make the app less dense in the tracker, bills, subscriptions, or banking tables.
- Do not use branded glyphs as action buttons.
- Do not reintroduce mixed naming; visible product name is `Bill Tracker`.