From c9d90a125f9df589fa3c080d5d29a13401f3cfc8 Mon Sep 17 00:00:00 2001 From: null Date: Sun, 5 Jul 2026 17:50:18 -0500 Subject: [PATCH] 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). --- docs/BRAND.md | 120 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 120 insertions(+) create mode 100644 docs/BRAND.md diff --git a/docs/BRAND.md b/docs/BRAND.md new file mode 100644 index 0000000..f137414 --- /dev/null +++ b/docs/BRAND.md @@ -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`.