@codeyam/codeyam-cli 0.1.0-staging.4c0c3c9 → 0.1.0-staging.5370992

package/codeyam-cli/templates/codeyam-editor-claude.md

@@ -0,0 +1,149 @@
+# CodeYam Editor Project
+
+This project is being built with CodeYam's Code + Data Editor. The core principle is **code and data are developed together** — every component should have scenario data that drives what it renders.
+
+## Architecture: Components + Scenarios
+
+### Component Structure
+
+Build with a clear component hierarchy so individual components can be previewed in isolation:
+
+```
+app/
+  components/
+    Dashboard.tsx        ← page-level component
+    TaskList.tsx         ← displays a list, gets data from API or props
+    TaskCard.tsx         ← single item, pure props
+    EmptyState.tsx       ← shown when no data
+```
+
+Each component should accept props that let it be rendered independently. Avoid components that can only work when deeply embedded — they should be previewable on their own with mock data.
+
+### Scenarios
+
+A **scenario** is a named set of data that drives how the app renders. Scenarios exist at two levels:
+
+- **App-level scenarios**: Full application state — what the database contains, what API responses return. Example: "Empty Dashboard", "Dashboard with 50 Tasks", "Dashboard with Overdue Tasks"
+- **Component-level scenarios**: Props for a single component in isolation. Example: "TaskCard - Default", "TaskCard - Overdue", "TaskCard - Completed"
+
+**Name scenarios by data state** ("Rich Data", "Empty", "Mobile"), not by feature. When adding a feature, enhance an existing scenario's data — rename it if the scope has grown.
+
+**Only create scenarios for states the current code can render.** If you seed 10 articles but the app doesn't have an article list component yet, the screenshot will show an empty page — that's a broken scenario. After registering, always view the captured screenshot to verify the data is actually visible.
+
+**Always register scenarios with CodeYam** using the CLI:
+
+```bash
+# Small inline JSON:
+codeyam editor register '{"name":"TaskCard - Default","componentName":"TaskCard","url":"/isolated-components/TaskCard?s=Default","dimensions":["<name from screenSizes>"]}'
+
+# Large JSON — use the Write tool to write to .codeyam/tmp/scenario.json, then:
+codeyam editor register @.codeyam/tmp/scenario.json
+```
+
+**To list existing scenarios:** `codeyam editor scenarios`
+
+### Database First
+
+Use a real database (SQLite + Prisma recommended) from the start. This lets scenarios represent different database states rather than just static prop variations:
+
+- Each scenario can seed the database with different data
+- API routes naturally return different results per scenario
+- This is closer to real-world behavior than prop mocking alone
+
+### Zooming In and Out
+
+The CodeYam Editor supports zooming between the full app view and isolated component views:
+
+- **Zoomed out**: See the whole app running with scenario data flowing through the database and APIs
+- **Zoomed in**: See a single component rendered in isolation with specific props
+
+Build components so they work at both zoom levels. A `TaskCard` should render correctly whether it's inside the full app or previewed alone with mock props.
+
+## Workflow
+
+1. Build a component
+2. Create scenarios with rich, realistic data that thoroughly exercises the component:
+   - Happy path with diverse, realistic content (not just "Test Item 1", "Test Item 2")
+   - Empty state (no data, first-time user)
+   - Rich data (many items, all optional fields populated, varied lengths and categories)
+   - Edge cases if they surface naturally from diverse data
+3. Register the scenarios with CodeYam
+4. Preview each scenario to verify the component handles all states
+5. Repeat for the next component, building up scenario coverage
+
+## Key Conventions
+
+- Component files go in `app/components/` (or `src/components/`)
+- One component per file, default export
+- Components accept props that can be provided by scenarios
+- Database seed scripts go in `prisma/seeds/` (one per scenario when using DB-level scenarios)
+- MSW handler files go in `.codeyam/msw-handlers/` (one per scenario for API mocking)
+
+## Design System
+
+If `.codeyam/design-system.md` exists, it contains the project's design tokens and brand guidelines. The editor step instructions will automatically show its contents inline — you don't need to read the file separately.
+
+- Define **every** design token as a CSS custom property in `globals.css` — not just colors:
+  - Colors: `--bg-surface`, `--text-primary`, `--accent-green-a`, etc.
+  - Typography: `--text-xs: 12px`, `--text-sm: 14px`, `--text-lg: 18px`, etc.
+  - Font weights: `--font-weight-normal: 400`, `--font-weight-medium: 500`, `--font-weight-semibold: 600`
+  - Spacing: `--spacing-xs: 4px`, `--spacing-sm: 8px`, `--spacing-md: 12px`, `--spacing-lg: 16px`, etc.
+  - Border radius, shadows, and transitions
+- Components must reference tokens — **zero hardcoded px values** for font-size, padding, margin, gap, or colors
+  - Bad: `fontSize: 14`, `padding: '12px 16px'`, `gap: 8`
+  - Good: `fontSize: 'var(--text-sm)'`, `padding: 'var(--spacing-md) var(--spacing-lg)'`, `gap: 'var(--spacing-sm)'`
+- This ensures the entire app updates when the design system changes
+
+## Avoiding Permission Prompts
+
+These patterns cause unnecessary approval prompts in Claude Code. Follow these rules:
+
+### Writing JSON files — use the Write tool, not bash
+
+**BAD** (triggers "expansion obfuscation" security warning due to braces+quotes in heredoc):
+
+```bash
+cat > /tmp/scenario.json << 'EOF'
+{"name":"My Scenario","localStorage":{"key":"[{\"id\":\"1\"}]"}}
+EOF
+```
+
+**GOOD** (Write tool is pre-approved, no bash prompt):
+Use the **Write tool** to create `.codeyam/tmp/scenario.json`, then register:
+
+```bash
+codeyam editor register @.codeyam/tmp/scenario.json
+```
+
+### Listing scenarios — use the CLI subcommand
+
+**BAD** (triggers bash approval):
+
+```bash
+cat .codeyam/editor-scenarios/*.json | grep -o '"name":"[^"]*"'
+ls .codeyam/editor-scenarios/*.json
+```
+
+**GOOD** (pre-approved):
+
+```bash
+codeyam editor scenarios
+```
+
+### Database schema changes — never force-reset
+
+**BAD** (destructive, triggers approval, drops all data):
+
+```bash
+npx prisma db push --force-reset
+```
+
+**GOOD** (preserves data by providing defaults for new required columns):
+
+```prisma
+userId Int @default(0)   // existing rows get 0
+```
+
+Then: `npm run db:push`
+
+If you must add a required column without a default, make it optional (`Int?`) or provide a `@default()` value. Never destroy user data with `--force-reset`.

package/codeyam-cli/templates/codeyam-editor-reference.md

@@ -0,0 +1,216 @@
+# .codeyam/ Directory Reference
+
+This file documents the `.codeyam/` internals and CLI commands. Consult this when you're stuck on scenario registration, audit failures, preview issues, or understanding what files do what.
+
+## Directory Structure
+
+### Committed Files (shared across clones)
+
+- `config.json` — Project configuration: slug, screen sizes, default viewport, feature metadata
+- `editor-scenarios/` — Scenario JSON files with seed data, localStorage, MSW handlers, and metadata
+- `scenarios-manifest.json` — Index of all scenarios for database sync on fresh clones
+- `design-system.md` — Design tokens and brand guidelines (if present)
+- `glossary.json` — Entity glossary built during extraction steps
+- `msw-handlers/` — MSW handler files for API mocking (one per scenario)
+- `seed-adapters/` — Seed adapter templates for database seeding
+
+### Gitignored Files (machine-local)
+
+- `db.sqlite3` / `db.sqlite3-wal` / `db.sqlite3-shm` — SQLite database (rebuilt on clone via `codeyam editor`)
+- `secrets.json` — API keys (Anthropic, etc.)
+- `server.json` / `server-state.json` — Background server process state
+- `queue.json` — Analysis job queue state
+- `active-scenario.json` — Currently active scenario for the preview
+- `editor-step.json` — Current editor workflow step number
+- `editor-user-prompt.txt` — The user's feature request text
+- `claude-session-id.txt` — Claude Code session ID for step tracking
+- `editor-mode-context.md` / `dev-mode-context.md` — Generated context for Claude
+- `logs/` — Server and analysis logs
+- `llm-calls/` — LLM call recordings
+- `captures/` — Playwright screenshot captures
+- `results/` — Analysis results
+- `tmp/` — Temporary files (use for large scenario JSON)
+- `rules/` — Auto-installed Claude rules
+- `bin/` — Helper scripts and hooks
+
+## CLI Command Reference
+
+All commands use the pattern `codeyam editor <subcommand>`.
+
+### Scenario Management
+
+| Command                                 | Description                                                |
+| --------------------------------------- | ---------------------------------------------------------- |
+| `codeyam editor register '<json>'`      | Register a scenario (inline JSON or `@path/to/file.json`)  |
+| `codeyam editor scenarios`              | List all registered scenarios                              |
+| `codeyam editor delete <scenarioId>`    | Delete a scenario by ID                                    |
+| `codeyam editor scenario-coverage`      | Verify all affected scenarios are fresh after code changes |
+| `codeyam editor validate-seed '<json>'` | Validate seed data structure                               |
+
+### Preview & Verification
+
+| Command                           | Description                                                                                       |
+| --------------------------------- | ------------------------------------------------------------------------------------------------- |
+| `codeyam editor preview '<json>'` | Navigate preview — **must include `dimension`** (e.g., `{"path":"/route","dimension":"Desktop"}`) |
+| `codeyam editor client-errors`    | Show client-side errors from the preview iframe                                                   |
+| `codeyam editor audit`            | Check that glossary entries have registered scenarios and tests                                   |
+
+### Entity Analysis
+
+| Command                                          | Description                                                            |
+| ------------------------------------------------ | ---------------------------------------------------------------------- |
+| `codeyam editor analyze-imports [file...]`       | Build the import dependency graph (optionally scope to specific files) |
+| `codeyam editor dependents <EntityName>`         | Find all entities that import a given entity                           |
+| `codeyam editor isolate "ComponentA ComponentB"` | Create isolation route directories for components                      |
+
+### Server
+
+| Command                     | Description             |
+| --------------------------- | ----------------------- |
+| `codeyam editor dev-server` | Query dev server status |
+
+### Workflow
+
+| Command                                                 | Description                                                     |
+| ------------------------------------------------------- | --------------------------------------------------------------- |
+| `codeyam editor <1-18>`                                 | Jump to a specific editor workflow step                         |
+| `codeyam editor steps`                                  | Show setup overview or cycle progress                           |
+| `codeyam editor change <feature>`                       | Start the change workflow for modifying features                |
+| `codeyam editor sync`                                   | Import scenarios from manifest into database (used after clone) |
+| `codeyam editor migrate [step\|next\|complete\|status]` | Run migration workflow steps                                    |
+
+## Scenario Registration Patterns
+
+### Component-Level Scenario
+
+```json
+{
+  "name": "TaskCard - Overdue",
+  "componentName": "TaskCard",
+  "url": "/isolated-components/TaskCard?s=Overdue",
+  "dimensions": ["Desktop"]
+}
+```
+
+### App-Level Scenario
+
+```json
+{
+  "name": "Dashboard with Tasks",
+  "url": "/",
+  "dimensions": ["Desktop"],
+  "seedData": {
+    "tasks": [{ "id": 1, "title": "Ship feature", "status": "in_progress" }]
+  },
+  "localStorage": { "user": "{\"name\":\"Alice\"}" }
+}
+```
+
+### Large JSON — Use a Tmp File
+
+Write JSON to `.codeyam/tmp/scenario.json` using the **Write tool**, then:
+
+```bash
+codeyam editor register @.codeyam/tmp/scenario.json
+```
+
+### Re-registration
+
+Registering a scenario with the same name replaces the existing one. No need to delete first.
+
+### Dimensions
+
+Dimension names come from `screenSizes` in `.codeyam/config.json`. Common values: `"Desktop"`, `"Mobile"`, `"Tablet"`. Every scenario and preview command must specify a dimension.
+
+## Troubleshooting
+
+### Audit gate blocking step 8+
+
+The audit checks that every glossary entity has at least one scenario and passes tests. Fix by:
+
+1. Run `codeyam editor audit` to see which entities are missing coverage
+2. Register scenarios for uncovered entities
+3. Fix any failing tests
+4. Re-run audit — do NOT loop `audit` and `analyze-imports` repeatedly
+
+### Scenarios showing empty/blank pages or error pages
+
+The scenario renders a URL but the page has no visible content, or shows an error page. Common causes:
+
+- **URL references IDs that don't exist in the seed data**: The URL contains a dynamic segment (e.g., `/items/abc-123`) but the seed data creates records with different IDs. Check the register output for `API response error` lines — they show the exact API call that failed and the server's response.
+- **Seed data doesn't match the code**: The seeded data has fields the component doesn't read, or the component expects data the seed doesn't provide
+- **Missing API route**: The component fetches from an API that doesn't exist yet
+- **Component not exported or not mounted**: The isolation route doesn't render the component
+- **Only create scenarios for states the current code can render** — if the component isn't built yet, the screenshot will be blank
+
+### Client errors in preview
+
+Run `codeyam editor client-errors` to see errors from the preview. There are three types:
+
+- **Console errors** (`Page console.error:`): JavaScript runtime errors — missing env vars, import errors, schema mismatches
+- **HTTP errors** (`HTTP error: status=NNN`): The page URL itself returned a non-2xx status (e.g., 404 page not found)
+- **API response errors** (`API response error: GET /api/... → NNN`): An API call made during page load returned a non-2xx status, with the server's response body included
+
+API response errors are the most actionable — they show the exact endpoint that failed and what the server returned. When you see one, read the scenario's seed data and verify that the IDs in the URL match IDs created by the seed. For example, if the URL is `/page/items/abc-123` but the seed creates items with ID `item-1`, the API call to `/api/items/abc-123` will return 404.
+
+### Dependents returning nothing
+
+`codeyam editor dependents <Entity>` requires the import graph to be built first. Run:
+
+```bash
+codeyam editor analyze-imports                           # all entities
+codeyam editor analyze-imports app/components/Foo.tsx    # single file
+codeyam editor analyze-imports app/components/Foo.tsx app/components/Bar.tsx  # multiple files
+```
+
+Then retry `dependents`. The import graph persists in the database.
+
+### Database missing after clone
+
+This is expected — `db.sqlite3` is gitignored. Running `codeyam editor` detects this state (config.json exists, DB doesn't) and automatically runs `init --force` to rebuild the database and sync scenarios from the manifest.
+
+### Dev server not starting
+
+Check if another process holds the port:
+
+1. Look at `.codeyam/server-state.json` for the PID and port
+2. Kill any stale process
+3. Restart with `codeyam editor` (the editor command starts the server)
+
+### Step validation errors
+
+Each step has prerequisites. If a step refuses to run:
+
+1. Run `codeyam editor steps` to see which steps are complete
+2. Complete the prerequisite steps first
+3. Don't skip steps — the workflow is sequential
+
+### Dimension mismatch
+
+If previews look wrong or captures fail:
+
+- Check `screenSizes` in `.codeyam/config.json` for valid dimension names
+- Scenario `dimensions` must reference names defined in `screenSizes`
+- Preview commands must also include `dimension` — don't omit it
+
+### Preview not updating
+
+If changes aren't reflected in the preview:
+
+- The dev server may need to rebuild — check terminal output for compilation errors
+- Hard-refresh the preview: `codeyam editor preview '{"path":"<current-path>","dimension":"<dimension>","forceRefresh":true}'`
+- Check `codeyam editor client-errors` for runtime errors blocking render
+
+## Anti-Patterns
+
+**Don't loop audit/analyze-imports.** If audit fails, fix the underlying issues (missing scenarios, failing tests). Running audit repeatedly without fixing anything wastes time.
+
+**Don't use `prisma db push --force-reset`.** This drops all data. Instead, add `@default()` values for new required columns, or make them optional (`Int?`). Use `npm run db:push`.
+
+**Don't hardcode viewport dimensions.** Always reference named dimensions from `screenSizes` in config.json (e.g., `"Desktop"`). Don't use raw pixel values like `1440x900`.
+
+**Don't use bash heredocs for JSON.** Braces and quotes in heredocs trigger Claude Code security warnings. Use the **Write tool** to create `.codeyam/tmp/scenario.json`, then `codeyam editor register @.codeyam/tmp/scenario.json`.
+
+**Don't blanket-ignore `.codeyam` in `.gitignore`.** Only machine-local files are ignored with granular patterns. Shared files (`config.json`, `editor-scenarios/`, etc.) must be committable.
+
+**Don't register scenarios for unbuilt features.** If the component or page doesn't exist yet, the scenario will capture a blank page. Build the component first, then create scenarios for what it actually renders.

package/codeyam-cli/templates/design-systems/clean-dashboard-design-system.md

@@ -0,0 +1,255 @@
+# Clean Dashboard Design System
+
+> Minimal, information-dense UI. Subtle depth via soft shadows and thin borders. For any web or mobile app.
+
+## Philosophy
+
+High data clarity, minimal chrome. Neutral palette with restrained color accents. Soft shadows and thin borders create depth without visual weight. Professional, calm motion. Consistent 4px grid.
+
+**Rules:**
+
+1. Cards use `var(--bg-surface)` — never hardcoded or colored backgrounds
+2. Text hierarchy: primary → secondary → tertiary (never skip levels)
+3. No drop shadows on elements already inside a card
+4. Max 2 font weights per card
+5. Both light and dark mode required via `data-theme` attribute
+
+---
+
+## Colors
+
+### Light Mode
+
+```css
+[data-theme='light'] {
+  --bg-base: #f7f8fa; /* page background */
+  --bg-surface: #ffffff; /* cards, panels */
+  --bg-overlay: #ffffff; /* modals, dropdowns */
+  --bg-muted: #f2f3f7; /* hover states, inactive */
+  --bg-active: #eef2ff; /* selected items */
+
+  --text-primary: #1a1b25;
+  --text-secondary: #6b7280;
+  --text-tertiary: #9ca3af;
+  --text-disabled: #c4c7ce;
+
+  --border: #e8e9ed;
+  --border-strong: #d1d3db;
+
+  --shadow-sm: 0 1px 3px rgba(0, 0, 0, 0.06), 0 1px 2px rgba(0, 0, 0, 0.04);
+  --shadow-md: 0 4px 12px rgba(0, 0, 0, 0.08);
+}
+```
+
+### Dark Mode
+
+```css
+[data-theme='dark'] {
+  --bg-base: #14141f;
+  --bg-surface: #1e1e2e;
+  --bg-overlay: #252537;
+  --bg-muted: #252537;
+  --bg-active: #2d2d45;
+
+  --text-primary: #e8e9f0;
+  --text-secondary: #9899aa;
+  --text-tertiary: #5e5f72;
+  --text-disabled: #3a3a50;
+
+  --border: #2a2a3e;
+  --border-strong: #383856;
+
+  --shadow-sm: 0 1px 3px rgba(0, 0, 0, 0.3);
+  --shadow-md: 0 4px 12px rgba(0, 0, 0, 0.4);
+}
+```
+
+Respect `@media (prefers-color-scheme: dark)` on `:root:not([data-theme="light"])`.
+
+### Accents
+
+```css
+/* These don't change between modes */
+--green-a: #34d399;
+--green-b: #a7f3d0; /* positive states */
+--red: #f87171; /* negative states */
+--purple-a: #9b8afb;
+--purple-b: #c4b5fd;
+--blue-a: #60a5fa;
+--blue-b: #bae6fd;
+--yellow: #fcd34d;
+```
+
+### Semantic
+
+```css
+--success-bg: var(--green-b);
+--success-text: #065f46;
+--danger-bg: #fee2e2;
+--danger-text: #991b1b;
+--warning-bg: #fef9c3;
+--warning-text: #854d0e;
+```
+
+### Ordered Palette
+
+```css
+/* For any categorical sequence: tags, categories, avatars, etc. */
+--palette-1: #6c8ef5; /* blue-purple */
+--palette-2: #34d399; /* green */
+--palette-3: #f87171; /* red */
+--palette-4: #fbbf24; /* yellow */
+--palette-5: #a78bfa; /* purple */
+--palette-6: #22d3ee; /* cyan */
+```
+
+---
+
+## Typography
+
+**Font stack:** `'Inter', sans-serif`
+
+| Style   | Size | Weight  | Notes                 |
+| ------- | ---- | ------- | --------------------- |
+| Display | 48px | 600     | Large emphasis values |
+| 2XL     | 24px | 400/600 | Section headings      |
+| LG      | 18px | 400/600 | Card titles           |
+| SM      | 14px | 400/600 | Body, labels          |
+| XS      | 12px | 400/600 | Captions, timestamps  |
+
+---
+
+## Spacing & Radius
+
+Base unit: 4px. Scale: 4, 8, 12, 16, 20, 24, 32, 40px.
+
+| Context              | Value       |
+| -------------------- | ----------- |
+| Card padding         | `20px 24px` |
+| Gap between cards    | 16px        |
+| Gap between sections | 24px        |
+
+```css
+--radius-sm: 6px; /* badges, chips */
+--radius-md: 8px; /* inputs, small cards */
+--radius-lg: 12px; /* cards, panels */
+--radius-xl: 16px; /* large containers */
+--radius-full: 9999px; /* pills, avatars */
+```
+
+---
+
+## Layout
+
+### Common Patterns
+
+- **Sidebar:** 200px fixed, `--bg-surface`, right border
+- **Top bar:** 52px height, `--bg-surface`, bottom border. Contains: breadcrumbs (left), search (center), actions (right)
+- **Side panel:** 260px fixed, `--bg-surface`, left border (optional, toggle on small viewports)
+- **Main content:** flex-1, `--bg-base`, 24px padding
+
+### Navigation States
+
+- Section labels: XS, `--text-tertiary`, uppercase, `letter-spacing: 0.08em`
+- Nav items: SM, `--text-secondary`, hover → `--bg-muted`
+- Active item: `--bg-active`, `--text-primary`, weight 600
+- Nested indent: 16px
+
+### Mobile / Small Viewport
+
+- Sidebar collapses to hamburger menu or bottom tab bar
+- Side panel becomes slide-over or hidden
+- Cards stack single-column, full width, reduce padding to 16px
+- Top bar simplified: hamburger + key actions only
+
+---
+
+## Components
+
+### Card
+
+```css
+.card {
+  background: var(--bg-surface);
+  border: 1px solid var(--border);
+  border-radius: var(--radius-lg);
+  padding: 20px 24px;
+  box-shadow: var(--shadow-sm);
+}
+```
+
+**Variants:** none — cards are always neutral surface color.
+
+**Interactive states:** hover → `--bg-muted` background or `--shadow-md`. No transform.
+
+### Value Card
+
+Card with: label (SM, `--text-secondary`), emphasized value (Display 48px, semibold), optional trend indicator. Positive: `--green-a` + `↗`. Negative: `--red` + `↘`. Trend text: XS, weight 500.
+
+### Button
+
+```css
+.btn {
+  padding: 0 14px;
+  border-radius: var(--radius-md);
+  font-weight: 500;
+  font-size: 13px;
+  border: none;
+  cursor: pointer;
+}
+/* Hover: 8% brightness shift. Disabled: 40% opacity, not-allowed. */
+```
+
+| Variant      | Background       | Text               | Border/Shadow                    |
+| ------------ | ---------------- | ------------------ | -------------------------------- |
+| Filled       | `--text-primary` | `--bg-base`        | none                             |
+| Filled muted | `--bg-muted`     | `--text-primary`   | none                             |
+| Outline      | transparent      | `--text-primary`   | `1px solid var(--border-strong)` |
+| Ghost        | transparent      | `--text-secondary` | none                             |
+
+| Size         | Padding     | Font Size |
+| ------------ | ----------- | --------- |
+| SM           | `6px 10px`  | 12px      |
+| MD (default) | `8px 14px`  | 13px      |
+| LG           | `11px 18px` | 14px      |
+
+Icon-only: square at size height. Split button: text + chevron with 1px divider.
+
+### Badge / Pill
+
+`border-radius: var(--radius-sm)` for chips, `--radius-full` for pills. Use accent colors at low opacity for backgrounds.
+
+### Input
+
+`--bg-surface`, `1px solid var(--border)`, `--radius-md`, SM text. Focus: `--border-strong` or accent ring.
+
+### Table / Data Row
+
+Rows 32px height, `border-bottom: var(--border)`. Labels SM, `--text-secondary`. Hover → `--bg-muted`.
+
+---
+
+## Motion
+
+```css
+--transition-fast: 100ms ease; /* hover states */
+--transition-base: 180ms ease; /* general transitions */
+--transition-slow: 280ms ease-in-out; /* panels, overlays */
+```
+
+Calm and professional — no bounce or spring. Subtle opacity and position transitions only.
+
+---
+
+## Checklist
+
+- [ ] Page bg is `--bg-base`, cards are `--bg-surface` — no hardcoded colors
+- [ ] Both `data-theme="light"` and `"dark"` fully supported
+- [ ] Text uses primary/secondary/tertiary hierarchy consistently
+- [ ] All spacing on 4px grid
+- [ ] No colored card backgrounds (except active-state chips)
+- [ ] No shadows on elements inside cards
+- [ ] Max 2 font weights per card
+- [ ] Motion is subtle and fast — no bounce effects
+- [ ] Icons are outlined, 1.5px stroke, inherit currentColor
+- [ ] Ordered palette colors used consistently for categorical items