# CMS-aiChemist Platform User Guide

> Technology-assisted visual design flow to dynamically managed, served, and interactive visual design deployment across new or existing projects for internal or external users.

**Platform**: [cms.chem.dev](https://cms.chem.dev) | **Content CMS**: [cms-content.chem.dev](https://cms-content.chem.dev) | **Reference**: [cms.chem.dev/ref/](https://cms.chem.dev/ref/)

---

## What CMS-aiChemist Is

CMS-aiChemist is a **multi-project design system orchestration platform**. It transforms visual design intent into live, token-driven, component-based frontends across any number of projects — each with their own brand, palette, and audiences — while sharing a common foundation of 66 components, 983 design tokens, and automated quality gates.

The core flow:

```
Visual Design (Penpot / Stitch / mockups / descriptions)
    ↓
Design Tokens (W3C DTCG standard)
    ↓
Shared Components (66 React primitives consuming tokens via CSS variables)
    ↓
Surfaces (Next.js interactive apps + Astro content sites)
    ↓
Production Deployment (PM2 + Caddy + auto-TLS + CI/CD)
```

Every project registered on the platform inherits the full component library and token pipeline, overriding only the tokens that define their brand. A wellness app and an investor relations portal share the same Button, Modal, and DataList components — they just look different because their tokens define different colors, typography, and spacing.

---

## Core Personas

### 1. External Evaluator / Stakeholder

**Entry point**: [cms.chem.dev](https://cms.chem.dev)

**Who**: Clients, partners, investors, or anyone assessing the platform's capabilities.

**What they see**: A polished landing page with:
- Platform capabilities overview (983 tokens, 66 components, 2 surfaces, AI orchestration)
- Live interactive component showcase (buttons, tabs, alerts, cards — running real code)
- Pipeline visualization: Penpot → Tokens → Components → Surfaces
- Persona-aware CTAs: "Start a New Project", "Browse Components", "Documentation", "Existing Projects"

**Key routes**:
| Route | Purpose |
|-------|---------|
| `/` | Landing — platform overview, live demos, entry point CTAs |
| `/pricing` | Pricing tiers and comparison |
| `/testimonials` | Social proof and case studies |
| `/compare` | Feature comparison matrix |
| `/kaleido-life` | Showcase: a real project's custom design system (129 tokens, teal/gold/navy) |
| `/kaleido-wellness` | Showcase: wellness dashboard surface |
| `/kaleido-score` | Showcase: life score MVP surface |
| `/kaleido-ir` | Showcase: investor relations dark theme |

**Primary workflow**: Browse → Understand capabilities → View live showcases → Contact or onboard.

---

### 2. New Project Owner (Onboarding)

**Entry point**: [cms.chem.dev/getting-started](https://cms.chem.dev/getting-started)

**Who**: Someone bringing a new project (app, site, dashboard) onto the platform.

**What they see**: A 4-step guided onboarding flow:

1. **Design Tokens** — Define your visual language in Penpot, export as DTCG JSON
2. **Build Pipeline** — Transform tokens into CSS custom properties automatically
3. **Use Components** — Import shared UI components that consume your tokens
4. **Deploy Surface** — Ship to Next.js or Astro — same components, same tokens

**Self-service wizard**: [cms.chem.dev/new-project](https://cms.chem.dev/new-project) — an interactive 4-step wizard with two modes:
- **"New Project"**: Describe → Visual Direction (Stitch/Penpot guidance) → Token Picker (live preview) → Register (CLI command + DTCG JSON)
- **"Migrate Existing"**: Describe Site → Extract & Map Tokens (auto-detect from URL + manual refinement) → Migration Checklist (search-and-replace tables) → Register

The wizard generates a ready-to-run CLI command and DTCG JSON — copy, paste, deploy.

**Three onboarding paths** (based on starting material):

#### Path A: From Text Concepts / Descriptions

Starting point: A written brief, product spec, or verbal description ("We need a wellness dashboard with a calming teal palette and glass-morphism effects").

**Self-service**: Use the [New Project Wizard](https://cms.chem.dev/new-project) in "New Project" mode:
1. Describe your project (name, ID, visual style description)
2. Visual Direction step shows your description and provides a copyable Stitch MCP prompt for AI-generated screens, plus Penpot links for manual design
3. Token Picker lets you choose primary/accent colors from 8 presets or hex input, fonts, and backgrounds — with a **live component preview** (Button, Card, Alert, Badge) updating in real-time
4. Register step generates the CLI command and DTCG JSON to copy and run

**CLI pipeline**:
```
Text description
    ↓  [AI-assisted: Stitch MCP generates visual concepts from prompts]
Stitch screen designs (7+ screens generated per session)
    ↓  [Extract: colors, typography, spacing, effects from generated designs]
DTCG token file (projects/{id}/tokens.json)
    ↓  [Pipeline: merge.py combines with foundation tokens]
Project-specific CSS variables + JSON
    ↓  [Components: 66 shared primitives consume the new tokens]
Live surface with project branding
    ↓  [Deploy: PM2 + Caddy + auto-TLS]
Production URL
```

**Real example**: Kaleido-Shenai was onboarded from a text concept → Stitch generated screens → 11 token overrides extracted → component showcase route deployed at `/kaleido-score`.

#### Path B: From Visual Concepts (URLs / Screenshots / Mockups)

Starting point: An existing design in Penpot, Figma export, screenshot, or mockup URL.

```
Visual reference (Penpot project / mockup / screenshot)
    ↓  [Extract: Penpot MCP reads design properties directly]
    ↓  [Or: manual token extraction from visual reference]
DTCG token file with color, typography, spacing, shadow values
    ↓  [Pipeline: build.py + merge.py]
Project-merged CSS + JSON
    ↓  [Route: scaffold via onboard-project.py]
Component showcase + project surface
    ↓  [Drift: design-drift.py validates token coverage 100%]
Production deployment
```

**Real example**: Kaleido-Life started from an existing Penpot project → Penpot MCP extracted 129 DTCG tokens → showcase surface built at `/kaleido-life` with custom teal/gold/navy palette.

#### Path C: From Existing Application with Static Design Elements

Starting point: A running app or site with hardcoded colors, fonts, and spacing that needs to move to dynamic design management.

**Self-service**: Use the [New Project Wizard](https://cms.chem.dev/new-project) in "Migrate Existing" mode:
1. Describe your existing site (URL, project ID, name, current visual style)
2. **Extract & Map Tokens** — click "Analyze Site" to auto-extract colors and fonts from the provided URL (server-side CSS parsing). The system fetches the page HTML, parses inline styles, `<style>` blocks, and linked stylesheets, then suggests token mappings (primary/accent colors, backgrounds, fonts). Click "Apply Extracted Values" to pre-populate, then adjust as needed. Alternatively, map all 7 tokens manually with free-form color pickers and font text inputs (not limited to presets). Live preview updates in real-time.
3. Migration Checklist auto-generates from your mapped tokens:
   - Color replacements table (your `#hex` → `var(--token-name)`)
   - Typography replacements (font-family swaps)
   - Component swaps table (CSS class patterns → shared UI components)
   - Import setup instructions
4. Register step generates the CLI command and DTCG JSON

**CLI pipeline**:
```
Existing application audit
    ↓  [Inventory: extract hardcoded values (hex colors, px values, font stacks)]
Map to DTCG token schema (color.primary.base, font.size.md, etc.)
    ↓  [Create: projects/{id}/tokens.json with extracted values as overrides]
Token pipeline generates CSS variables
    ↓  [Migrate: replace hardcoded values with var(--token-name) references]
    ↓  [Adopt: swap custom components for shared UI primitives where possible]
Application now consumes dynamic tokens
    ↓  [Register: onboard-project.py adds to registry + dashboard]
    ↓  [Monitor: design-drift.py tracks token coverage]
Managed via CMS-aiChemist from here forward
```

**Core value**: The existing app stops being a snowflake. Design changes propagate through token updates rather than find-and-replace across codebases.

**Key routes**:
| Route | Purpose |
|-------|---------|
| `/getting-started` | 4-step overview with resource links |
| `/new-project` | Interactive wizard (New Project + Migrate Existing modes) |

#### Onboarding Command

The wizard at `/new-project` generates this command for you — just copy and run:

```bash
python3 ops/pipeline/onboard-project.py my-project "My Project Name" \
  --surface nextjs \
  --route /my-project \
  --penpot-project <penpot-id> \
  --stitch-project <stitch-id> \
  --update-nav
```

This creates:
- Registry entry in `projects/registry.json`
- Token override template at `projects/my-project/tokens.json`
- Route scaffold at `apps/web/src/app/my-project/page.tsx`
- Documentation at `projects/my-project/README.md`
- Merged token output at `projects/my-project/output/`

---

### 3. Internal Developer

**Entry point**: [cms.chem.dev/dashboard](https://cms.chem.dev/dashboard)

**Who**: Developers building or maintaining surfaces on the platform.

**What they see**: Project dashboard with filterable grid (All / Active / Design / Frontend tabs), each project showing status, component count, and token coverage.

**Key routes**:
| Route | Purpose |
|-------|---------|
| `/dashboard` | All registered projects with status and metrics |
| `/dashboard/[id]` | Project detail — tokens, components, drift score |
| `/design-system` | Live token catalog: 69 colors, 10 type sizes, 13 spacing steps, 5 shadows |
| `/components` | Searchable component hub: 66 components in 8 categories with descriptions and family badges |
| `/components/[name]` | Enhanced component docs: props table, import snippet, metadata panel, live demo, prev/next nav |
| `/new-project` | Self-service project wizard (New Project + Migrate Existing modes) |
| `/docs` | Architecture docs, ADRs (7 including ADR-007 Storybook evaluation), token reference, handoffs |
| `/getting-started` | Onboarding guide with wizard CTAs |
| `/status` | Platform health: CI status, route counts, uptime |

**Primary workflow**: Dashboard → pick project → view/edit tokens → build → verify drift → deploy.

**Component development cycle**:
```
1. Browse /components (categorized hub with descriptions) or /design-system for existing primitives
2. Click any component to see: props table, import snippet, live demo, metadata panel (a11y, tokens, states, CMS bindings)
3. If component exists: use it, customize via tokens
4. If component needed: add to packages/ui/src/components/
5. Write tests: component + interaction + a11y (jest-axe)
6. Register in component-meta.ts with 16-field metadata
7. Create demo route wrapped in ComponentDocPage — auto-generates docs from metadata
8. Run drift check: python3 ops/pipeline/design-drift.py
9. Build + deploy: npx next build && pm2 restart cms-web
```

---

### 4. Designer

**Entry point**: [cms.chem.dev/design-system](https://cms.chem.dev/design-system)

**Who**: Designers working on visual language, token definitions, and component appearance.

**What they see**: Interactive design system catalog showing:
- **Colors**: 69 tokens across 8 groups (backgrounds, primary, accent, CTA, text, status, border)
- **Typography**: 10 sizes (xs–6xl), 4 weights, 3 font families
- **Spacing**: 13-step scale (0–96px)
- **Shadows**: 5 variants (sm, md, lg, glow, glowGreen)
- **Border radii**: 7 options (none–full)
- **Live component demos**: Button variants, Tabs, Alerts, Cards

**Key routes**:
| Route | Purpose |
|-------|---------|
| `/design-system` | Full token catalog with live previews |
| `/kaleido-life` | Example: project-specific token override (129 custom tokens) |
| `/ref/tokens/` | Raw token files: CSS variables + DTCG JSON |
| Penpot (`penpot.chem.dev`) | Source design tool — connected via MCP |

**Design-to-code workflow**:
```
Penpot design → Export DTCG JSON → Token pipeline → CSS variables → Components render with new tokens
```

---

### 5. Content Editor

**Entry point**: [cms-content.chem.dev](https://cms-content.chem.dev)

**Who**: Content editors managing blog posts, editorial content, and CMS-driven pages.

**What they see**: Astro 6 + EmDash CMS with:
- Landing page with platform features and stats
- Blog index with category badges (engineering, design, product, updates)
- Individual blog post pages with rich text

**Key routes**:
| Route | Purpose |
|-------|---------|
| `cms-content.chem.dev/` | Content surface landing |
| `cms-content.chem.dev/blog` | Blog index |
| `cms-content.chem.dev/blog/[slug]` | Individual posts |

**Content workflow**:
```
Write content → EmDash CMS (SQLite-backed) → Astro renders with shared components → Live at cms-content.chem.dev
```

---

### 6. Agent / Machine (Claude Code, CI/CD, APIs)

**Entry point**: [cms.chem.dev/ref/](https://cms.chem.dev/ref/) or [cms.chem.dev/status](https://cms.chem.dev/status)

**Who**: Claude Code sessions, CI pipelines, automated tools, downstream systems like GitReport.

**What they access**:
| Resource | URL |
|----------|-----|
| Token JSON (machine-readable) | `cms.chem.dev/ref/tokens/tokens.json` |
| Token CSS | `cms.chem.dev/ref/tokens/tokens.css` |
| Handoff documents | `cms.chem.dev/ref/handoffs/` |
| Architecture docs | `cms.chem.dev/ref/docs/` |
| Design briefs | `cms.chem.dev/ref/design/` |
| Platform status | `cms.chem.dev/status` |

**Brain integration workflow** (Claude Code sessions):
```
brain-pull.sh → Read local mirrors → Execute work → brain-push.sh → Update NotebookLM sources
```

---

## High-Value Workflows

### Workflow 1: Full Design-to-Deploy Pipeline

**Proven end-to-end** (Timeline component, 2026-04-06):

```
1. Research phase: brain-query.sh asks NotebookLM for design intent
2. AI design: Stitch MCP generates screens from text prompts
3. Token extraction: Pull colors, type, spacing from generated screens
4. Token pipeline: build.py → merge.py → CSS + JSON output
5. Component build: React primitive in packages/ui/
6. Route scaffold: page.tsx consuming the component
7. Test: vitest (component + interaction + axe a11y)
8. Drift check: design-drift.py validates 100/100
9. Build: npx next build
10. Deploy: pm2 restart cms-web
11. Verify: smoke tests + Lighthouse audit
12. Brain push: brain-push.sh records outcome
```

### Workflow 2: Project-Specific Visual Iteration

**For existing projects that need design changes**:

```
1. Edit: projects/{id}/tokens.json (change color.primary.base, font.size.lg, etc.)
2. Merge: python3 packages/tokens/merge.py
3. Build: cd apps/web && npx next build
4. Preview: localhost:3500/{project-route}
5. Drift: python3 ops/pipeline/design-drift.py
6. Deploy: pm2 restart cms-web
7. Live: https://cms.chem.dev/{project-route}
```

Token changes propagate to every component automatically — no code changes needed for visual updates.

### Workflow 3: Component Library Extension

**Adding a new shared primitive**:

```
1. Create: packages/ui/src/components/NewComponent.tsx
2. Export: packages/ui/src/index.ts
3. Metadata: Register in component-meta.ts (16 fields: family, props_schema, a11y, responsive, etc.)
4. Test: a11y.test.tsx + interactions.test.tsx + components.test.tsx
5. Showcase: apps/web/src/app/new-component/NewComponentShowcase.tsx (handcrafted demo)
6. Route: apps/web/src/app/new-component/page.tsx — wrap in <ComponentDocPage componentName="NewComponent">
   (auto-generates: breadcrumb, props table, import snippet, metadata panel, prev/next nav)
7. Register: Add to component-routes.ts for hub listing + navigation
8. Drift: Verify 100/100 with new component
9. Deploy: Rebuild both surfaces
```

All 5 registered projects can immediately use the new component.

### Workflow 4: Cross-Surface Content Publishing

```
1. Write: EmDash CMS (SQLite-backed, blog collection)
2. Render: Astro builds with shared React components as islands
3. Nav: Cross-site links connect cms.chem.dev ↔ cms-content.chem.dev
4. Deploy: pm2 restart cms-content
5. Live: cms-content.chem.dev/blog/[slug]
```

### Workflow 5: Automated Quality Gates (CI/CD)

Every push to master triggers 8 CI jobs:

| Job | Gate | Threshold |
|-----|------|-----------|
| build-web | Next.js compiles | Must pass |
| build-cms-theme | Astro compiles | Must pass |
| unit-tests | 661 tests (component + interaction + a11y) | All pass |
| typecheck-web | TypeScript strict mode | Zero errors |
| token-merge | 983 tokens build + merge across 5 projects | Must pass |
| design-drift | Token coverage score | >= 80/100 (currently 100) |
| lighthouse | Performance/A11y/BP/SEO audit on 15 routes | Budget thresholds |
| smoke-tests | Playwright route health on production | All 200s |

---

## The Internal/External Paradigm: How It Works Today and Going Forward

### Current State (2026-04-07)

Today, **both servers blend internal platform content with project-specific showcase content**:

**cms.chem.dev (Next.js)** serves:
- **Platform core**: Landing (`/`), Dashboard (`/dashboard`), Design System (`/design-system`), Components (`/components`), Docs (`/docs`), Getting Started (`/getting-started`), New Project Wizard (`/new-project`), Status (`/status`), Pricing (`/pricing`)
- **Project showcases**: `/kaleido-life`, `/kaleido-score`, `/kaleido-ir`, `/kaleido-wellness`
- **Component demos**: 55 individual component routes (`/button`, `/modal`, `/table`, etc.) — each with auto-generated docs: props table, import snippet, metadata panel, prev/next navigation

**cms-content.chem.dev (Astro)** serves:
- **Platform content**: Landing page, blog (engineering, design, product, updates)

This coexistence is intentional at this stage: the platform needs to **demonstrate** multi-project capabilities by showing real project surfaces alongside the tooling that created them. The Kaleido showcases are both the proof and the product.

### Intended Go-Forward Paradigm

The architecture is designed for a **hub-and-spoke separation** as the platform matures:

```
                        ┌─────────────────────────────────────────┐
                        │  CMS-aiChemist Platform (Hub)           │
                        │  cms.chem.dev                           │
                        │                                          │
                        │  Internal personas:                      │
                        │  - Dashboard: project management         │
                        │  - Design System: token catalog          │
                        │  - Components: component library         │
                        │  - Docs: architecture, ADRs              │
                        │  - Getting Started: onboarding           │
                        │  - Status: platform health               │
                        │                                          │
                        │  External personas:                      │
                        │  - Landing: capabilities overview        │
                        │  - Pricing, Compare, Testimonials        │
                        │  - Blog (via cms-content.chem.dev)       │
                        │                                          │
                        │  Shared infrastructure:                  │
                        │  - /ref/ (tokens, docs, handoffs)        │
                        │  - CI/CD (8 jobs)                        │
                        │  - Token pipeline (build + merge)        │
                        │  - 66 shared components                  │
                        └──────────────┬──────────────────────────┘
                                       │
              ┌────────────────────────┼────────────────────────┐
              │                        │                        │
    ┌─────────▼─────────┐  ┌──────────▼──────────┐  ┌─────────▼─────────┐
    │  Project A         │  │  Project B           │  │  Project C         │
    │  (e.g. Kaleido)    │  │  (e.g. Client Site)  │  │  (e.g. New Venture)│
    │                    │  │                      │  │                    │
    │  Own subdomain or  │  │  Own subdomain or    │  │  Own subdomain or  │
    │  own domain        │  │  own domain          │  │  own domain        │
    │                    │  │                      │  │  own domain        │
    │  Tokens: inherited │  │  Tokens: inherited   │  │  Tokens: inherited │
    │  + overrides       │  │  + overrides         │  │  + overrides       │
    │                    │  │                      │  │                    │
    │  Components:       │  │  Components:         │  │  Components:       │
    │  same 66 shared    │  │  same 66 shared      │  │  same 66 shared    │
    │  primitives        │  │  primitives          │  │  primitives        │
    └───────────────────-┘  └──────────────────────┘  └────────────────────┘
```

**For internal personas** (developers, designers, agents):
- The hub at `cms.chem.dev` remains the single control plane: dashboard, design system, component library, docs, onboarding, CI/CD status
- Project-specific routes (`/kaleido-life`, etc.) serve as **live previews within the hub** — showing how a project's tokens render with shared components
- The dashboard at `/dashboard/[id]` becomes the primary project management interface

**For external personas** (evaluators, end users, clients):
- Each project **graduates** to its own deployment when ready for production audiences
- A Kaleido end user visits `kaleido.app` (or similar), not `cms.chem.dev/kaleido-life`
- The hub showcases remain as portfolio/demo entries: "Here's what we built for Kaleido"
- `cms.chem.dev` itself is the platform's public face, with showcase routes serving as case studies

**For project-specific CMS content**:
- `cms-content.chem.dev` currently handles platform-level blog/editorial
- Project-specific content (e.g., Kaleido blog posts, documentation) would get their own EmDash instance or collections within the shared CMS, served at the project's own domain
- The EmDash seed schema supports this: collections are defined per project with distinct slugs

**The key architectural principle**: The hub never stops showing project previews — they're evidence of capability. But production-facing project surfaces deploy independently, consuming the same tokens and components via the shared packages. The pipeline, not the URL structure, is what ties everything together.

---

## Key Gaps and Opportunities

### Gap 1: No Project Graduation Path (High Priority)

**Current**: Projects live as routes within `cms.chem.dev`. There's no documented or tooled path for a project to "graduate" from `/kaleido-life` to `kaleido.chem.dev` or an external domain.

**Opportunity**: Build a graduation pipeline:
- `ops/pipeline/graduate-project.py` — generates standalone Next.js or Astro build consuming project-specific merged tokens
- Caddy config template for new subdomains
- PM2 app entry for the graduated surface
- The hub route becomes a "case study" page linking to the live project

**Impact**: This is the critical path from "demo platform" to "production multi-project system."

### Gap 2: No Live Token Editing UI (Medium Priority)

**Current**: Token changes require editing JSON files, running Python scripts, and rebuilding. Designers and non-technical users can't iterate on tokens without developer involvement.

**Opportunity**: A token editor at `/dashboard/[id]/tokens` that:
- Shows current token values with visual previews (color swatches, type samples)
- Allows overriding values with immediate preview
- Saves to `projects/{id}/tokens.json` and triggers merge + build
- Falls back to the foundation value when overrides are cleared

**Impact**: Enables designers to iterate without developer handoff — the core promise of a design system platform.

### Gap 3: No Real-Time Preview During Design Iteration (Medium Priority)

**Current**: Design changes require: edit tokens → run pipeline → rebuild → restart PM2 → verify. This is a 2-3 minute cycle.

**Opportunity**: Hot-reload token preview:
- Dev mode that watches `projects/{id}/tokens.json` for changes
- Triggers incremental CSS generation (no full rebuild)
- Next.js dev server reflects changes instantly via HMR

**Impact**: Reduces design iteration cycle from minutes to seconds.

### Gap 4: Project-Specific CMS Content Isolation (Medium Priority)

**Current**: `cms-content.chem.dev` serves platform-level blog content. There's no mechanism for project-specific content (e.g., Kaleido's own blog, documentation, or marketing pages).

**Opportunity**: EmDash supports multiple collections. Add per-project content collections:
- `blog-kaleido-life`, `docs-kaleido-life` etc.
- Or separate EmDash instances per project with shared theme
- Content routes at project subdomains

**Impact**: Completes the content story for graduated projects.

### Gap 5: No Automated Penpot-to-Token Extraction (Low-Medium Priority)

**Current**: Penpot MCP can read design properties, but token extraction is manual. A designer updates colors in Penpot, then someone manually creates the DTCG JSON.

**Opportunity**: Automated extraction pipeline:
- Penpot MCP reads project design properties
- Maps to DTCG schema automatically (color, typography, spacing, shadows)
- Generates `projects/{id}/tokens.json` diff
- PR or direct merge with review

**Impact**: Closes the loop between design tool and token pipeline — true design-to-code automation.

### Gap 6: Dashboard Mock Data (Low Priority)

**Current**: `/dashboard` shows hardcoded mock data (10 projects with placeholder metrics). The registry has 5 real projects, but the dashboard doesn't read from it.

**Opportunity**: Wire dashboard to `projects/registry.json`:
- Read real project metadata (name, surface, route, component count, token override count)
- Pull drift scores from latest drift report
- Show real CI status via GitHub API
- Link each project card to `/dashboard/[id]` with live data

**Impact**: Dashboard becomes a real management interface instead of a demo.

### Gap 7: FTP Static Mirror (Low Priority, Blocked)

**Current**: `ops/sync-static.sh` syncs tokens and docs to `static-site/` served at `/ref/`. FTP deployment to `ftp.chem.dev` is ready but DNS record not yet created.

**Opportunity**: Once DNS is configured:
- Push static mirror to FTP for external CDN or backup access
- Token JSON and CSS available at stable URLs for external consumers

**Impact**: External projects can consume tokens without accessing the platform directly.

### ~~Gap 8: Storybook or Enhanced Component Explorer~~ — RESOLVED (2026-04-07)

**Resolution**: Path B (metadata-enhanced component routes) was implemented. All 55 component demo pages now include:
- Breadcrumb navigation (Home > Components > [Name])
- Component header with family badge and description
- Import snippet in CodeBlock
- Props table (parsed from `props_schema` metadata)
- Existing handcrafted showcase (preserved)
- MetaPanel with 16 metadata fields (a11y, tokens, states, responsive, CMS bindings, etc.)
- Prev/next navigation

`/components` hub upgraded with descriptions and family badges per card.

Path A (Storybook) documented in [ADR-007](https://cms.chem.dev/ref/docs/decision-records/ADR-007-storybook-evaluation.md) for future reference. Conditions for revisiting: team growth (3+ devs), npm publication, visual regression CI, designer count exceeds 2.

### Gap 9: Self-Service New Project / Migration Wizard — RESOLVED (2026-04-07)

**Resolution**: Interactive wizard at `/new-project` with two modes:
- **New Project**: Describe → Visual Direction (Stitch/Penpot) → Token Picker (live preview) → Register
- **Migrate Existing**: Describe Site → Extract & Map Tokens (auto-detect from URL + manual) → Migration Checklist → Register

Closes the gap between "I have an idea" and `onboard-project.py`. Getting Started page updated with wizard CTAs. Extract & Map step fetches existing site CSS to auto-detect colors/fonts.

---

## Platform Numbers (2026-04-07)

| Metric | Value |
|--------|-------|
| Shared UI components | 66 |
| W3C DTCG design tokens | 983 |
| Registered projects | 5 |
| Next.js routes | 73 |
| Unit tests | 661 (component + interaction + a11y) |
| CI jobs | 8 (all green) |
| Design drift score | 100/100 |
| Lighthouse | P:97 A:95 BP:96 SEO:100 |
| Production surfaces | 2 (Next.js + Astro) |
| NotebookLM brain sources | ~32 |
| Stitch-generated screens | 7 |
| Token pipeline projects | 5 (each with merged output) |

---

## Quick Reference: Key URLs

| URL | What It Serves | Persona |
|-----|---------------|---------|
| `cms.chem.dev` | Platform hub — landing, dashboard, design system, components, docs | All |
| `cms.chem.dev/getting-started` | New project onboarding guide | New project owners |
| `cms.chem.dev/new-project` | Interactive wizard (New Project + Migrate Existing) | New project owners |
| `cms.chem.dev/dashboard` | Project management dashboard | Developers, managers |
| `cms.chem.dev/dashboard/[id]` | Project detail view | Developers |
| `cms.chem.dev/design-system` | Token catalog with live previews | Designers, developers |
| `cms.chem.dev/components` | Searchable component hub (66 components, descriptions + badges) | Developers |
| `cms.chem.dev/[component]` | Enhanced component docs (props, import, metadata, demo) | Developers |
| `cms.chem.dev/docs` | Architecture, ADRs, handoffs | Developers, agents |
| `cms.chem.dev/status` | Platform health and CI status | Agents, ops |
| `cms.chem.dev/ref/` | Raw tokens, docs, handoffs (file server) | Agents, CI/CD |
| `cms.chem.dev/kaleido-life` | Project showcase: Kaleido-Life design system | Evaluators |
| `cms-content.chem.dev` | EmDash CMS — blog and editorial content | Content editors |
| `cms-content.chem.dev/blog` | Blog index | All |
| `penpot.chem.dev` | Design tool (Penpot) | Designers |

---

## Quick Reference: Key Commands

```bash
# Onboard a new project
python3 ops/pipeline/onboard-project.py <id> "<name>" --surface nextjs --route /<id> --update-nav

# Build foundation tokens
python3 packages/tokens/build.py

# Merge all project tokens
python3 packages/tokens/merge.py

# Check design drift
python3 ops/pipeline/design-drift.py --ci --json > drift-report.json

# Run unit tests (661 tests)
cd packages/ui && npx vitest run

# Build and deploy Next.js
cd apps/web && npx next build && pm2 restart cms-web

# Build and deploy Astro
cd apps/cms-theme && npm run build && pm2 restart cms-content

# Sync static reference site
bash ops/sync-static.sh

# Query the brain (NotebookLM via Gemini bridge)
bash ops/brain/brain-query.sh "What are the priorities for the token pipeline?"

# Push learnings back to brain
bash ops/brain/brain-push.sh "Session Update - <title>" "<content>"

# Check brain source inventory
bash ops/brain/brain-status.sh
```