non ai theme

AGENTS.md

@@ -17,26 +17,42 @@ React 19 + Vite 8 + TypeScript design-system showcase. Dark-first, token-driven
 
 ## Design tokens — the contract
 
-1. **Single source of truth: `src/tokens.css`.** Every font size, color, spacing, radius, and shadow color in `src/App.css` comes from a token. The guard `scripts/check-tokens.mjs` (in `npm run check`) bans hardcoded hex colors, px font sizes, and raw `rgba()` in application CSS — new colors go in as tokens, accent washes use `color-mix(in srgb, var(--accent) N%, transparent)`.
-2. Typography scale (`--text-3xs` … `--text-2xl`, `--text-hero`) is rem-based on a 9→28px grid. Longform body `--text-md`, buttons/nav `--text-xs`, meta/eyebrows `--text-2xs`/`--text-3xs`.
-3. **Global density knob: `--root-font-size`** (default `112%` readability preset, baseline 16px = `100%`). One line scales every token-driven size app-wide; spacing tokens follow.
-4. **Theming:** components read only `var(--*)` and never know the theme. `:root[data-theme='light']` in tokens.css holds the daylight palette. Toggle = `document.documentElement.dataset.theme` (Topbar's sun/moon button, persisted in `localStorage['ns-theme']`). Adding a third theme = one more token block.
-5. "Make the small text a bit larger" = bump `--text-xs`/`--text-2xs`. "Soften a surface" = its token. No grep, no per-component edits.
+1. **Single source of truth: `src/tokens.css`.** Every font size, color, spacing, radius, and shadow color comes from a token. The palette is defined in modern CSS Color 4 `lab(...)` color space:
+   - Dark theme (`.dark`, `[data-theme='dark']`): Pitch black base (`lab(0% 0 0)`), deep cards (`lab(.903296% 0 0)`), radiant electric mint/cyan primary (`lab(89.9321% -47.9163 -15.7303)`), vivid destructive (`lab(54.5811% 71.684 50.9279)`), chart colors 1–5, and subtle dot grid (`--dot-color`).
+   - Light theme (`:root`, `[data-theme='light']`): Pure white daylight base (`lab(100% 0 0)`), crisp charcoal primary (`lab(7.78201% -.0000149012 0)`), and high-contrast surfaces.
+2. The guard `scripts/check-tokens.mjs` (in `npm run check`) bans hardcoded hex colors, px font sizes, and raw `rgba()` in application CSS — new colors go in as tokens, accent washes use `color-mix(in srgb, var(--primary) N%, transparent)`.
+3. Typography scale (`--text-3xs` … `--text-2xl`, `--text-hero`) is rem-based on a 9→28px grid. Longform body `--text-md`, buttons/nav `--text-xs`, meta/eyebrows `--text-2xs`/`--text-3xs`.
+4. **Global density knob: `--root-font-size`** (default `112%` readability preset, baseline 16px = `100%`). One line scales every token-driven size app-wide; spacing tokens follow.
+5. **Theming:** components read only `var(--*)` and never know the theme. Toggle synchronizes both `document.documentElement.dataset.theme` and `.dark`/`.light` classes.
+
+## Smart Utils & AI Workflow
+
+- **Class helper**: `src/utils/cn.ts` — zero-dependency classnames merging utility for conditional component styles.
+- **Smart CSS**: `src/utils.css` — ready-to-use helpers (`.dot-canvas`, `.surface-card`, `.surface-sidebar`, `.badge-*`, `.hover-lift`, `.kbd-tag`, `.skeleton-pulse`).
+- **Composable Primitives**: `src/components/ui/` (`Badge.tsx`, `Card.tsx`, `StatCard.tsx`, `Kbd.tsx`).
+- **AI Agent System Prompt & Recipes**: `src/data/ai-rules.ts`.
 
 ## Structure
 
 ```
 src/
-  tokens.css        ← design tokens + light theme (edit this first)
-  index.css         ← fonts, tokens import, base resets
-  App.css           ← all component styles (token-driven, plain CSS)
-  App.tsx           ← page composition only
-  components/       ← one component per file, readable multi-line JSX
-    Topbar.tsx      ← owns the theme toggle (useTheme inside)
+  tokens.css        ← lab() design tokens + dark & light themes (edit this first)
+  utils.css         ← token-compliant smart CSS utility classes
+  index.css         ← fonts, tokens & utils import, base resets
+  App.css           ← application component styles (token-driven, plain CSS)
+  App.tsx           ← page composition & showcase layout
+  utils/
+    cn.ts           ← conditional classnames utility
+  components/
+    ui/             ← composable UI primitives (Badge, Card, StatCard, Kbd)
+    AIWorkflowSection.tsx ← AI workflow and smart utils showcase
+    Topbar.tsx      ← owns the theme toggle (.dark & data-theme)
     Hero.tsx, CodeSample.tsx, RightRail.tsx, ButtonMatrix.tsx,
     Sidebar.tsx, Section.tsx, FormField.tsx, TokenGrid.tsx,
     MarkdownRenderer.tsx, CodeEditor.tsx, Button.tsx, Icon.tsx
-  data/library.ts   ← demo content for the showcase
+  data/
+    library.ts      ← demo content and color token data for the showcase
+    ai-rules.ts     ← AI copilot prompt and quick implementation recipes
 scripts/check-tokens.mjs ← token contract guard (part of npm run check)
 ```