'UI Shell and General Architecture'

1 files changed, 24 insertions, 0 deletions

diff --git a/CLAUDE.md b/CLAUDE.md
index 9e7c256..ea7a26f 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -49,6 +49,30 @@ Selected ticker lives in the URL query param `?ticker=SYMBOL`. Types are shared
 ### Testing approach
 Backend tests use `monkeypatch` to stub `data_service` functions — never make live yfinance calls in tests. Use a `tmp_path` fixture for any test that touches SQLite. There is no frontend test runner; use `npm run lint` and `npm run build` for frontend validation.
 
+## Design System (`design-system/`)
+
+The repo includes a full personal-brand design system at `design-system/`. All frontend work must follow it — never invent colors, radii, or type choices.
+
+**Token entry point:** `design-system/colors_and_type.css` (also mirrored into `frontend/public/design-system/` for serving). Import it for all new components; it declares every CSS custom property: ink surfaces, fg tints, brass/champagne accent, oxford navy, burgundy, semantic gain/loss/caution/info colors, spacing scale, radii, shadows, and font stacks.
+
+**Typefaces:**
+- `--font-serif` — EB Garamond (variable). Display + body serif; italic at large sizes is the signature move.
+- `--font-sans` — IBM Plex Sans. UI labels, eyebrows, buttons, badges.
+- `--font-mono` — IBM Plex Mono. All prices, percentages, and tabular numerics (`font-variant-numeric: tabular-nums`).
+
+**Visual rules that must not be broken:**
+- Background is `#0B0E13` (ink-0), never pure black. Text is `#F2ECDC` (fg-0), never pure white.
+- Primary accent is champagne `#C2AA7A` — for links, focus rings, eyebrows, button fills. Never as a large background fill.
+- Semantic colors: gain `#4F8C5E`, loss `#B5494B`, caution `#C49545`, info `#4A78B5`.
+- Card radius is 6px; buttons are 2px. No radius above 6px except capsule chips (999px). No bubbly rounding.
+- Hairline `1px` borders only (`#232934`). No gradients except the chart area fill. No glass effects.
+- Transitions are 150ms ease. No bounces, springs, or scroll-jacking.
+- No emoji — ever. Use SVG icons from `design-system/assets/icons/` or unicode geometrics (`▲ ▼ ◈ ✦ ↗ ·`).
+
+**Prism UI kit:** `design-system/ui_kits/prism/` is a forward-looking redesign showing the target component shapes: `<Sidebar>`, `<TopBar>`, `<TickerHeader>`, `<KPIStrip>`, `<ChartCard>`, `<QuoteTable>`, `<ValuationPanel>`, `<FilingsList>`, `<InsiderRow>`. Read `parts{1,2,3}.jsx` and `prism.css` before building new dashboard surfaces.
+
+**Skill:** `design-system/SKILL.md` is a Claude Code skill (`tyler-hoang-design`) — invoke it when doing design-heavy frontend work.
+
 ## Reference: Prism v1 (`../prism`)
 
 The old Streamlit-based app at `../prism` is the canonical reference for finance logic being ported into v2. Do not import from it at runtime, but read it when implementing new financial features.