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.