@discourser/design-system 0.22.2 → 0.22.3

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

@@ -0,0 +1,993 @@
+# Step 7: Panda Token Resolution for Foundation Stories — Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Replace raw-value rendering in all four foundation MDX stories with Panda CSS token variables so a broken token produces a blank/invisible output.
+
+**Architecture:** Approach A — update the display components in `src/stories/foundations/components/` to accept a token-name prop and look up pre-declared `css()` class strings. The `.mdx` files pass token name strings instead of raw hex/px/shadow values. `material3Language` is removed from all rendering paths.
+
+**Tech Stack:** Panda CSS (`css()` from `styled-system/css`), React, MDX (Storybook), TypeScript.
+
+---
+
+## Task 1: Update `ColorSwatch.tsx` — refactor `SemanticSwatch`
+
+**Files:**
+
+- Modify: `src/stories/foundations/components/ColorSwatch.tsx`
+
+The `SemanticSwatch` component currently accepts `lightValue`/`darkValue` hex strings and applies them as inline `backgroundColor`. Replace with a Panda CSS token lookup.
+
+**Step 1: Add the `css` import and pre-declare the semantic background lookup**
+
+At the top of `ColorSwatch.tsx`, add `import { css } from 'styled-system/css';`.
+
+Then add this object **before** the `ColorSwatch` component definition (keep `ColorSwatch` and `TonalSwatch` as-is for now — they may still be imported even if unused):
+
+```tsx
+import { css } from 'styled-system/css';
+import { type CSSProperties } from 'react';
+
+// ── Pre-declared css() lookups — Panda CSS statically extracts these ─────────
+// Keys match the `name` prop passed from Colors.mdx (M3 semantic role names).
+// Values use the Panda semantic token path from src/preset/semantic-tokens.ts.
+const semanticBg: Record<string, string> = {
+  // Primary
+  primary: css({ bg: 'primary' }),
+  onPrimary: css({ bg: 'onPrimary' }),
+  primaryContainer: css({ bg: 'primary.container' }),
+  onPrimaryContainer: css({ bg: 'onPrimary.container' }),
+  // Secondary
+  secondary: css({ bg: 'secondary' }),
+  onSecondary: css({ bg: 'onSecondary' }),
+  secondaryContainer: css({ bg: 'secondary.container' }),
+  onSecondaryContainer: css({ bg: 'onSecondary.container' }),
+  // Tertiary
+  tertiary: css({ bg: 'tertiary' }),
+  onTertiary: css({ bg: 'onTertiary' }),
+  tertiaryContainer: css({ bg: 'tertiary.container' }),
+  onTertiaryContainer: css({ bg: 'onTertiary.container' }),
+  // Error
+  error: css({ bg: 'error' }),
+  onError: css({ bg: 'onError' }),
+  errorContainer: css({ bg: 'error.container' }),
+  onErrorContainer: css({ bg: 'onError.container' }),
+  // Surface
+  surface: css({ bg: 'surface' }),
+  onSurface: css({ bg: 'onSurface' }),
+  surfaceVariant: css({ bg: 'surfaceVariant' }),
+  onSurfaceVariant: css({ bg: 'onSurface.variant' }),
+  // Surface containers
+  surfaceContainerLowest: css({ bg: 'surface.container.lowest' }),
+  surfaceContainerLow: css({ bg: 'surface.container.low' }),
+  surfaceContainer: css({ bg: 'surface.container' }),
+  surfaceContainerHigh: css({ bg: 'surface.container.high' }),
+  surfaceContainerHighest: css({ bg: 'surface.container.highest' }),
+  // Outline
+  outline: css({ bg: 'outline' }),
+  outlineVariant: css({ bg: 'outline.variant' }),
+  // Inverse
+  inverseSurface: css({ bg: 'inverseSurface' }),
+  inverseOnSurface: css({ bg: 'inverseOnSurface' }),
+  inversePrimary: css({ bg: 'inversePrimary' }),
+  // Utility
+  background: css({ bg: 'background' }),
+  onBackground: css({ bg: 'onBackground' }),
+  scrim: css({ bg: 'scrim' }),
+  shadow: css({ bg: 'shadow' }),
+};
+```
+
+**Step 2: Replace the `SemanticSwatchProps` interface and component**
+
+Remove the old `SemanticSwatchProps` interface and `SemanticSwatch` component entirely, replace with:
+
+```tsx
+interface SemanticSwatchProps {
+  name: string;
+  description?: string;
+}
+
+export const SemanticSwatch = ({ name, description }: SemanticSwatchProps) => {
+  const bgClass = semanticBg[name] ?? '';
+
+  const containerStyle: CSSProperties = {
+    marginBottom: '16px',
+  };
+
+  const labelStyle: CSSProperties = {
+    fontSize: '14px',
+    fontWeight: '500',
+    marginBottom: '8px',
+    fontFamily: 'Inter, sans-serif',
+  };
+
+  const swatchRowStyle: CSSProperties = {
+    display: 'grid',
+    gridTemplateColumns: '1fr 1fr',
+    gap: '8px',
+  };
+
+  const swatchContainerStyle: CSSProperties = {
+    display: 'flex',
+    flexDirection: 'column',
+    gap: '4px',
+  };
+
+  const swatchStyle: CSSProperties = {
+    height: '80px',
+    borderRadius: '8px',
+    border: '1px solid rgba(0, 0, 0, 0.1)',
+  };
+
+  const modeStyle: CSSProperties = {
+    fontSize: '10px',
+    textTransform: 'uppercase',
+    color: '#999',
+    fontWeight: '600',
+  };
+
+  const tokenStyle: CSSProperties = {
+    fontSize: '11px',
+    fontFamily: 'monospace',
+    color: '#666',
+  };
+
+  const descStyle: CSSProperties = {
+    fontSize: '12px',
+    color: '#666',
+    marginTop: '8px',
+  };
+
+  return (
+    <div style={containerStyle}>
+      <div style={labelStyle}>{name}</div>
+      <div style={swatchRowStyle}>
+        {/* Light mode swatch — inherits default theme */}
+        <div style={swatchContainerStyle}>
+          <div style={modeStyle}>Light</div>
+          <div className={bgClass} style={swatchStyle} />
+          <div style={tokenStyle}>{name}</div>
+        </div>
+        {/* Dark mode swatch — forced via data-theme="dark" */}
+        <div style={swatchContainerStyle} data-theme="dark">
+          <div style={modeStyle}>Dark</div>
+          <div className={bgClass} style={swatchStyle} />
+          <div style={tokenStyle}>{name} [dark]</div>
+        </div>
+      </div>
+      {description && <div style={descStyle}>{description}</div>}
+    </div>
+  );
+};
+```
+
+**Step 3: Verify TypeScript compiles**
+
+```bash
+cd /Users/willstreeter/WebstormProjects/vibe-coding/shifu-project/Discourser-Design-System
+pnpm typecheck
+```
+
+Expected: no new errors (there may be errors from Colors.mdx prop mismatch until Task 2 — that's OK for now, mdx files aren't type-checked the same way).
+
+---
+
+## Task 2: Update `Colors.mdx` — remove tonal grid, update SemanticSwatch calls
+
+**Files:**
+
+- Modify: `src/stories/foundations/Colors.mdx`
+
+**Step 1: Remove the tonal palette section and update imports**
+
+Replace the import line:
+
+```mdx
+import {
+  ColorSwatch,
+  TonalSwatch,
+  SemanticSwatch,
+} from './components/ColorSwatch';
+import { material3Language } from '../../languages/material3.language';
+```
+
+With:
+
+```mdx
+import { SemanticSwatch } from './components/ColorSwatch';
+```
+
+**Step 2: Replace the six tonal palette grid sections**
+
+The file has six `<div style={{ display: 'grid', gridTemplateColumns: 'repeat(13, 1fr)' ...}}>` blocks (Primary, Secondary, Tertiary, Neutral, Neutral Variant, Error) each containing `{Object.entries(material3Language.colors.X).map(...)}`.
+
+Replace **all six** (from `### Primary` through the Error tonal grid `</div>`) plus the `### Primary` through `### Error` subheadings and the paragraphs before each grid.
+
+Replace the entire tonal palettes section (everything from `## Tonal Palettes` down to but not including `---`) with:
+
+```mdx
+## Tonal Palettes
+
+> **These are internal pipeline values.** Tonal palette steps (0–100) are used to build the Radix-scale and semantic tokens — they are not Panda CSS tokens and should never be used directly in components. To see the usable color vocabulary, open **Foundations → Color Scale** in the sidebar.
+```
+
+**Step 3: Update all SemanticSwatch JSX calls — remove lightValue and darkValue props**
+
+Find every `<SemanticSwatch` block. Each currently looks like:
+
+```jsx
+<SemanticSwatch
+  name="primary"
+  lightValue={material3Language.semantic.primary}
+  darkValue={material3Language.semanticDark.primary}
+  description="Primary brand color for key actions and emphasis"
+/>
+```
+
+Remove `lightValue={...}` and `darkValue={...}` from every call. Result:
+
+```jsx
+<SemanticSwatch
+  name="primary"
+  description="Primary brand color for key actions and emphasis"
+/>
+```
+
+There are ~34 `<SemanticSwatch` calls. Remove the `lightValue` and `darkValue` props from all of them.
+
+**Step 4: Run typecheck**
+
+```bash
+pnpm typecheck
+```
+
+Expected: clean.
+
+---
+
+## Task 3: Token breakage test (verify + revert)
+
+This is the manual verification required by the spec. Do NOT skip it.
+
+**Step 1: Temporarily break the `primary` token**
+
+In `src/preset/semantic-tokens.ts`, find:
+
+```ts
+primary: {
+  DEFAULT: { value: { base: s.primary, _dark: d.primary } },
+```
+
+Rename `primary` → `primary_BROKEN`:
+
+```ts
+primary_BROKEN: {
+  DEFAULT: { value: { base: s.primary, _dark: d.primary } },
+```
+
+**Step 2: Rebuild Panda**
+
+```bash
+pnpm build:panda
+```
+
+**Step 3: Confirm visual failure**
+
+Open Storybook (`pnpm dev`) and navigate to **Foundations → Colors**. The `primary` semantic swatch boxes should appear blank/no color (showing the background color of the page rather than the primary token color). This confirms the swatch is reading from the CSS variable, not from a hardcoded hex.
+
+**Step 4: Revert the token rename**
+
+Restore `primary_BROKEN` → `primary` in `src/preset/semantic-tokens.ts`.
+
+**Step 5: Rebuild Panda and confirm recovery**
+
+```bash
+pnpm build:panda
+```
+
+Storybook: primary swatches return to their correct green color.
+
+---
+
+## Task 4: Commit Colors + test result
+
+```bash
+cd /Users/willstreeter/WebstormProjects/vibe-coding/shifu-project/Discourser-Design-System
+git add src/stories/foundations/components/ColorSwatch.tsx \
+        src/stories/foundations/Colors.mdx
+git commit -m "feat: Colors.mdx uses Panda token CSS vars for semantic swatches
+
+- SemanticSwatch now accepts name prop (token key) + lookup table
+- Light/dark swatches use data-theme wrapper + same css() class
+- Token labels show token path instead of hex strings
+- Tonal palette grid removed (internal values, not Panda tokens)
+  → replaced with note pointing to Color Scale story
+- material3Language removed from all rendering paths in Colors.mdx
+
+Test performed: renamed 'primary' → 'primary_BROKEN' in semantic-tokens.ts,
+confirmed primary swatches went blank; reverted, confirmed recovery."
+```
+
+---
+
+## Task 5: Update `ElevationCard.tsx` — use shadow tokens
+
+**Files:**
+
+- Modify: `src/stories/foundations/components/ElevationCard.tsx`
+
+**Step 1: Add `css` import and pre-declare elevation classes**
+
+```tsx
+import { css } from 'styled-system/css';
+import { type CSSProperties } from 'react';
+
+// ── Pre-declared css() calls — Panda CSS statically extracts these ─────────
+const elevationClasses: Record<string, string> = {
+  level0: css({ boxShadow: 'level0' }),
+  level1: css({ boxShadow: 'level1' }),
+  level2: css({ boxShadow: 'level2' }),
+  level3: css({ boxShadow: 'level3' }),
+  level4: css({ boxShadow: 'level4' }),
+  level5: css({ boxShadow: 'level5' }),
+};
+
+export { elevationClasses };
+```
+
+**Step 2: Update `ElevationCardProps` — remove `shadow` prop**
+
+```tsx
+interface ElevationCardProps {
+  level: string;
+}
+```
+
+**Step 3: Update `ElevationCard` component**
+
+Remove `shadow` from the destructured props. Remove `boxShadow` from `cardStyle`. Apply `elevationClasses[level]` as className on the card div:
+
+```tsx
+export const ElevationCard = ({ level }: ElevationCardProps) => {
+  const containerStyle: CSSProperties = {
+    display: 'flex',
+    flexDirection: 'column',
+    alignItems: 'center',
+    marginBottom: '32px',
+  };
+
+  const cardStyle: CSSProperties = {
+    width: '200px',
+    height: '120px',
+    backgroundColor: '#fff',
+    borderRadius: '12px',
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    marginBottom: '16px',
+    // boxShadow applied via className — reads from Panda CSS variable
+  };
+
+  const labelStyle: CSSProperties = {
+    fontSize: '16px',
+    fontWeight: '600',
+    fontFamily: 'Inter, sans-serif',
+    marginBottom: '8px',
+    color: '#333',
+  };
+
+  return (
+    <div style={containerStyle}>
+      <div style={labelStyle}>{level}</div>
+      <div style={cardStyle} className={elevationClasses[level]}>
+        <span style={{ color: '#999', fontSize: '14px' }}>
+          {level === 'level0' ? 'No shadow' : 'Elevation'}
+        </span>
+      </div>
+    </div>
+  );
+};
+```
+
+**Step 4: Update `ElevationGrid` — remove `elevations` prop, render fixed levels**
+
+```tsx
+export const ElevationGrid = () => {
+  const gridStyle: CSSProperties = {
+    display: 'grid',
+    gridTemplateColumns: 'repeat(auto-fill, minmax(300px, 1fr))',
+    gap: '48px',
+    marginTop: '32px',
+    padding: '32px',
+    backgroundColor: '#f5f5f5',
+    borderRadius: '8px',
+  };
+
+  return (
+    <div style={gridStyle}>
+      {(
+        ['level0', 'level1', 'level2', 'level3', 'level4', 'level5'] as const
+      ).map((level) => (
+        <ElevationCard key={level} level={level} />
+      ))}
+    </div>
+  );
+};
+```
+
+**Step 5: Typecheck**
+
+```bash
+pnpm typecheck
+```
+
+---
+
+## Task 6: Update `Elevation.mdx` — use token classes, remove material3Language
+
+**Files:**
+
+- Modify: `src/stories/foundations/Elevation.mdx`
+
+**Step 1: Update imports**
+
+Replace:
+
+```mdx
+import { ElevationGrid } from './components/ElevationCard';
+import { material3Language } from '../../languages/material3.language';
+```
+
+With:
+
+```mdx
+import { ElevationGrid, elevationClasses } from './components/ElevationCard';
+```
+
+**Step 2: Update `<ElevationGrid />` — remove props**
+
+Find:
+
+```jsx
+<ElevationGrid elevations={material3Language.elevation.levels} />
+```
+
+Replace with:
+
+```jsx
+<ElevationGrid />
+```
+
+**Step 3: Update "Visual Comparison — Cards with Different Elevations" section**
+
+This section has an inline grid with three cards (Level 0, 1, 2). Each div uses `boxShadow: material3Language.elevation.levels.levelX`.
+
+Replace `boxShadow: material3Language.elevation.levels.level0` with `className={elevationClasses['level0']}` (and remove the boxShadow from the style object). Do this for level0, level1, level2.
+
+For example, the Level 0 card changes from:
+
+```jsx
+<div style={{
+  padding: '24px',
+  backgroundColor: '#fff',
+  borderRadius: '12px',
+  boxShadow: material3Language.elevation.levels.level0,
+  textAlign: 'center'
+}}>
+```
+
+To:
+
+```jsx
+<div
+  className={elevationClasses['level0']}
+  style={{ padding: '24px', backgroundColor: '#fff', borderRadius: '12px', textAlign: 'center' }}
+>
+```
+
+**Step 4: Update "Floating Elements" section**
+
+Same treatment for level3, level4, level5 cards in the second visual grid.
+
+**Step 5: Typecheck**
+
+```bash
+pnpm typecheck
+```
+
+---
+
+## Task 7: Commit Elevation changes
+
+```bash
+git add src/stories/foundations/components/ElevationCard.tsx \
+        src/stories/foundations/Elevation.mdx
+git commit -m "feat: Elevation.mdx uses Panda token CSS vars for shadow swatches
+
+- elevationClasses lookup: 6 explicit css({ boxShadow: 'levelX' }) entries
+- ElevationCard uses className instead of inline boxShadow style
+- ElevationGrid renders fixed level array, no longer accepts elevations prop
+- elevationClasses exported for use in Elevation.mdx inline cards
+- material3Language removed from all rendering paths in Elevation.mdx"
+```
+
+---
+
+## Task 8: Update `SpacingBox.tsx` — use width tokens
+
+**Files:**
+
+- Modify: `src/stories/foundations/components/SpacingBox.tsx`
+
+**Step 1: Add `css` import and pre-declare spacing width classes**
+
+```tsx
+import { css } from 'styled-system/css';
+import { type CSSProperties } from 'react';
+
+// ── Pre-declared css() calls — Panda CSS statically extracts these ─────────
+const spacingWidthClasses: Record<string, string> = {
+  none: css({ width: 'none' }),
+  xxs: css({ width: 'xxs' }),
+  xs: css({ width: 'xs' }),
+  sm: css({ width: 'sm' }),
+  md: css({ width: 'md' }),
+  lg: css({ width: 'lg' }),
+  xl: css({ width: 'xl' }),
+  xxl: css({ width: 'xxl' }),
+  xxxl: css({ width: 'xxxl' }),
+};
+```
+
+**Step 2: Update `SpacingBox` component**
+
+The `value` prop is kept for the px label. Remove `width: value` from `boxStyle`. Apply `spacingWidthClasses[name]` as className:
+
+```tsx
+export const SpacingBox = ({ name, value }: SpacingBoxProps) => {
+  // ... same containerStyle, labelContainerStyle, nameStyle, valueStyle, boxContainerStyle ...
+
+  const boxStyle: CSSProperties = {
+    height: '40px',
+    backgroundColor: '#4C662B',
+    borderRadius: '4px',
+    position: 'relative',
+    // width applied via className — reads from Panda CSS variable
+  };
+
+  const dimensionStyle: CSSProperties = {
+    position: 'absolute',
+    top: '-20px',
+    left: '0',
+    right: '0',
+    fontSize: '10px',
+    fontFamily: 'monospace',
+    color: '#999',
+    textAlign: 'center',
+  };
+
+  return (
+    <div style={containerStyle}>
+      <div style={labelContainerStyle}>
+        <div style={nameStyle}>{name}</div>
+        <div style={valueStyle}>{value}</div>
+      </div>
+      <div style={boxContainerStyle}>
+        <div style={boxStyle} className={spacingWidthClasses[name]}>
+          <div style={dimensionStyle}>{value}</div>
+        </div>
+      </div>
+    </div>
+  );
+};
+```
+
+Keep `SpacingGrid` as-is (it already passes `name` and `value`).
+
+**Step 3: Typecheck**
+
+```bash
+pnpm typecheck
+```
+
+---
+
+## Task 9: Update `Spacing.mdx` — remove material3Language from rendering
+
+**Files:**
+
+- Modify: `src/stories/foundations/Spacing.mdx`
+
+**Step 1: Update imports**
+
+Remove the material3Language import entirely:
+
+```mdx
+import { Meta } from '@storybook/addon-docs/blocks';
+import { SpacingBox } from './components/SpacingBox';
+import { material3Language } from '../../languages/material3.language';
+```
+
+Replace with:
+
+```mdx
+import { Meta } from '@storybook/addon-docs/blocks';
+import { SpacingBox } from './components/SpacingBox';
+```
+
+**Step 2: The `<SpacingBox>` calls in the spacing scale section — no change needed**
+
+The calls already pass `name` and `value` with static strings:
+
+```jsx
+<SpacingBox name="none" value={material3Language.spacing.none} />
+```
+
+These use `material3Language` for the `value` prop which is **display only** (the px label). The spec says we can keep material3Language for static label text. However, since we're removing the import, we need to replace with static values.
+
+Replace the nine `<SpacingBox>` calls with static values:
+
+```jsx
+<SpacingBox name="none" value="0px" />
+<SpacingBox name="xxs"  value="2px" />
+<SpacingBox name="xs"   value="4px" />
+<SpacingBox name="sm"   value="8px" />
+<SpacingBox name="md"   value="16px" />
+<SpacingBox name="lg"   value="24px" />
+<SpacingBox name="xl"   value="32px" />
+<SpacingBox name="xxl"  value="48px" />
+<SpacingBox name="xxxl" value="64px" />
+```
+
+**Step 3: Update the Spacing Reference Table**
+
+The table uses `{material3Language.spacing.none}` etc. in the Value column. Replace with static values:
+
+```mdx
+| Token  | Value | Pixels | Use Case                        |
+| ------ | ----- | ------ | ------------------------------- |
+| `none` | 0px   | 0px    | Reset spacing, remove gaps      |
+| `xxs`  | 2px   | 2px    | Minimal gaps, fine-tuning       |
+| `xs`   | 4px   | 4px    | Tight spacing within components |
+| `sm`   | 8px   | 8px    | Component internal spacing      |
+| `md`   | 16px  | 16px   | Default spacing, component gaps |
+| `lg`   | 24px  | 24px   | Section spacing, card padding   |
+| `xl`   | 32px  | 32px   | Large section breaks            |
+| `xxl`  | 48px  | 48px   | Major section dividers          |
+| `xxxl` | 64px  | 64px   | Page-level spacing              |
+```
+
+**Step 4: Update "Visual Examples" section — replace material3Language gap/padding**
+
+Three container divs use `gap: material3Language.spacing.sm`, `gap: material3Language.spacing.md`, `gap: material3Language.spacing.lg` and `padding: material3Language.spacing.md/lg/xl`.
+
+Replace each with static px strings:
+
+- `gap: material3Language.spacing.sm` → `gap: '8px'`
+- `gap: material3Language.spacing.md` → `gap: '16px'`
+- `gap: material3Language.spacing.lg` → `gap: '24px'`
+- `padding: material3Language.spacing.md` → `padding: '16px'`
+- `padding: material3Language.spacing.lg` → `padding: '24px'`
+- `padding: material3Language.spacing.xl` → `padding: '32px'`
+
+**Step 5: Typecheck**
+
+```bash
+pnpm typecheck
+```
+
+---
+
+## Task 10: Commit Spacing changes
+
+```bash
+git add src/stories/foundations/components/SpacingBox.tsx \
+        src/stories/foundations/Spacing.mdx
+git commit -m "feat: Spacing.mdx uses Panda token CSS vars for spacing bars
+
+- spacingWidthClasses lookup: 9 explicit css({ width: 'tokenName' }) entries
+- SpacingBox uses className for the visual width bar
+- value prop kept for px label display only
+- material3Language removed from Spacing.mdx (static values inlined)"
+```
+
+---
+
+## Task 11: Update `TypeSpecimen.tsx` — use textStyle tokens
+
+**Files:**
+
+- Modify: `src/stories/foundations/components/TypeSpecimen.tsx`
+
+**Step 1: Add `css` import and pre-declare textStyle classes**
+
+```tsx
+import { css } from 'styled-system/css';
+import { type CSSProperties } from 'react';
+
+// ── Pre-declared css() calls — Panda CSS statically extracts these ─────────
+const textStyleClasses: Record<string, string> = {
+  displayLarge: css({ textStyle: 'displayLarge' }),
+  displayMedium: css({ textStyle: 'displayMedium' }),
+  displaySmall: css({ textStyle: 'displaySmall' }),
+  headlineLarge: css({ textStyle: 'headlineLarge' }),
+  headlineMedium: css({ textStyle: 'headlineMedium' }),
+  headlineSmall: css({ textStyle: 'headlineSmall' }),
+  titleLarge: css({ textStyle: 'titleLarge' }),
+  titleMedium: css({ textStyle: 'titleMedium' }),
+  titleSmall: css({ textStyle: 'titleSmall' }),
+  bodyLarge: css({ textStyle: 'bodyLarge' }),
+  bodyMedium: css({ textStyle: 'bodyMedium' }),
+  bodySmall: css({ textStyle: 'bodySmall' }),
+  labelLarge: css({ textStyle: 'labelLarge' }),
+  labelMedium: css({ textStyle: 'labelMedium' }),
+  labelSmall: css({ textStyle: 'labelSmall' }),
+};
+```
+
+**Step 2: Update `TypeSpecimenProps` — add `styleName` prop**
+
+```tsx
+interface TypeSpecimenProps {
+  styleName: string;
+  name: string;
+  fontSize: string;
+  lineHeight: string;
+  fontWeight: string;
+  letterSpacing: string;
+  fontFamily: string;
+  sampleText?: string;
+}
+```
+
+**Step 3: Update the component — use textStyle class for specimen text**
+
+The `specimenStyle` object with raw fontSize/lineHeight/fontWeight/letterSpacing/fontFamily should be removed from the specimen div. The `textStyleClasses[styleName]` class handles all typography. Keep a minimal style for `color` and `marginBottom`:
+
+```tsx
+export const TypeSpecimen = ({
+  styleName,
+  name,
+  fontSize,
+  lineHeight,
+  fontWeight,
+  letterSpacing,
+  fontFamily,
+  sampleText = 'The quick brown fox jumps over the lazy dog',
+}: TypeSpecimenProps) => {
+  // ... containerStyle, headerStyle, nameStyle, propertiesStyle, propertyStyle, propertyLabelStyle stay unchanged ...
+
+  return (
+    <div style={containerStyle}>
+      <div style={headerStyle}>
+        <div style={nameStyle}>{name}</div>
+      </div>
+      {/* Specimen text: uses Panda textStyle token — blank if token broken */}
+      <div
+        className={textStyleClasses[styleName]}
+        style={{ color: '#000', marginBottom: '16px' }}
+      >
+        {sampleText}
+      </div>
+      {/* Spec table: shows raw token values for reference */}
+      <div style={propertiesStyle}>
+        <div style={propertyStyle}>
+          <div style={propertyLabelStyle}>Font Size</div>
+          <div>{fontSize}</div>
+        </div>
+        <div style={propertyStyle}>
+          <div style={propertyLabelStyle}>Line Height</div>
+          <div>{lineHeight}</div>
+        </div>
+        <div style={propertyStyle}>
+          <div style={propertyLabelStyle}>Font Weight</div>
+          <div>{fontWeight}</div>
+        </div>
+        <div style={propertyStyle}>
+          <div style={propertyLabelStyle}>Letter Spacing</div>
+          <div>{letterSpacing}</div>
+        </div>
+        <div style={propertyStyle}>
+          <div style={propertyLabelStyle}>Font Family</div>
+          <div>{fontFamily}</div>
+        </div>
+      </div>
+    </div>
+  );
+};
+```
+
+Remove the `getFontFamilyString` helper function — it's no longer needed since the specimen uses the Panda textStyle class.
+
+**Step 4: Typecheck**
+
+```bash
+pnpm typecheck
+```
+
+---
+
+## Task 12: Update `Typography.mdx` — add styleName prop, remove material3Language
+
+**Files:**
+
+- Modify: `src/stories/foundations/Typography.mdx`
+
+**Step 1: Update imports**
+
+Remove material3Language import:
+
+```mdx
+import { Meta } from '@storybook/addon-docs/blocks';
+import { TypeSpecimen } from './components/TypeSpecimen';
+```
+
+**Step 2: Update Font Families section — replace dynamic font strings with static**
+
+Replace three occurrences:
+
+- `fontFamily: material3Language.typography.fonts.display` → `fontFamily: '"Fraunces", Georgia, serif'`
+- `fontFamily: material3Language.typography.fonts.body` → `fontFamily: '"Poppins", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif'`
+- `fontFamily: material3Language.typography.fonts.mono` → `fontFamily: '"JetBrains Mono", "Fira Code", Consolas, monospace'`
+
+**Step 3: Add `styleName` prop to all 15 `<TypeSpecimen>` calls**
+
+Each call currently looks like:
+
+```jsx
+<TypeSpecimen
+  name="Display Large"
+  fontSize={material3Language.typography.scale.displayLarge.fontSize}
+  lineHeight={material3Language.typography.scale.displayLarge.lineHeight}
+  fontWeight={material3Language.typography.scale.displayLarge.fontWeight}
+  letterSpacing={material3Language.typography.scale.displayLarge.letterSpacing}
+  fontFamily={material3Language.typography.scale.displayLarge.fontFamily}
+  sampleText="Display Large"
+/>
+```
+
+Add `styleName="displayLarge"` (and keep all existing props for the spec table). The `styleName` value matches the Panda textStyle key:
+
+| name prop         | styleName        |
+| ----------------- | ---------------- |
+| "Display Large"   | `displayLarge`   |
+| "Display Medium"  | `displayMedium`  |
+| "Display Small"   | `displaySmall`   |
+| "Headline Large"  | `headlineLarge`  |
+| "Headline Medium" | `headlineMedium` |
+| "Headline Small"  | `headlineSmall`  |
+| "Title Large"     | `titleLarge`     |
+| "Title Medium"    | `titleMedium`    |
+| "Title Small"     | `titleSmall`     |
+| "Body Large"      | `bodyLarge`      |
+| "Body Medium"     | `bodyMedium`     |
+| "Body Small"      | `bodySmall`      |
+| "Label Large"     | `labelLarge`     |
+| "Label Medium"    | `labelMedium`    |
+| "Label Small"     | `labelSmall`     |
+
+**Step 4: Replace `material3Language.typography.scale.*` props with static values**
+
+After adding `styleName`, the remaining props are for the spec table only. Replace dynamic lookups with static strings from `material3Language.ts`:
+
+```
+displayLarge:   57px / 64px / 400 / -0.25px / display
+displayMedium:  45px / 52px / 400 / 0px     / display
+displaySmall:   36px / 44px / 400 / 0px     / display
+headlineLarge:  32px / 40px / 400 / 0px     / display
+headlineMedium: 28px / 36px / 400 / 0px     / display
+headlineSmall:  24px / 32px / 400 / 0px     / display
+titleLarge:     22px / 28px / 400 / 0px     / body
+titleMedium:    16px / 24px / 500 / 0.15px  / body
+titleSmall:     14px / 20px / 500 / 0.1px   / body
+bodyLarge:      16px / 24px / 400 / 0.5px   / body
+bodyMedium:     14px / 20px / 400 / 0.25px  / body
+bodySmall:      12px / 16px / 400 / 0.4px   / body
+labelLarge:     14px / 20px / 500 / 0.1px   / body
+labelMedium:    12px / 16px / 500 / 0.5px   / body
+labelSmall:     11px / 16px / 500 / 0.5px   / body
+```
+
+Verify these values against `src/languages/material3.language.ts` before writing them into the mdx — don't assume they're correct from this plan.
+
+**Step 5: Typecheck**
+
+```bash
+pnpm typecheck
+```
+
+---
+
+## Task 13: Commit Typography changes
+
+```bash
+git add src/stories/foundations/components/TypeSpecimen.tsx \
+        src/stories/foundations/Typography.mdx
+git commit -m "feat: Typography.mdx uses Panda textStyle tokens for specimen rendering
+
+- textStyleClasses lookup: 15 explicit css({ textStyle: '...' }) entries
+- TypeSpecimen specimen div uses className from lookup, not inline specimenStyle
+- styleName prop added to all 15 TypeSpecimen calls in Typography.mdx
+- Font family display uses static strings (font names aren't Panda tokens)
+- material3Language removed from all rendering paths in Typography.mdx"
+```
+
+---
+
+## Task 14: Final verification
+
+**Step 1: Run full test suite**
+
+```bash
+pnpm test
+```
+
+Expected: 306/306 pass (display components have no unit tests; the token-contract test remains valid since we didn't change semantic-tokens.ts).
+
+**Step 2: TypeScript check**
+
+```bash
+pnpm typecheck
+```
+
+Expected: 0 errors.
+
+**Step 3: Build check**
+
+```bash
+pnpm build
+```
+
+Expected: clean build.
+
+**Step 4: Storybook smoke check**
+
+```bash
+pnpm dev
+```
+
+Open each of the four stories:
+
+- Foundations → Colors: semantic swatches show token-resolved colors; tonal section shows the reference note
+- Foundations → Elevation: ElevationGrid shows 6 levels via box-shadow tokens; Visual Comparison section renders correctly
+- Foundations → Spacing: SpacingBox bars render at correct widths; px labels still visible
+- Foundations → Typography: TypeSpecimen specimens render with correct font/size via textStyle tokens; spec tables still show raw values
+
+No console errors expected.
+
+---
+
+## Task 15: Update sequence status doc + final commit
+
+**Step 1: Find the sequence status doc**
+
+```bash
+ls docs/
+```
+
+Look for a file tracking "Steps 1–N complete" — likely `docs/design-system-setup-prompt.md` or similar.
+
+**Step 2: Mark Step 7 complete**
+
+Find the Step 7 entry and update its status from pending to complete.
+
+**Step 3: Final commit**
+
+```bash
+git add docs/
+git commit -m "docs: mark Step 7 complete — Panda token resolution for foundation stories"
+```
+
+---
+
+## Quick Reference: Panda Token Paths Used
+
+| Rendered property          | Panda token syntax                                                        |
+| -------------------------- | ------------------------------------------------------------------------- |
+| Semantic color backgrounds | `css({ bg: 'primary' })`, `css({ bg: 'primary.container' })` etc.         |
+| Box shadow levels          | `css({ boxShadow: 'level0' })` … `css({ boxShadow: 'level5' })`           |
+| Spacing widths             | `css({ width: 'none' })`, `css({ width: 'sm' })` etc.                     |
+| Typography                 | `css({ textStyle: 'displayLarge' })` … `css({ textStyle: 'labelSmall' })` |
+
+All lookups follow the same pattern as `ColorScale.stories.tsx` — explicit string literals, no dynamic interpolation.