Initial commit

frontend/README.md

@@ -0,0 +1,78 @@
+# Northstar Design System
+
+A token-driven design system showcase built for AI-assisted development workflows.
+React 19 · Vite 8 · TypeScript (strict) · Vitest · oxlint.
+
+## Quick start
+
+```bash
+npm install
+npm run dev        # dev server on 0.0.0.0:5173
+```
+
+## Auth and the API proxy
+
+`/api` is proxied to the Go backend (`API_URL`, default
+`http://localhost:8080`) so the browser only ever sees the vite origin —
+on `localhost` or `*.preview.k6n.net`. That keeps OIDC redirects and the
+session cookie first-party: the topbar's Sign in and the overview Session
+card go through `/api/auth/login`, the issuer returns to
+`/api/auth/callback` on the same host, and `useSession()`
+([src/auth](src/auth)) polls `/api/auth/session`. The proxy forwards
+`X-Forwarded-Host`/`X-Forwarded-Proto` so the backend registers the right
+redirect URI per host. See the backend README for the server side.
+
+## The quality gate
+
+```bash
+npm run check
+```
+
+One command, four gates, in order:
+
+1. **`oxlint`** — lint over every source file.
+2. **`scripts/check-tokens.mjs`** — the token contract: bans hardcoded colors
+   (hex / named / `rgb()` / `hsl()` / `oklch()` / `lab()`), px font sizes and
+   undefined `var(--x)` references — in **both** CSS files and inline
+   `style={{ … }}` objects. Values may span lines; comments are ignored.
+3. **`vitest run`** — unit + component tests (`tests/`).
+4. **`tsc -b && vite build`** — strict typecheck, then production build.
+
+CI runs the same gate on every push and PR (`.github/workflows/ci.yml`).
+
+## Design tokens
+
+`src/tokens.css` is the single source of truth. Every color, font size,
+spacing, radius and shadow goes through a `var(--token)` — components never
+hardcode values. Themes are plain CSS: `:root[data-theme='light']` /
+`.light` and `:root[data-theme='dark']` / `.dark`, with a pre-paint script in
+`index.html` that applies the saved (or OS-preferred) theme before first paint.
+
+The global density knob is `--root-font-size` — one line scales the whole app.
+
+## Layout
+
+```
+src/
+  tokens.css        ← lab() design tokens, dark & light themes
+  index.css         ← fonts, token import, base resets
+  utils.css         ← token-compliant utility classes
+  App.css           ← application showcase styles
+  app/              ← AppStateProvider + useAppState(), and the route table (wouter)
+  auth/             ← useSession() + UserMenu / SessionCard (OIDC identity via the API proxy)
+  pages/            ← one page component per route
+  components/
+    ui/             ← composable primitives (Overlay, Dialog, Sheet, Tabs, Alert, …)
+    icon-registry.ts← the one icon name → lucide component map
+    examples/       ← reusable patterns (MetricsDashboard, SettingsPanel, …)
+    dev/            ← ErrorBoundary + dev error sink (#dev-errors)
+  utils/            ← cn(), useTimeout()
+tests/              ← vitest suites (jsdom)
+scripts/
+  check-tokens.mjs  ← token contract guard
+```
+
+## For agents
+
+Read [`AGENTS.md`](./AGENTS.md) before changing anything — it documents the
+token contract, the overlay/icon registries, and the parallel-subagent rules.