docs(brand): add BRAND.md guidelines
120-line brand guidelines document covering the v0.42.0 brand
system: naming ('Bill Tracker' with the space, not 'BillTracker'),
asset paths, lockup usage rules (light vs dark variants, mono
mark, social preview), the canonical source-of-truth in
client/lib/brand.ts, and the GitHub-Open-Graph card dimensions.
This is commit 4 (and the last) of the v0.42.0 follow-up batch.
Docs-only; no code change. Depends on 68e57cf (favicon + PWA).
This commit is contained in:
null
parent
68e57cf45b
commit
c9d90a125f
|
|
@ -0,0 +1,120 @@
|
|||
# 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`.
|
||||
Loading…
Reference in New Issue