@discourser/design-system 0.22.2 → 0.22.4

package/docs/plans/2026-03-12-figma-token-export-rewrite.md

@@ -0,0 +1,504 @@
+# Figma Token Export Rewrite Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Rewrite `scripts/export-figma-tokens.ts` to generate three DTCG-compatible output files from `material3Language` with zero hardcoded values.
+
+**Architecture:** Single script with pure helper functions. Each output file is built by a dedicated builder function that reads exclusively from `material3Language`. The semantic key → Figma path mapping is handled by a single `semanticKeyToFigmaPath()` pure function. All three files are written to `dist/`, and `dist/figma-variables.json` is also copied to `tokens/tokens.json`.
+
+**Tech Stack:** TypeScript (ESM), tsx runner, Node.js `fs`/`path`, no new dependencies.
+
+---
+
+### Task 1: Add `figma:export` script to package.json
+
+**Files:**
+
+- Modify: `package.json`
+
+**Step 1: Add the script entry**
+
+In `package.json`, find the `"scripts"` block. Add after the last existing script entry:
+
+```json
+"figma:export": "tsx scripts/export-figma-tokens.ts"
+```
+
+**Step 2: Verify**
+
+```bash
+cd /Users/willstreeter/WebstormProjects/vibe-coding/shifu-project/Discourser-Design-System
+cat package.json | grep figma:export
+```
+
+Expected output: `"figma:export": "tsx scripts/export-figma-tokens.ts"`
+
+**Step 3: Commit**
+
+```bash
+git add package.json
+git commit -m "chore: add figma:export script to package.json"
+```
+
+---
+
+### Task 2: Rewrite scripts/export-figma-tokens.ts
+
+**Files:**
+
+- Modify: `scripts/export-figma-tokens.ts` (complete rewrite)
+
+**Step 1: Replace the entire file with this implementation**
+
+```typescript
+/**
+ * Export Design System Tokens for Figma
+ *
+ * Generates three DTCG-compatible output files from material3Language.
+ * Zero hardcoded values — all data sourced programmatically.
+ *
+ * Usage: pnpm figma:export
+ */
+
+import { material3Language } from '../src/languages/material3.language';
+import * as fs from 'fs';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const packageJsonPath = path.join(__dirname, '..', 'package.json');
+const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
+
+// ---------------------------------------------------------------------------
+// Helper: strip px suffix and convert to number
+// ---------------------------------------------------------------------------
+
+function px(value: string): number {
+  return parseFloat(value.replace('px', ''));
+}
+
+function ms(value: string): number {
+  return parseFloat(value.replace('ms', ''));
+}
+
+// ---------------------------------------------------------------------------
+// Helper: camelCase semantic key → Figma path (/ separator)
+// ---------------------------------------------------------------------------
+
+function semanticKeyToFigmaPath(key: string): string {
+  // Surface container variants
+  if (key === 'surfaceContainer') return 'surface/container';
+  if (key === 'surfaceContainerLow') return 'surface/container/low';
+  if (key === 'surfaceContainerLowest') return 'surface/container/lowest';
+  if (key === 'surfaceContainerHigh') return 'surface/container/high';
+  if (key === 'surfaceContainerHighest') return 'surface/container/highest';
+
+  // surfaceVariant / onSurfaceVariant
+  if (key === 'surfaceVariant') return 'surface/variant';
+  if (key === 'onSurfaceVariant') return 'onSurface/variant';
+
+  // outlineVariant
+  if (key === 'outlineVariant') return 'outline/variant';
+
+  // inverse*
+  if (key === 'inverseSurface') return 'inverse/surface';
+  if (key === 'inverseOnSurface') return 'inverse/onSurface';
+  if (key === 'inversePrimary') return 'inverse/primary';
+
+  // on*Container (e.g. onPrimaryContainer → onPrimary/container)
+  const onContainerMatch = key.match(/^(on[A-Z][a-z]+)Container$/);
+  if (onContainerMatch) {
+    return `${onContainerMatch[1]}/container`;
+  }
+
+  // *Container (e.g. primaryContainer → primary/container)
+  const containerMatch = key.match(/^([a-z][a-zA-Z]+)Container$/);
+  if (containerMatch) {
+    return `${containerMatch[1]}/container`;
+  }
+
+  // All others pass through as-is
+  return key;
+}
+
+// ---------------------------------------------------------------------------
+// Builder 1: Primitives collection — tonal palettes
+// ---------------------------------------------------------------------------
+
+type DtcgColorEntry = {
+  $type: 'color';
+  $value: Record<string, string>;
+};
+
+type DtcgNumberEntry = {
+  $type: 'number';
+  $value: Record<string, number>;
+};
+
+function buildPrimitives(): Record<string, DtcgColorEntry> {
+  const result: Record<string, DtcgColorEntry> = {};
+  const lang = material3Language;
+
+  for (const [paletteName, tones] of Object.entries(lang.colors)) {
+    for (const [tone, hex] of Object.entries(tones)) {
+      const key = `${paletteName}/${tone}`;
+      result[key] = {
+        $type: 'color',
+        $value: { Value: String(hex) },
+      };
+    }
+  }
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Builder 2: Semantic collection — light + dark modes
+// ---------------------------------------------------------------------------
+
+function buildSemantic(): Record<string, DtcgColorEntry> {
+  const result: Record<string, DtcgColorEntry> = {};
+  const lang = material3Language;
+
+  // Iterate light keys (semantic and semanticDark must have identical key sets)
+  for (const [key, lightValue] of Object.entries(lang.semantic)) {
+    const darkValue = (lang.semanticDark as Record<string, string>)[key];
+    const figmaPath = semanticKeyToFigmaPath(key);
+
+    result[figmaPath] = {
+      $type: 'color',
+      $value: {
+        Light: lightValue,
+        Dark: darkValue,
+      },
+    };
+  }
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Builder 3: Spacing & Shape collection — numeric tokens
+// ---------------------------------------------------------------------------
+
+function buildSpacingAndShape(): Record<string, DtcgNumberEntry> {
+  const result: Record<string, DtcgNumberEntry> = {};
+  const lang = material3Language;
+
+  // Spacing
+  for (const [key, value] of Object.entries(lang.spacing)) {
+    result[`spacing/${key}`] = {
+      $type: 'number',
+      $value: { Value: px(value) },
+    };
+  }
+
+  // Radii
+  for (const [key, value] of Object.entries(lang.shape.radii)) {
+    result[`radii/${key}`] = {
+      $type: 'number',
+      $value: { Value: px(value) },
+    };
+  }
+
+  // Border widths
+  for (const [key, value] of Object.entries(lang.border.widths)) {
+    result[`border/${key}`] = {
+      $type: 'number',
+      $value: { Value: px(value) },
+    };
+  }
+
+  // Durations
+  for (const [key, value] of Object.entries(lang.motion.durations)) {
+    result[`duration/${key}`] = {
+      $type: 'number',
+      $value: { Value: ms(value) },
+    };
+  }
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Builder 4: Effect styles — elevation
+// ---------------------------------------------------------------------------
+
+type ElevationEntry = {
+  value: string;
+  description: string;
+};
+
+const elevationDescriptions: Record<string, string> = {
+  level0: 'No elevation — flat surfaces',
+  level1: 'Cards at rest, contained buttons (semantic: xs)',
+  level2: 'Cards on hover, raised buttons (semantic: sm)',
+  level3: 'Dialogs, dropdowns, popovers (semantic: md)',
+  level4: 'Navigation drawers, modal sheets (semantic: lg)',
+  level5: 'FABs, tooltips, snackbars (semantic: xl)',
+};
+
+function buildEffectStyles(): { elevation: Record<string, ElevationEntry> } {
+  const elevation: Record<string, ElevationEntry> = {};
+  const lang = material3Language;
+
+  for (const [key, value] of Object.entries(lang.elevation.levels)) {
+    elevation[key] = {
+      value,
+      description: elevationDescriptions[key] ?? key,
+    };
+  }
+
+  return { elevation };
+}
+
+// ---------------------------------------------------------------------------
+// Builder 5: Text styles — typography
+// ---------------------------------------------------------------------------
+
+type TextStyleEntry = {
+  fontFamily: string;
+  fontSize: number;
+  fontWeight: number;
+  lineHeight: number;
+  letterSpacing: number;
+  figmaTextStyle: string;
+};
+
+function buildTextStyles(): Record<string, TextStyleEntry> {
+  const result: Record<string, TextStyleEntry> = {};
+  const lang = material3Language;
+
+  for (const [key, style] of Object.entries(lang.typography.scale)) {
+    const fontKey = style.fontFamily as 'display' | 'body' | 'mono';
+    const fontFamilyString = lang.typography.fonts[fontKey];
+    // Extract first font name before comma, strip quotes
+    const fontFamily = fontFamilyString
+      .split(',')[0]
+      .replace(/['"]/g, '')
+      .trim();
+
+    result[key] = {
+      fontFamily,
+      fontSize: px(style.fontSize),
+      fontWeight: Number(style.fontWeight),
+      lineHeight: px(style.lineHeight),
+      letterSpacing: px(style.letterSpacing),
+      figmaTextStyle: key,
+    };
+  }
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Main: assemble, write files, print summary
+// ---------------------------------------------------------------------------
+
+function ensureDir(filePath: string): void {
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+}
+
+function writeJson(filePath: string, data: unknown): void {
+  ensureDir(filePath);
+  fs.writeFileSync(filePath, JSON.stringify(data, null, 2));
+}
+
+const distDir = path.join(__dirname, '..', 'dist');
+
+// --- figma-variables.json ---
+const primitives = buildPrimitives();
+const semantic = buildSemantic();
+const spacingAndShape = buildSpacingAndShape();
+
+const figmaVariables = {
+  $metadata: {
+    version: packageJson.version ?? '0.0.0',
+    generated: new Date().toISOString(),
+  },
+  Primitives: primitives,
+  Semantic: semantic,
+  'Spacing & Shape': spacingAndShape,
+};
+
+const figmaVariablesPath = path.join(distDir, 'figma-variables.json');
+writeJson(figmaVariablesPath, figmaVariables);
+
+// --- figma-effect-styles.json ---
+const effectStyles = buildEffectStyles();
+const effectStylesPath = path.join(distDir, 'figma-effect-styles.json');
+writeJson(effectStylesPath, effectStyles);
+
+// --- figma-text-styles.json ---
+const textStyles = buildTextStyles();
+const textStylesPath = path.join(distDir, 'figma-text-styles.json');
+writeJson(textStylesPath, textStyles);
+
+// --- tokens/tokens.json (copy of figma-variables.json) ---
+const tokensPath = path.join(__dirname, '..', 'tokens', 'tokens.json');
+writeJson(tokensPath, figmaVariables);
+
+// --- Summary ---
+console.log(
+  `✅ dist/figma-variables.json — ${Object.keys(primitives).length} Primitives, ${Object.keys(semantic).length} Semantic, ${Object.keys(spacingAndShape).length} Spacing & Shape tokens`,
+);
+console.log(
+  `✅ dist/figma-effect-styles.json — ${Object.keys(effectStyles.elevation).length} elevation levels`,
+);
+console.log(
+  `✅ dist/figma-text-styles.json — ${Object.keys(textStyles).length} text styles`,
+);
+console.log(`✅ tokens/tokens.json updated`);
+```
+
+**Step 2: Run the export script to verify it executes clean**
+
+```bash
+cd /Users/willstreeter/WebstormProjects/vibe-coding/shifu-project/Discourser-Design-System
+pnpm figma:export
+```
+
+Expected output (exact numbers):
+
+```
+✅ dist/figma-variables.json — 78 Primitives, 31 Semantic, 24 Spacing & Shape tokens
+✅ dist/figma-effect-styles.json — 6 elevation levels
+✅ dist/figma-text-styles.json — 15 text styles
+✅ tokens/tokens.json updated
+```
+
+**Step 3: Spot-check the output files**
+
+```bash
+# Verify Primitives structure
+node -e "const f=JSON.parse(require('fs').readFileSync('dist/figma-variables.json','utf8')); console.log(Object.keys(f.Primitives).slice(0,3)); console.log(f.Primitives['primary/0'])"
+```
+
+Expected:
+
+```
+[ 'primary/0', 'primary/10', 'primary/20' ]
+{ '$type': 'color', '$value': { Value: '#000000' } }
+```
+
+```bash
+# Verify Semantic has Light/Dark modes (no dark-* prefix keys)
+node -e "const f=JSON.parse(require('fs').readFileSync('dist/figma-variables.json','utf8')); const s=f.Semantic; console.log(s['primary']); console.log(s['primary/container']); console.log(s['surface/container/lowest'])"
+```
+
+Expected:
+
+```
+{ '$type': 'color', '$value': { Light: '#4C662B', Dark: '#B1D18A' } }
+{ '$type': 'color', '$value': { Light: '#CDEDA3', Dark: '#354E16' } }
+{ '$type': 'color', '$value': { Light: '#FFFFFF', Dark: '#0C0F09' } }
+```
+
+```bash
+# Verify numeric tokens are numbers not strings
+node -e "const f=JSON.parse(require('fs').readFileSync('dist/figma-variables.json','utf8')); const s=f['Spacing & Shape']; console.log(s['spacing/md']); console.log(s['radii/extraSmall']); console.log(s['border/thin']); console.log(s['duration/normal'])"
+```
+
+Expected:
+
+```
+{ '$type': 'number', '$value': { Value: 16 } }
+{ '$type': 'number', '$value': { Value: 4 } }
+{ '$type': 'number', '$value': { Value: 1 } }
+{ '$type': 'number', '$value': { Value: 200 } }
+```
+
+```bash
+# Verify text styles have numeric values and correct font family
+node -e "const f=JSON.parse(require('fs').readFileSync('dist/figma-text-styles.json','utf8')); console.log(f['displayLarge']); console.log(f['bodyMedium'])"
+```
+
+Expected:
+
+```
+{
+  fontFamily: 'Fraunces',
+  fontSize: 57,
+  fontWeight: 400,
+  lineHeight: 64,
+  letterSpacing: -0.25,
+  figmaTextStyle: 'displayLarge'
+}
+{
+  fontFamily: 'Poppins',
+  fontSize: 14,
+  fontWeight: 400,
+  lineHeight: 20,
+  letterSpacing: 0.25,
+  figmaTextStyle: 'bodyMedium'
+}
+```
+
+```bash
+# Verify effect styles
+node -e "const f=JSON.parse(require('fs').readFileSync('dist/figma-effect-styles.json','utf8')); console.log(Object.keys(f.elevation)); console.log(f.elevation.level1)"
+```
+
+Expected:
+
+```
+[ 'level0', 'level1', 'level2', 'level3', 'level4', 'level5' ]
+{
+  value: '0px 1px 2px rgba(0, 0, 0, 0.3), 0px 1px 3px 1px rgba(0, 0, 0, 0.15)',
+  description: 'Cards at rest, contained buttons (semantic: xs)'
+}
+```
+
+```bash
+# Verify tokens/tokens.json was updated
+node -e "const f=JSON.parse(require('fs').readFileSync('tokens/tokens.json','utf8')); console.log(Object.keys(f))"
+```
+
+Expected:
+
+```
+[ '$metadata', 'Primitives', 'Semantic', 'Spacing & Shape' ]
+```
+
+**Step 4: Run typecheck**
+
+```bash
+pnpm tsc --noEmit
+```
+
+Expected: No errors.
+
+**Step 5: Run tests to verify no regressions**
+
+```bash
+pnpm test
+```
+
+Expected: All tests pass (306/306).
+
+**Step 6: Commit**
+
+```bash
+git add scripts/export-figma-tokens.ts tokens/tokens.json
+git commit -m "feat: rewrite export-figma-tokens to DTCG format with Light/Dark modes"
+```
+
+---
+
+## Success Criteria
+
+- [ ] `pnpm figma:export` runs clean with no errors
+- [ ] `dist/figma-variables.json` exists with `Primitives`, `Semantic`, `Spacing & Shape` collections
+- [ ] Semantic collection has `Light`/`Dark` modes (no `dark-*` prefix keys anywhere)
+- [ ] All numeric tokens (spacing, radii, border, duration) are numbers not strings
+- [ ] `dist/figma-effect-styles.json` exists with 6 elevation levels
+- [ ] `dist/figma-text-styles.json` exists with 15 text styles, numeric values
+- [ ] `tokens/tokens.json` updated to match figma-variables.json content
+- [ ] Zero hardcoded hex values in the script
+- [ ] `pnpm test` passes: 306/306 (no regressions)
+- [ ] `pnpm tsc --noEmit` clean

package/docs/plans/2026-03-12-step7-panda-token-resolution-design.md

@@ -0,0 +1,119 @@
+# Step 7 Design: Panda Token Resolution for Foundation Stories
+
+**Date:** 2026-03-12
+**Branch context:** fix/remove-m3-labels (or new feature branch)
+
+## Goal
+
+Replace raw-value rendering with Panda CSS token resolution in all four foundation MDX stories. A broken token must produce a blank/invisible output rather than silently working.
+
+## Approach: A (Update Components)
+
+Move all Panda `css()` lookups inside the display component files in `src/stories/foundations/components/`. The `.mdx` files pass token name strings instead of raw values. This is cleaner than inlining JSX in `.mdx`.
+
+---
+
+## Per-Story Design
+
+### Colors.mdx
+
+**TonalSwatch section** → Remove entirely. Replace with a note pointing to the Color Scale story. Rationale: tonal palette tones (0, 10, 20, …, 100) have no Panda token equivalents — they are internal pipeline values. Adding 65 documentation-only tokens would be noise. ColorScale.stories.tsx already covers the usable Radix-scale vocabulary.
+
+**SemanticSwatch** → Update `ColorSwatch.tsx`:
+
+- Remove `lightValue` / `darkValue` props
+- Add `name` prop (token key string, e.g. `"primary"`, `"onPrimary"`, `"primary.container"`)
+- Pre-declare `semanticBg: Record<string, string>` with ~31 explicit `css({ bg: '...' })` entries
+- Show light/dark side-by-side: light box = plain div with lookup class; dark box = same class inside a `data-theme="dark"` wrapper
+- Labels show token path (e.g. `primary`) and `primary [dark]` — no hex strings
+
+`Colors.mdx` changes:
+
+- Remove tonal palette grid divs + `TonalSwatch` import usage (keep import if ColorSwatch still exports it, or remove)
+- Replace each `<SemanticSwatch lightValue=... darkValue=...>` with `<SemanticSwatch name="primary" ...>`
+- Keep all prose, headings, and usage guidelines unchanged
+
+### Elevation.mdx / ElevationCard.tsx
+
+Shadow tokens `level0`–`level5` exist in Panda as `boxShadow` values.
+
+`ElevationCard.tsx` changes:
+
+- Pre-declare `elevationClasses: Record<string, string>` with 6 entries: `level0: css({ boxShadow: 'level0' })` … `level5: css({ boxShadow: 'level5' })`
+- Remove `shadow` prop; use `level` prop as lookup key
+- The displayed shadow string becomes static text (hardcoded in the mdx reference table)
+
+`ElevationGrid.tsx`:
+
+- Remove `elevations: Record<string, string>` prop
+- Render a fixed array `['level0', 'level1', 'level2', 'level3', 'level4', 'level5']`
+
+`Elevation.mdx` changes:
+
+- `<ElevationGrid />` — no prop needed
+- "Visual Comparison" inline divs use pre-declared elevation classes (pre-declared in the mdx or extracted to a helper)
+
+### Spacing.mdx / SpacingBox.tsx
+
+Spacing tokens `none`, `xxs`, `xs`, `sm`, `md`, `lg`, `xl`, `xxl`, `xxxl` exist in Panda.
+
+`SpacingBox.tsx` changes:
+
+- Pre-declare `spacingWidthClasses: Record<string, string>` with 9 entries: `none: css({ width: 'none' })` … `xxxl: css({ width: 'xxxl' })`
+- Width bar uses `className={spacingWidthClasses[name]}` instead of `style={{ width: value }}`
+- Keep `value` prop for the px label display
+
+`Spacing.mdx` changes:
+
+- `<SpacingBox>` calls keep `name` and `value` props (value is for px label only)
+- "Visual Examples" section uses static px strings (e.g. `gap: '8px'`) instead of `material3Language.spacing.sm`
+
+### Typography.mdx / TypeSpecimen.tsx
+
+Text styles exist: `displayLarge`, `displayMedium`, `displaySmall`, `headlineLarge`, `headlineMedium`, `headlineSmall`, `titleLarge`, `titleMedium`, `titleSmall`, `bodyLarge`, `bodyMedium`, `bodySmall`, `labelLarge`, `labelMedium`, `labelSmall` (15 total).
+
+`TypeSpecimen.tsx` changes:
+
+- Add `styleName` prop (e.g. `'displayLarge'`)
+- Pre-declare `textStyleClasses: Record<string, string>` with 15 explicit `css({ textStyle: '...' })` entries
+- Specimen text uses `className={textStyleClasses[styleName]}` instead of inline `specimenStyle`
+- Keep all raw-value props (`fontSize`, `lineHeight`, etc.) — used only for the spec table below each specimen
+
+`Typography.mdx` changes:
+
+- Each `<TypeSpecimen>` gets `styleName="displayLarge"` (etc.) added
+- Font Families section: replace `fontFamily: material3Language.typography.fonts.display` with static string `'"Fraunces", Georgia, "Times New Roman", serif'` etc.
+
+---
+
+## Implementation Rules
+
+- All `css()` calls use string literals — no dynamic template strings or variables
+- Use a pre-declared lookup object (same pattern as `ColorScale.stories.tsx` `scaleBg` / `semanticClasses`)
+- `material3Language` must not be used to set any rendered color, shadow, width, or textStyle
+- `material3Language` may still be referenced for static label/description text only
+
+---
+
+## Test Requirement
+
+After first story is refactored (Colors.mdx / SemanticSwatch):
+
+1. In `semantic-tokens.ts`, temporarily rename `primary` → `primary_BROKEN`
+2. Storybook: confirm primary color swatches go blank/invisible
+3. Revert rename
+4. Confirm swatches return to normal
+   Document in commit message.
+
+---
+
+## Success Criteria
+
+- [x] All four .mdx stories render via Panda CSS token variables, not raw values
+- [x] No css() calls use dynamic string interpolation
+- [x] material3Language is NOT used to set any rendered color, shadow, size, or textStyle
+- [x] Test-and-revert confirms visual failure on token breakage
+- [x] pnpm test passes: 306/306
+- [x] pnpm tsc --noEmit clean
+- [x] Storybook renders all stories without console errors
+- [x] Sequence status doc updated: Step 7 complete