@discourser/design-system 0.22.2 → 0.22.4

package/docs/context-share/STORY-001-VALIDATION-PASSED.md

@@ -0,0 +1,192 @@
+# STORY-001 Validation Report — PASSED ✅
+
+**Date:** 2026-02-10
+**Validator:** Claude Code (corrected by user)
+**Script:** `scripts/test-storybook-mcp.sh`
+
+## Executive Summary
+
+**STORY-001 PASSES all acceptance criteria.** The Storybook MCP server successfully provides queryable documentation for AI agents through TWO manifest files:
+
+1. **components.json** (125KB) - Component stories and react-docgen output
+2. **docs.json** (1.1MB) - **Full MDX documentation content** ← **This was initially missed**
+
+## Initial Error & Correction
+
+### What Went Wrong
+The initial validation script ONLY checked `components.json` and concluded the MCP server was unsuitable because react-docgen failed on Ark UI compound components. **This conclusion was wrong.**
+
+### What Was Missed
+The script completely ignored `storybook-static/manifests/docs.json`, which contains **57 full MDX documentation files** with:
+- Complete component implementation guidelines (37 entries)
+- Decision trees for component selection
+- Correct vs wrong TypeScript code patterns
+- Compound component APIs (Dialog.Root, Dialog.Trigger, etc.)
+- Foundation documentation (Colors, Typography, Spacing, Elevation)
+- Token references and semantic usage
+- Skills documentation for AI agents
+
+### User Correction
+The user correctly identified that the `@storybook/addon-mcp` exposes 4 MCP tools, not 2:
+
+**Dev toolset:**
+1. `get_ui_building_instructions` - Story writing guidelines
+2. `preview-stories` - Visual verification URLs
+
+**Docs toolset (enabled via `experimentalComponentsManifest: true`):**
+3. `list-all-documentation` - Lists ALL components AND standalone docs
+4. `get-documentation` - Returns documentation from **BOTH** manifests
+
+The `get-documentation` tool checks BOTH manifests and returns whichever matches the requested ID.
+
+## Validation Results
+
+### ✅ Component Manifest (react-docgen)
+
+| Component | Stories | Props | react-docgen Status |
+|-----------|---------|-------|---------------------|
+| Dialog | 4 | 0 | ❌ "No component definition found" (expected) |
+| Select | 4 | 0 | ⚠️ No props extracted (expected) |
+| Popover | 4 | 4 | ⚠️ Wrong component (Button props) |
+| Accordion | 4 | 4 | ⚠️ Wrong component (Button props) |
+
+**Verdict:** react-docgen fails on Ark UI compound components (withContext HOCs). This is **expected and documented behavior**. Story code snippets work perfectly.
+
+### ✅ Docs Manifest (MDX Content) — THE CRITICAL PART
+
+| Documentation Type | Count | Example Sizes |
+|--------------------|-------|---------------|
+| Component guidelines | 37 | Select: 52,057 chars<br>Popover: 38,555 chars<br>Dialog: 30,847 chars<br>Typography: 20,048 chars |
+| Foundation docs | 4 | Colors: 13,106 chars<br>Typography: 10,616 chars |
+| Skills docs | 6 | Component patterns, Design language, Panda recipes |
+| Other docs | 10 | Figma Make guides, Examples |
+| **Total** | **57** | **1.1MB of MDX content** |
+
+#### Dialog Documentation Sample
+
+```typescript
+// ✅ Use Dialog for critical confirmations
+<Dialog.Root open={open} onOpenChange={setOpen}>
+  <Dialog.Trigger>
+    <Button variant="filled">Delete Account</Button>
+  </Dialog.Trigger>
+  <Dialog.Content>
+    <Dialog.Title>Delete Account?</Dialog.Title>
+    <Dialog.Description>This action cannot be undone.</Dialog.Description>
+    <Dialog.CloseTrigger>
+      <Button variant="text">Cancel</Button>
+    </Dialog.CloseTrigger>
+  </Dialog.Content>
+</Dialog.Root>
+
+// ❌ Don't use Dialog for navigation - use Drawer
+<Dialog.Root>
+  <Dialog.Content>
+    <nav>...</nav>
+  </Dialog.Content>
+</Dialog.Root>  // Wrong - navigation shouldn't be modal
+```
+
+**Verdict:** The MDX documentation provides **richer information than auto-generated prop tables** ever could. This includes:
+- ✅ Decision trees (when to use Dialog vs Drawer vs Popover vs Tooltip)
+- ✅ Full TypeScript examples with correct/wrong patterns
+- ✅ Exact import paths (`import { Dialog } from '@discourser/design-system'`)
+- ✅ Compound component APIs (all sub-components documented)
+- ✅ Size variants and use cases
+- ✅ Accessibility requirements
+- ✅ Token references and semantic usage
+
+## STORY-001 Acceptance Criteria Assessment
+
+| Criterion | Status | Details |
+|-----------|--------|---------|
+| MCP addon installed and configured | ✅ PASS | `@storybook/addon-mcp` in `.storybook/main.ts`<br>`experimentalComponentsManifest: true` enabled |
+| Component stories have code snippets | ✅ PASS | 24 components with 4 stories each (avg)<br>Full TypeScript examples in `stories[].snippet` |
+| react-docgen props for compound components | ⚠️ EXPECTED FAIL | Known limitation: react-docgen can't parse `withContext` HOCs |
+| **MDX docs are queryable via MCP** | ✅ PASS | **57 documentation entries in `docs.json`** |
+| **Component guidelines have full content** | ✅ PASS | **37 component guidelines with 10K-52K chars each** |
+| **Foundation docs accessible** | ✅ PASS | **Colors, Typography, Spacing, Elevation all present** |
+
+## Overall Verdict
+
+### ✅ **STORY-001 PASSED**
+
+**Reason:** The MCP server provides **exactly what Kai needs** through the docs manifest:
+1. The `get-documentation` tool serves content from BOTH manifests
+2. When react-docgen fails (expected), hand-written MDX docs provide richer information
+3. Dialog doc: 30K+ chars with decision trees, patterns, APIs
+4. Select doc: 52K+ chars with comprehensive guidance
+5. AI agents get **contextual guidance**, not just type signatures
+
+## Implications for Kai Agent Initiative
+
+### Risks Mitigated
+✅ **Original risk:** "MCP endpoint may not provide useful docgen for compound components"
+✅ **Resolution:** MDX documentation IS queryable and provides superior guidance
+
+### Architecture Validation
+✅ **Storybook as single source of truth** — Confirmed working
+✅ **MCP as query interface** — Confirmed working
+✅ **Kai can consume both stories and docs** — Confirmed possible
+
+### Next Steps
+1. ✅ Mark STORY-001 as PASSED
+2. ✅ Kai can query `get-documentation` for component guidance
+3. ✅ Phase 1 Panda CSS Layout MDX docs will auto-appear in manifest
+4. ✅ Kai's sidecar knowledge may not need to duplicate Storybook content
+
+## Key Documentation by Component
+
+```bash
+# Component guidelines (selection)
+documentation-guidelines-99-select--docs       52,057 chars
+documentation-guidelines-99-popover--docs      38,555 chars
+documentation-guidelines-99-dialog--docs       30,847 chars
+documentation-guidelines-99-accordion--docs    25,221 chars
+documentation-guidelines-99-typography--docs   20,048 chars
+documentation-guidelines-99-colors--docs       15,091 chars
+documentation-guidelines-99-icon-button--docs  14,661 chars
+documentation-guidelines-99-button--docs       13,398 chars
+
+# Foundation docs
+foundations-colors--docs                       13,106 chars
+foundations-typography--docs                   10,616 chars
+foundations-elevation--docs                     8,443 chars
+foundations-spacing--docs                       7,892 chars
+
+# Skills docs
+documentation-claude-skills-99-panda-recipes   12,334 chars
+documentation-claude-skills-99-component-patterns 11,567 chars
+documentation-claude-skills-99-design-language  9,823 chars
+```
+
+## Lessons Learned
+
+1. **Always check ALL manifest files** — Don't assume one manifest tells the whole story
+2. **Read the source code** — The `@storybook/mcp` source shows TWO manifests are loaded
+3. **MDX > auto-generated docs** — Hand-written guidelines provide context that type inference can't
+4. **Compound components need different strategies** — react-docgen limitations are well-known; MDX is the solution
+
+## Files Generated
+
+- `tmp/mcp-test-results/components.json` - Component manifest (125KB)
+- `tmp/mcp-test-results/docs.json` - **Docs manifest (1.1MB)** ← The important one
+- `tmp/mcp-test-results/*-sample.txt` - Content previews
+
+## Verification Command
+
+```bash
+# Run the corrected validation test
+./scripts/test-storybook-mcp.sh
+
+# Manually verify docs.json content
+jq -r '.docs["documentation-guidelines-99-dialog--docs"].content' \
+  storybook-static/manifests/docs.json | head -100
+
+# List all documentation entries
+jq -r '.docs | keys[]' storybook-static/manifests/docs.json
+```
+
+---
+
+**Conclusion:** The Storybook MCP server is **fully functional** for the Kai agent initiative. The initial assessment was incorrect because it only examined half of what the MCP server provides. With both manifests validated, STORY-001 acceptance criteria are met.

package/docs/context-share/STORY-002-IMPLEMENTATION-COMPLETE.md

@@ -0,0 +1,161 @@
+# STORY-002: Shadow Token Architecture Fix — COMPLETE ✅
+
+## Summary
+Successfully unified the shadow token system by chaining semantic tokens (xs-2xl) to M3 base tokens (level0-5), eliminating the parallel Park UI shadow system.
+
+## Changes Implemented
+
+### 1. `src/preset/shadows.ts` ✅
+**Before:** Independent Park UI shadow values with hardcoded colors
+```ts
+xs: { value: { base: '0px 1px 2px {colors.neutral.a6}...' } }
+sm: { value: { base: '0px 2px 4px {colors.neutral.a4}...' } }
+```
+
+**After:** Semantic tokens chained to M3 base tokens
+```ts
+xs: { value: '{shadows.level1}' }
+sm: { value: '{shadows.level2}' }
+md: { value: '{shadows.level3}' }
+lg: { value: '{shadows.level4}' }
+xl: { value: '{shadows.level5}' }
+'2xl': { value: '{shadows.level5}' }
+```
+
+**Result:** Semantic tokens now reference base M3 elevation values, creating proper token chain.
+
+### 2. `src/preset/recipes/button.ts` ✅
+**Changes:** Switched from base tokens to semantic tokens (3 lines)
+- Line 108: `boxShadow: 'level2'` → `boxShadow: 'sm'`
+- Line 112: `boxShadow: 'level3'` → `boxShadow: 'md'`
+- Line 115: `boxShadow: 'level1'` → `boxShadow: 'xs'`
+
+**Result:** Button recipe now uses semantic tokens consistently with other components.
+
+### 3. `src/stories/foundations/Elevation.mdx` ✅
+**Added:** Three-layer architecture explanation
+- Layer 1: Base tokens (level0-5) from M3 spec
+- Layer 2: Semantic tokens (xs-2xl) referencing base tokens
+- Layer 3: Component usage with semantic tokens only
+
+**Updated:** All code examples to use semantic tokens
+- Interactive states: `level1`/`level2` → `xs`/`sm`
+- Basic elevation: `level1` → `xs`
+- Interactive button: `level1`/`level2`/`level3` → `xs`/`sm`/`md`
+- Modal overlay: `level3` → `md`
+
+## Verification Results
+
+### ✅ Build Successful
+```bash
+$ pnpm build:panda
+✔️ styled-system/css
+✔️ styled-system/tokens
+✔️ styled-system/patterns
+✔️ styled-system/recipes
+✔️ styled-system/jsx
+```
+
+### ✅ No Base Tokens in Recipes
+```bash
+$ grep -r "boxShadow: 'level" src/preset/recipes/
+# Returns: 0 results ✓
+```
+
+### ✅ Files Unchanged (as required)
+- `src/languages/transform.ts` — Line 27 still registers shadows from elevation.levels
+- `src/languages/material3.language.ts` — elevation.levels (level0-5) unchanged
+- `src/preset/shadows.ts` — inset token preserved (lines 30-35)
+- DesignLanguageContract — No changes
+- DTCG scripts/pipeline — No changes
+
+## Components Requiring Visual Verification
+
+**15 components use shadows** and should be verified in Storybook (light + dark themes):
+
+1. **button** — Uses xs/sm/md (elevated variant)
+2. **card** — Uses lg
+3. **dialog** — Uses lg
+4. **drawer** — Uses lg
+5. **input** — Uses custom shadow (unchanged)
+6. **popover** — Uses lg
+7. **radio-group** — Uses custom inset shadow (unchanged)
+8. **select** — Uses md
+9. **skeleton** — Uses none (unchanged)
+10. **slider** — Uses xs
+11. **switch** — Uses xs
+12. **tabs** — Uses custom inset shadow (unchanged)
+13. **textarea** — Uses custom shadow (unchanged)
+14. **toast** — Uses lg
+15. **tooltip** — Uses sm
+
+### Visual Check Instructions
+```bash
+pnpm dev  # Start Storybook at localhost:6006
+```
+
+For each component above:
+1. Open component story in Storybook
+2. Check light theme — shadows should match M3 elevation levels
+3. Check dark theme — shadows should match M3 elevation levels
+4. Verify interactive states (hover/active) show appropriate shadow changes
+
+## Token Architecture Flow
+
+```
+Material3Language (material3.language.ts)
+  ↓
+elevation.levels.level0-5  (M3 shadow values)
+  ↓
+transform.ts (line 27: shadows: objectToTokens(language.elevation.levels))
+  ↓
+Base Tokens (level0-5 registered in Panda)
+  ↓
+shadows.ts (semantic tokens reference base tokens)
+  ↓
+Semantic Tokens (xs→level1, sm→level2, md→level3, lg→level4, xl/2xl→level5)
+  ↓
+Component Recipes (button, card, dialog, etc.)
+  ↓
+React Components
+```
+
+## Acceptance Criteria Status
+
+| # | Criterion | Status |
+|---|-----------|--------|
+| 1 | shadows.ts updated with token references | ✅ Complete |
+| 2 | inset token unchanged | ✅ Verified |
+| 3 | Button recipe updated (level→semantic) | ✅ Complete |
+| 4 | grep -r "boxShadow: 'level" returns 0 | ✅ Verified |
+| 5 | transform.ts UNCHANGED | ✅ Verified |
+| 6 | DesignLanguageContract UNCHANGED | ✅ Verified |
+| 7 | DTCG scripts UNCHANGED | ✅ Verified |
+| 8 | pnpm build:panda succeeds | ✅ Passed |
+| 9 | Visual regression check needed | ⏳ Pending user verification |
+| 10 | Elevation.mdx updated | ✅ Complete |
+
+## Next Steps
+
+1. **User Action Required:** Run `pnpm dev` and perform visual verification of all 15 components listed above
+2. Test in both light and dark themes
+3. Verify interactive states (hover, active) show proper elevation changes
+4. Once verified, commit changes with message:
+   ```
+   fix: unify shadow token architecture - chain semantic to M3 base tokens
+
+   - Update semantic tokens (xs-2xl) to reference M3 base tokens (level0-5)
+   - Switch button recipe from base tokens to semantic tokens
+   - Update Elevation.mdx with three-layer architecture docs
+   - Remove all direct base token usage from component recipes
+
+   Implements STORY-002
+   Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
+   ```
+
+## Benefits
+
+- **Single source of truth:** All shadows now derive from M3 elevation spec
+- **Swappable design language:** Can replace M3 with another system by changing base token values
+- **Consistent naming:** Components use meaningful semantic names (xs-2xl) not arbitrary levels
+- **Maintainable:** Changes to elevation values only need updates in one place (material3.language.ts)