all docsdocs/DESIGN.md

Design language

Dark, minimal, liquid glass. Grays on grays, one restrained mint accent.

References: the Grapevine landing (pill nav, atmospheric dark), the CryptoLens / "untitled" dashboards (bold sans headings, muted gray sidebars, glass panels), Aldrin (landing minimalism). Screen inventory inherited from the CardIntel prototype — see reference/claude-design-spec.md.

Rules

  1. Every value is a token. Colors, type sizes, spacing unit, radii, glass treatment — all defined once in apps/web/src/app/theme.css. No hex, no oklch, no magic px in components. If a value isn't expressible with an existing token, add a token.
  2. Dark only (for now). The app commits to one look; color-scheme: dark is set globally. A light palette would be a second semantic block in theme.css, not a component change.
  3. Monochrome first. Surfaces are white-alpha glass over near-black ink; text is a three-step gray ladder. Color carries meaning only: mint (--color-positive / chart lead), red (--color-negative), amber (--color-warning). If it's decorative, it's gray.
  4. Glass sparingly but consistently. .glass for panels/cards, .glass-strong for elevated chips. Never nest heavy blur.
  5. Type hierarchy.
    • Headings: font-heading (Hanken Grotesk) bold, tight tracking.
    • Body/UI: font-sans (Geist).
    • Data, labels, numbers: font-mono (Geist Mono) — all stats and table numerics are mono. Section labels use .data-label (mono, 2xs, uppercase, tracked).
  6. Density like Notion. Quiet chrome, small labels, generous but not airy spacing; panels breathe at p-5, grids gap at gap-3/gap-4.
  7. State colors mean competitiveness. Green = more competitive / best in row / verified-high; red = less competitive; neutral gray = re-verified / unchanged. Same encoding on badges, compare highlights, provenance dots.
  8. Provenance is visible. Values that came from somewhere render a ProvenanceBadge (source · verified date · confidence dot). Estimates and mock data are labeled as such — never dressed up as facts.

Component inventory

shadcn/ui primitives (components/ui/) + Frankie-specific pieces (components/frankie/): PageHeader, StatCard, BarList, EventRow, CompetitiveBadge, ProvenanceBadge, CardSwatch. Charts wrap Recharts and pull colors from chart tokens (components/charts/).