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.
- `mark.svg` - compact app mark and favicon.
- `mark-mono.svg` - single-color mark for constrained contexts.
- `social-preview.svg` - Open Graph, README, release, or marketplace preview.
- `pwa-192.png`, `pwa-512.png`, `apple-touch-icon.png` - install surfaces.

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:

- Tracker
- Bills
- Calendar
- Analytics
- Data
- Banking
- Snowball
- Security/Admin

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.

## 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`.