@discourser/design-system 0.22.4 → 0.24.0

package/docs/context-share/m3-token-pipeline-audit.md

@@ -1,125 +0,0 @@
-# M3 Token Pipeline Audit Report
-
-> **Date:** 2026-02-10
-> **Codebase:** Discourser Design System
-> **Scope:** Full Material 3 token pipeline — from `material-theme.json` through transforms, bridge files, preset, `panda.config.ts`, and generated `styled-system` output.
-
----
-
-## Executive Summary
-
-The pipeline is **mostly healthy** after the recent fixes. Shadow token chaining works correctly, error/red DEFAULT tokens resolve properly, and the three palettes with Radix bridge files (primary, neutral/gray, error/red) have complete 1-12, a1-a12, and semantic variant (solid/subtle/surface/outline/plain) coverage in both light and dark modes.
-
-**Three issues found** — one is a significant gap, one is a minor discrepancy, and one is a question for you to decide on.
-
----
-
-## Findings
-
-### 🔴 Finding 1: Secondary and Tertiary Have No Radix Bridge Files
-
-**Severity: Significant gap**
-
-The `src/preset/colors/` directory contains bridge files for primary, neutral, and error — but **no `m3-secondary.ts` or `m3-tertiary.ts`**. The colors index only exports:
-
-```ts
-export const colors = {
-  primary,   // ← has bridge (1-12, a1-a12, solid/subtle/surface/outline/plain)
-  neutral,   // ← has bridge
-  error,     // ← has bridge
-  gray: neutral,  // alias
-  red: error,     // alias
-};
-```
-
-**What exists for secondary/tertiary:** Only M3 tonal palette values (0, 10, 20, 30, 40, 50, 60, 70, 80, 90, 95, 99, 100) from the language transform, plus M3 semantic tokens (secondary, secondary.container, onSecondary, onSecondary.container) from `semantic-tokens.ts`.
-
-**What's missing:** The Radix-scale bridge (1-12 solid scale, a1-a12 alpha scale) and all Park UI semantic variants (solid.bg, solid.fg, subtle.bg, surface.bg, outline.bg, plain.bg, etc.).
-
-**Impact:** Any Park UI component using `colorPalette="secondary"` or `colorPalette="tertiary"` will fail to resolve tokens like `colorPalette.9`, `colorPalette.solid.bg`, etc. If no components currently use these palettes, this is latent. But Kai (or any developer) would hit this the moment they try to use secondary/tertiary with a Park UI recipe.
-
-**Fix:** Create `m3-secondary.ts` and `m3-tertiary.ts` following the exact pattern of `m3-primary.ts`, then add them to the colors index with appropriate aliases.
-
----
-
-### 🟡 Finding 2: `border` Token Discrepancy Between `panda.config.ts` and Preset
-
-**Severity: Minor — functionally OK, architecturally inconsistent**
-
-In `panda.config.ts`, the border token has **both** a root-level value and nested children:
-
-```ts
-border: {
-  value: { base: '{colors.gray.6}', _dark: '{colors.gray.6}' },  // root value ✅
-  default: { value: { base: '{colors.gray.6}', _dark: '{colors.gray.6}' } },
-  muted: { value: { base: '{colors.gray.4}', _dark: '{colors.gray.4}' } },
-},
-```
-
-In `src/preset/index.ts`, it has **only** nested children (no root value):
-
-```ts
-border: {
-  default: { value: { base: '{colors.gray.6}', _dark: '{colors.gray.6}' } },
-  muted: { value: { base: '{colors.gray.4}', _dark: '{colors.gray.4}' } },
-},
-```
-
-**Generated output:** Only `colors.border` exists as a CSS variable. `colors.border.default` and `colors.border.muted` do **not** appear in `styled-system/tokens/index.mjs`. This means `panda.config.ts` is the one that ran codegen, and the root value took precedence — the nested children got merged/flattened.
-
-**Impact:** Nobody currently references `border.default` or `border.muted` in any recipe or component (confirmed by grep). Park UI upstream also defines border as a simple flat token. So functionally this is fine. But the preset definition (which would be what gets published as a package) differs from the local config, and the nested structure isn't generating separate tokens.
-
-**Fix:** Align the two files. Recommendation: match Park UI upstream — make border a flat token with just a root value. Remove the unused `default` and `muted` nesting from both files.
-
----
-
-### 🟢 Finding 3: Confirmed Working — Shadow Token Chaining
-
-The recent elevation fix is fully operational:
-
-```
-shadows.xs  → resolves to → var(--shadows-level1)
-shadows.sm  → resolves to → var(--shadows-level2)
-shadows.md  → resolves to → var(--shadows-level3)
-shadows.lg  → resolves to → var(--shadows-level4)
-shadows.xl  → resolves to → var(--shadows-level5)
-shadows.2xl → resolves to → var(--shadows-level5)
-```
-
-No recipes reference `level` tokens directly. No raw hex colors found in any recipe. The three-layer architecture (M3 base → Park UI semantic → component) is intact.
-
----
-
-### 🟢 Finding 4: Confirmed Working — Error/Red DEFAULT Resolution
-
-`m3-error.ts` has a proper DEFAULT key:
-
-```ts
-DEFAULT: { value: { base: m3[40], _dark: m3[80] } },
-```
-
-Generated output shows both `colors.error` and `colors.red` resolve to CSS variables. The alias chain `red → error → m3 tonal palette` is intact.
-
----
-
-### 🟢 Finding 5: M3 Semantic Tokens — No Nesting Issues
-
-All M3 semantic tokens in `semantic-tokens.ts` use proper `DEFAULT` keys where they have children (surface.DEFAULT + surface.container, onSurface.DEFAULT + onSurface.variant, etc.). No orphaned nested structures without root values.
-
-The `outline` token (M3 semantic: outline.DEFAULT, outline.variant) does **not** collide with the per-palette `outline` semantic variant (primary.outline.bg, error.outline.bg, etc.) because they're at different paths in the token tree.
-
----
-
-## Items I Could NOT Verify (Require Running in the Project)
-
-- **`pnpm panda codegen` for fresh warnings** — The generated output I audited may be stale. Running codegen would confirm zero `Missing token` warnings.
-- **`pnpm test`** — Couldn't execute tests remotely. Test files exist for the language transform and should be run to confirm.
-
----
-
-## Recommendation: Priority Order
-
-1. **Create secondary/tertiary bridge files** — This is the real gap. Until these exist, those palettes are incomplete for Park UI consumption.
-2. **Align border token structure** — Quick cleanup, flatten to match Park UI upstream.
-3. **Run `pnpm panda codegen` and `pnpm test`** — Confirm clean output after any changes.
-4. **Consider whether secondary/tertiary need aliases** (like `gray → neutral` and `red → error`) — depends on whether Park UI recipes ever reference these by alternate names.

package/docs/context-share/storybook-mcp-kai-agent-revised-summary.md

@@ -1,211 +0,0 @@
-# Storybook MCP + Kai Agent Research — Revised Summary
-
-> **Date:** 2026-02-10
-> **Purpose:** Carry-forward context for next conversation session
-> **Start next chat with:** "Continuing Storybook MCP + Kai agent research — here's the revised summary"
-
----
-
-## What We're Building
-
-A Design Engineer BMAD agent ("Kai") that uses Storybook MCP as its single source of truth for the Discourser Design System, replacing the failed Figma-MCP-direct-to-code approach.
-
-```
-Figma MCP → visual intent only
-    ↓
-Kai (Design Engineer Agent)
-    ↓
-Storybook MCP (consolidated source)
-├── Components (Ark UI / Park UI)
-├── Layout Patterns (Panda CSS)
-├── Tokens (semantic + visual)
-└── Composition Guides
-    ↓
-Design Implementation Spec → Dev Agent (Amelia)
-```
-
----
-
-## Critical Discovery: Storybook Already at 10.2.8
-
-You upgraded Storybook to **10.2.8** (well past the 10.1.0 minimum for component manifest). This changes the timeline significantly — the SB upgrade phase is **already done**.
-
----
-
-## Current Storybook Inventory (Verified Live at localhost:6006)
-
-### Components WITH Stories (.stories.tsx) — 17 components
-All have Docs page + interactive controls + props table via docgen:
-
-| Component | Stories | Notes |
-|-----------|---------|-------|
-| **Avatar** | Has stories | — |
-| **Badge** | Has stories | — |
-| **Button** | Default, All Variants, Color Palettes, All Sizes, Loading States, Disabled | Props: variant, size, colorPalette, loading, disabled. Docgen working. |
-| **Card** | Basic, All Variants, With Image | — |
-| **Checkbox** | Has stories (under Form) | — |
-| **Dialog** | Default, Sizes, Placement, Long Content | Compound component (Ark UI) — stories work |
-| **IconButton** | Has stories | — |
-| **Input** | Has stories (under Form) | — |
-| **InputGroup** | Has stories (under Form) | — |
-| **Progress** | Has stories | — |
-| **RadioGroup** | Has stories (under Form) | — |
-| **Select** | Default, Sizes, Disabled, With Groups | — |
-| **Slider** | Has stories | — |
-| **Stepper** | Default, All Visual States, Sizes, Color Palettes, Interactive Demo, Linear Navigation, Vertical, Numbers Only | Comprehensive. Critical for onboarding. |
-| **Switch** | Has stories | — |
-| **Tabs** | Has stories | — |
-| **Toast** | Has stories | — |
-
-### Docs-Only Sections (MDX, no .stories.tsx)
-| Section | Contents |
-|---------|----------|
-| **Layout** | Docs-only folder |
-| **Form** | Grouping folder for Checkbox, Input, InputGroup, RadioGroup, Textarea |
-| **Typography** | Docs-only |
-| **Overlay** | Docs-only folder |
-| **Feedback** | Docs-only folder |
-| **Textarea** | Under Form group |
-
-### Documentation Section
-| Area | Contents |
-|------|----------|
-| **Figma Make** | Figma template guides |
-| **Guidelines** | ~25 per-component implementation guides (99-Button, 99-Card, etc.) with decision trees, right/wrong patterns, import paths, variant tables, props reference, code examples |
-| **Claude Skills** | Context engineering files for Claude Code |
-
-### Foundations (MDX docs)
-- Colors, Elevation, Spacing, Typography
-
-### Key Observations
-1. **Component stories already exist** — the original audit's "zero component stories" finding was outdated. This eliminates the biggest blocker.
-2. **Docgen is working** — props tables auto-generate with descriptions (e.g., colorPalette shows "Color palette (M3 colors)").
-3. **Guidelines section is the token bridge** — the 99-Button guide already documents variants, visual characteristics, and the M3 connection. This partially addresses the "TokenBridge.mdx" need.
-4. **Compound components work** — Dialog stories render correctly despite Ark UI's Root/Trigger/Content pattern.
-
----
-
-## What's NOT Done Yet
-
-1. **`@storybook/addon-mcp` not installed** — `/mcp` endpoint returns "Not Found"
-2. **`experimentalComponentsManifest` not enabled** — `/manifests/components.html` returns "Not Found"
-3. **Kai agent YAML not written**
-4. **Design Implementation Spec format not defined**
-
----
-
-## Revised Phases
-
-### Original Phases (from audit)
-| Phase | What | Status |
-|-------|------|--------|
-| 0 | Fix shadow token ambiguity | Still needed |
-| 1 | Create component stories | **DONE** — 17 components have stories |
-| 2 | Create TokenBridge.mdx | **Partially done** — Guidelines section covers much of this |
-| 3 | Add missing foundation docs | Still needed (Radii, layer styles) |
-| 4 | Upgrade Storybook 8→9 | **DONE** — already at 10.2.8 |
-
-### Revised Phases
-
-| Phase | What | Effort | Why |
-|-------|------|--------|-----|
-| **0** | Install `@storybook/addon-mcp` + enable `experimentalComponentsManifest` | Small | Unlocks MCP endpoint. SB 10.2.8 already supports it. |
-| **1** | Verify component manifest output | Small | Confirm docgen data flows through `/manifests/components.json`. Test compound component (Dialog) representation. |
-| **2** | Fix shadow token ambiguity | Small | `level1-5` vs `lg` — consolidate vocabulary |
-| **3** | Add missing foundation docs (Radii, layer styles) | Medium | Complete token documentation for Kai |
-| **4** | Define Kai agent YAML + Design Implementation Spec format | Medium | The agent definition and its output contract |
-| **5** | Evaluate Guidelines coverage gaps | Low priority | Guidelines already cover most components. Identify any missing entries for new components. |
-
-**Phases 1 and 4 (original) are eliminated.** The biggest blockers are gone.
-
----
-
-## Storybook MCP Addon — Version Requirements (Researched)
-
-| Capability | Min SB Version | Your Version | Status |
-|------------|---------------|--------------|--------|
-| Dev toolset (story URLs, build instructions) | 9.1.16 | 10.2.8 | ✅ Ready |
-| Docs toolset (component manifest, props, examples) | 10.1.0 | 10.2.8 | ✅ Ready (needs feature flag) |
-| Node.js requirement | 24+ | TBD | Verify |
-
-### To enable:
-```ts
-// .storybook/main.ts
-export default {
-  addons: ['@storybook/addon-mcp'],
-  features: {
-    experimentalComponentsManifest: true,
-    // Optional: experimentalCodeExamples: true,
-  },
-};
-```
-
-### Two MCP toolsets:
-1. **Dev toolset**: `get-ui-building-instructions`, `get-stories-urls` — needs .stories.tsx files ✅ (exist)
-2. **Docs toolset**: `list-all-components`, `get-component-details` — needs component manifest ✅ (SB version supports it)
-
----
-
-## Kai Agent — Structural Patterns (from existing BMAD agents)
-
-Analyzed `dev_agent.yaml` and `tea_agent.yaml`:
-
-```yaml
-agent:
-  webskip: true  # Used by dev and tea agents
-  metadata:
-    id: "_bmad/bmm/agents/{name}.md"
-    name: {PersonaName}
-    title: {Role}
-    icon: {emoji}
-    module: bmm
-    hasSidecar: false
-  persona:
-    role: {description}
-    identity: {core purpose}
-    communication_style: {voice}
-    principles: |
-      - Bullet list of core principles
-  critical_actions:
-    - "Mandatory behaviors with specific file paths"
-  menu:
-    - trigger: {XX} or fuzzy match on {keyword}
-      workflow: "{project-root}/_bmad/bmm/workflows/{path}/workflow.yaml"
-      description: "[XX] Name: Description"
-```
-
-Key patterns: Dev agent is ultra-succinct, file-path oriented, strict test requirements. TEA agent uses knowledge fragment loading via index CSV. Both have `critical_actions` that run before any work.
-
----
-
-## Panda CSS + Storybook Compatibility Notes
-
-- Vite builder: PostCSS config must use array syntax: `plugins: [require('@pandacss/dev/postcss')()]`
-- Import generated CSS in `.storybook/preview.ts`: `import '../src/index.css'`
-- Add Storybook files to panda.config.ts include: `"./stories/**/*.{js,jsx,ts,tsx}"`
-- Use `staticCss` to pre-generate recipe variants for Storybook
-- Use `.raw()` marker for args that need Panda style detection
-
----
-
-## Open Questions for Next Session
-
-1. **Node.js version** — Is Node 24+ available in your dev environment? Required for addon-mcp.
-2. **Component manifest with Ark UI compounds** — Does Dialog.Root/Trigger/Content pattern generate useful docgen data through the manifest? (Needs hands-on test after Phase 0)
-3. **Kai agent output format** — What should a "Design Implementation Spec" look like to feed the Dev agent?
-4. **Guidelines coverage** — Are there gaps between the 25 Guidelines entries and the 17 storied components?
-
----
-
-## Key Files
-
-| File | Location | Purpose |
-|------|----------|---------|
-| Storybook config | `.storybook/main.ts` | Add addon-mcp + feature flag here |
-| Token source | `src/preset/` | Colors, semantic-tokens, shadows, text-styles, layer-styles |
-| Recipes | `src/preset/recipes/` | 30 recipes |
-| Components | `src/components/` | 27 components |
-| Stories | Alongside components (verified working) | .stories.tsx files |
-| Foundation docs | `src/stories/foundations/` | Colors, Typography, Spacing, Elevation MDX |
-| Guidelines | Under Documentation section | 25+ component implementation guides |
-| Repo | `Tasty-Maker-Studio/Discourser-Design-System` v0.13.0+ | — |