@discourser/design-system 0.22.2 → 0.22.4

package/docs/TESTING_TOKENS.md

@@ -0,0 +1,340 @@
+# Token Testing Strategy
+
+## Overview
+
+This document describes the comprehensive testing strategy for design tokens in the Discourser Design System. These tests prevent regressions in the three-layer token architecture.
+
+## Test Categories
+
+> **Total: 50 tests across 4 test files**
+
+### 1. **Token Definition Tests** (`src/preset/__tests__/shadows.test.ts`) — 11 tests
+
+**Purpose:** Verify semantic tokens are correctly defined and chained to base tokens.
+
+**What it tests:**
+- ✅ Semantic tokens (xs-2xl) reference correct base tokens (level1-5)
+- ✅ Utility tokens (inset) remain independent
+- ✅ No hardcoded Park UI values in semantic tokens
+- ✅ All required tokens are present
+- ✅ No unexpected tokens exist
+
+**Example:**
+```ts
+it('sm should reference shadows.level2', () => {
+  expect(shadows.sm.value).toBe('{shadows.level2}');
+});
+```
+
+**Catches:**
+- Accidentally using hardcoded values instead of token references
+- Missing token definitions
+- Wrong token references (e.g., sm → level3 instead of level2)
+
+---
+
+### 2. **Recipe Token Usage Tests** (`src/preset/recipes/__tests__/recipe-shadows.test.ts`) — 16 tests
+
+**Purpose:** Verify component recipes use semantic tokens (NOT base tokens).
+
+**What it tests:**
+- ✅ All shadow-using components use semantic tokens (xs-2xl)
+- ✅ No recipe references base tokens (level0-5) directly
+- ✅ STORY-003: Input/Textarea use focus-underline token
+- ✅ STORY-003: RadioGroup uses inset-border token
+- ✅ No inline var(--shadow-color) strings in recipes
+- ✅ Custom shadows are documented and intentional
+
+**Example:**
+```ts
+it('button recipe should use semantic tokens (xs, sm, md)', () => {
+  const elevated = button.variants?.variant?.elevated;
+  expect(elevated?.boxShadow).toBe('sm');
+  expect(elevated?._hover?.boxShadow).toBe('md');
+});
+```
+
+**Catches:**
+- Components bypassing semantic layer and using base tokens
+- Regressions after refactoring
+- Inconsistent token usage across components
+
+---
+
+### 3. **Transform Tests** (`src/languages/__tests__/transform.test.ts`) — 9 tests
+
+**Purpose:** Verify design language contract is correctly transformed to Panda theme.
+
+**What it tests:**
+- ✅ Base tokens (level0-5) are created from elevation.levels
+- ✅ M3 shadow values are preserved exactly
+- ✅ Shadow values follow M3 pattern (two-part shadows)
+- ✅ Elevation progression is correct
+- ✅ Transform function doesn't mutate source data
+
+**Example:**
+```ts
+it('should preserve M3 shadow values exactly', () => {
+  const expected = material3Language.elevation.levels;
+  expect(pandaTheme.tokens.shadows.level1.value).toBe(expected.level1);
+});
+```
+
+**Catches:**
+- Lost or corrupted M3 elevation values during transform
+- Incorrect token structure
+- Mutations to design language contract
+
+---
+
+### 4. **Integration Tests** (`src/preset/__tests__/token-resolution.test.ts`) — 14 tests
+
+**Purpose:** Verify complete preset configuration has correct token architecture.
+
+**What it tests:**
+- ✅ Preset includes both base and semantic shadow tokens
+- ✅ Semantic tokens reference existing base tokens
+- ✅ No circular token references
+- ✅ Inset token remains independent (STORY-002 requirement)
+- ✅ Utility tokens (focus-underline, inset-border) are independent
+- ✅ All recipes avoid base token usage (system-wide check)
+- ✅ Utility tokens are used in appropriate recipes
+- ✅ Token reference integrity across the system
+
+**Example:**
+```ts
+it('semantic tokens should only reference existing base tokens', () => {
+  const baseTokenNames = Object.keys(baseShadows || {});
+  // Verify each semantic token reference is valid
+  expect(baseTokenNames).toContain(referencedToken);
+});
+```
+
+**Catches:**
+- Broken token references
+- Missing base tokens
+- Circular dependencies
+- Integration issues between layers
+
+---
+
+## Running Tests
+
+### Run all token tests
+```bash
+pnpm test shadows
+```
+
+### Run specific test file
+```bash
+pnpm test shadows.test.ts
+pnpm test recipe-shadows.test.ts
+pnpm test transform.test.ts
+pnpm test token-resolution.test.ts
+```
+
+### Run with coverage
+```bash
+pnpm test:coverage
+```
+
+### Watch mode during development
+```bash
+pnpm test --watch
+```
+
+---
+
+## CI/CD Integration
+
+### Pre-commit Hook
+```bash
+# .husky/pre-commit
+pnpm test shadows --run
+```
+
+### GitHub Actions
+```yaml
+- name: Test Token Architecture
+  run: pnpm test shadows --run
+```
+
+---
+
+## Test Patterns
+
+### Pattern 1: Token Reference Validation
+```ts
+// Verify semantic token references base token
+expect(shadows.sm.value).toBe('{shadows.level2}');
+```
+
+### Pattern 2: Component Recipe Validation
+```ts
+// Verify recipe uses semantic tokens
+expect(recipe.boxShadow).toMatch(/^(xs|sm|md|lg|xl|2xl)$/);
+```
+
+### Pattern 3: Negative Testing (Anti-patterns)
+```ts
+// Verify no base tokens in recipes
+expect(recipeString).not.toMatch(/['"]level[0-5]['"]/);
+```
+
+### Pattern 4: Structural Validation
+```ts
+// Verify token has expected structure
+expect(token.value).toHaveProperty('base');
+expect(token.value).toHaveProperty('_dark');
+```
+
+---
+
+## Extending Tests for New Tokens
+
+### Adding a new semantic shadow token
+
+1. **Update `shadows.test.ts`:**
+```ts
+it('xxl should reference shadows.level5', () => {
+  expect(shadows.xxl.value).toBe('{shadows.level5}');
+});
+```
+
+2. **Update coverage test:**
+```ts
+const requiredTokens = ['xs', 'sm', 'md', 'lg', 'xl', '2xl', 'xxl', 'inset'];
+```
+
+### Adding a new component recipe
+
+1. **Import the recipe:**
+```ts
+import { newComponent } from '../newComponent';
+```
+
+2. **Add recipe test:**
+```ts
+it('newComponent recipe should use semantic tokens', () => {
+  expect(newComponent.boxShadow).toMatch(/^(xs|sm|md|lg|xl|2xl)$/);
+});
+```
+
+3. **Add to anti-pattern check:**
+```ts
+const recipes = { button, card, /* ... */, newComponent };
+```
+
+---
+
+## Visual Regression Testing
+
+While unit tests verify token definitions, visual regression tests verify the actual rendered output.
+
+### Chromatic Integration (Recommended)
+```bash
+# Run visual regression tests
+pnpm chromatic
+```
+
+### Manual Visual Testing
+```bash
+pnpm dev  # Start Storybook
+# Check each component in light + dark themes
+```
+
+**Components to visually verify:**
+- Button (elevated variant)
+- Card
+- Dialog
+- Drawer
+- Popover
+- Select
+- Slider
+- Switch
+- Toast
+- Tooltip
+
+---
+
+## Debugging Failed Tests
+
+### Token reference mismatch
+```
+Expected: '{shadows.level2}'
+Received: '{shadows.level3}'
+```
+**Fix:** Update semantic token definition in `src/preset/shadows.ts`
+
+### Recipe using base token
+```
+Error: recipeString matches /level[0-5]/
+```
+**Fix:** Update recipe to use semantic token (xs, sm, md, lg, xl, 2xl)
+
+### Missing base token
+```
+Error: baseTokenNames does not contain 'level6'
+```
+**Fix:** Either add the base token to material3.language.ts or fix the reference
+
+### Transform not preserving values
+```
+Expected: "0px 1px 2px rgba(0,0,0,0.3)"
+Received: undefined
+```
+**Fix:** Check transform.ts objectToTokens function and language contract
+
+---
+
+## Benefits of This Testing Strategy
+
+### 1. **Prevents Regressions**
+Tests catch when someone accidentally:
+- Uses base tokens directly in components
+- Breaks the token chain
+- Removes required tokens
+
+### 2. **Documents Architecture**
+Tests serve as executable documentation showing:
+- How tokens should be structured
+- What the token chain looks like
+- Which patterns are allowed/forbidden
+
+### 3. **Enables Refactoring**
+With comprehensive tests, you can:
+- Safely refactor token definitions
+- Swap design languages
+- Update M3 values with confidence
+
+### 4. **Fast Feedback**
+Tests run in milliseconds:
+- No need to rebuild Panda
+- No need to check Storybook manually
+- Instant feedback on token changes
+
+---
+
+## Best Practices
+
+### ✅ DO:
+- Run tests before committing
+- Add tests for new tokens/recipes
+- Keep tests focused and specific
+- Use descriptive test names
+- Test both positive and negative cases
+
+### ❌ DON'T:
+- Skip tests when adding new components
+- Test implementation details
+- Make tests dependent on each other
+- Hardcode magic values
+- Test Panda CSS internals
+
+---
+
+## Related Documentation
+
+- [STORY-002 Implementation](../context-share/STORY-002-IMPLEMENTATION-COMPLETE.md)
+- [Three-Layer Architecture](../CLAUDE.md#architecture)
+- [Shadow Token Architecture](../context-share/ELEVATION_FIX_PLAN.md)

package/docs/active-stories/README.md

@@ -0,0 +1,29 @@
+# Active Stories
+
+Story specs for work in progress on the Discourser Design System. Each file is structured as a **self-contained prompt** — paste directly into Claude Code to execute.
+
+## Execution Order
+
+```
+STORY-006a → STORY-006b → STORY-006c → STORY-011 → STORY-008
+```
+
+| # | File | Description | Estimate | Status |
+|---|------|-------------|----------|--------|
+| 1 | `STORY-006a-figma-translation-foundations.md` | Translation MDX files 00-04 (overview, colors, typography, spacing, shadows) | 1.5-2hr | Ready |
+| 2 | `STORY-006b-figma-translation-components.md` | Translation MDX file 05 (all 25+ component mappings) | 2-3hr | Blocked on 006a |
+| 3 | `STORY-006c-figma-translation-layout-extension.md` | Translation MDX files 06-07 (layout patterns, extension guide) | 1.5-2hr | Blocked on 006b |
+| 4 | `STORY-011-verify-translation-docs.md` | Automated tests + verification scripts for translation accuracy | 2-3hr | Blocked on 006c |
+| 5 | `STORY-008-kai-sidecar-fragments.md` | Extract condensed knowledge fragments for Kai agent | 2-3hr | Blocked on 011; executes in Discourser.ai repo |
+
+## Lifecycle
+
+When a story completes:
+1. Move the file to `docs/context-share/` with completion notes appended
+2. Update the corresponding Notion story status to Complete
+3. Start the next story in sequence
+
+## Parent Epic
+
+**Kai Agent — Design System MCP Integration & Elevation Fix**
+[Notion link](https://www.notion.so/3034d6019b428105a147e39a4fdb0a70)

package/docs/active-stories/STORY-006a-figma-translation-foundations.md

@@ -0,0 +1,324 @@
+# STORY-006a: Figma Translation System — Foundation Files (00-04)
+
+> **Epic:** Kai Agent — Design System MCP Integration
+> **Parent Story:** STORY-006: Figma-to-Discourser Translation System
+> **Part:** 1 of 3
+> **Estimate:** 1.5-2hr
+
+---
+
+## Context
+
+We're building a Figma-to-Discourser translation system — a multi-file MDX documentation suite in Storybook that maps external design vocabulary (Figma, Tailwind, Shadcn) to Discourser Design System vocabulary (Panda CSS, Park UI, Ark UI).
+
+This is the core translation layer for:
+- The **Kai Design Engineer agent** (reads these docs via Storybook MCP to make token/component decisions)
+- **Human developers** onboarding from Tailwind/Shadcn projects
+- **Design System as a Service** clients receiving implementation specs
+
+This prompt covers the **overview + token-level mapping files** (files 00-04). No component knowledge needed — just tokens verified against `panda.config.ts`.
+
+---
+
+## Prerequisites — READ THESE FIRST
+
+Before writing ANY code, read these files to understand the existing vocabulary and conventions:
+
+1. `panda.config.ts` — The actual semantic tokens defined (fg.default, fg.muted, fg.subtle, canvas, border, radii l1/l2/l3, shadows). **This is the source of truth for every token name you reference.**
+2. `src/preset/semantic-tokens.ts` — M3 semantic token definitions (surface, onSurface, outline, etc.)
+3. `src/preset/shadows.ts` — Park UI shadow token scale
+4. `stories/documentation/guidelines/design-tokens/colors.mdx` — Existing M3 color token docs
+5. `stories/documentation/guidelines/design-tokens/spacing.mdx` — Existing spacing scale docs
+6. `stories/documentation/guidelines/design-tokens/typography.mdx` — Existing typography scale docs
+7. `stories/documentation/guidelines/design-tokens/elevation.mdx` — Existing shadow/elevation docs
+8. `stories/documentation/guidelines/components/button.mdx` — Example of existing doc format (use as structure reference)
+
+---
+
+## Deliverables
+
+Create directory: `stories/documentation/figma-translation/`
+
+Create these 5 files:
+
+### File 1: `00-FigmaTranslation.mdx`
+
+**Storybook sidebar:** `Documentation/Figma Translation/00-Overview`
+
+```tsx
+import { Meta } from '@storybook/addon-docs/blocks';
+<Meta title="Documentation/Figma Translation/00-Overview" />
+```
+
+Content:
+- What this document suite is (translation layer between Figma/Tailwind/Shadcn vocabulary and Discourser)
+- Who it's for (Kai agent, human developers onboarding from Tailwind/Shadcn projects)
+- How to use it (look up the external term → get the Discourser equivalent)
+- Architecture summary: Figma/Shadcn → Tailwind utilities → Discourser semantic tokens → Panda CSS output
+- The 3-layer token architecture:
+  - **Layer 1 (Infrastructure):** Panda CSS / Park UI token names (`xs`, `sm`, `md`, `lg`, `xl`) — unchanging
+  - **Layer 2 (Design Language):** Material 3 — provides VALUES mapped to Layer 1 names — swappable
+  - **Layer 3 (Components):** Recipes reference Layer 1 only — decoupled from aesthetic
+- Table of contents linking to all sub-pages (01 through 07)
+
+### File 2: `01-Colors.mdx`
+
+**Storybook sidebar:** `Documentation/Figma Translation/01-Colors`
+
+Translation tables with THREE columns: **Source (Figma/Tailwind/Shadcn) | Discourser Token | Notes**
+
+**Background colors section:**
+
+| Source (Figma/Tailwind/Shadcn) | Discourser | Notes |
+|---|---|---|
+| `bg-background`, `bg-white` | `bg="canvas"` | Page-level background, resolves to gray.1 |
+| `bg-card`, `bg-popover` | `bg="bg.default"` or use component (Card.Root handles this) | Surface containers |
+| `bg-muted` | `bg="bg.muted"` | Subtle background areas |
+| `bg-primary` | `colorPalette="primary"` (on components) or `bg="primary.9"` (raw) | Primary action surfaces |
+| `bg-secondary` | `colorPalette="secondary"` or `bg="secondary.9"` | Secondary surfaces |
+| `bg-destructive` | `colorPalette="error"` or `bg="error.9"` | Error/destructive surfaces |
+| `bg-accent` | `bg="primary.a3"` or `bg="secondary.a3"` | Accent/highlight backgrounds |
+
+**Text colors section:**
+
+| Source | Discourser | Notes |
+|---|---|---|
+| `text-foreground` | `color="fg.default"` | Primary text, resolves to gray.12 |
+| `text-muted-foreground` | `color="fg.muted"` | Secondary text, resolves to gray.11 |
+| `text-primary` | `color="primary.11"` | Branded text |
+| `text-destructive` | `color="error.11"` | Error text |
+| `text-primary-foreground` | `color="primary.contrast"` | Text on primary backgrounds |
+
+**Border colors section:**
+
+| Source | Discourser | Notes |
+|---|---|---|
+| `border`, `border-input` | `borderColor="border"` | Default border, resolves to gray.6 |
+| `border-primary` | `borderColor="primary.7"` | Primary-colored borders |
+
+**M3 Surface System section** (when Figma uses M3 vocabulary directly):
+
+| Source (M3) | Discourser | Notes |
+|---|---|---|
+| `surface` | `bg="surface"` | M3 base surface |
+| `surfaceContainer` | `bg="surface.container"` | M3 default container |
+| `surfaceContainerLow` | `bg="surface.container.low"` | M3 low elevation |
+| `surfaceContainerHigh` | `bg="surface.container.high"` | M3 high elevation |
+| `surfaceContainerHighest` | `bg="surface.container.highest"` | M3 highest elevation |
+| `onSurface` | `color="onSurface"` | Text on M3 surfaces |
+| `onSurfaceVariant` | `color="onSurface.variant"` | Secondary text on M3 surfaces |
+| `outline` | `borderColor="outline"` | M3 outline |
+| `outlineVariant` | `borderColor="outline.variant"` | M3 subtle outline |
+
+**Color Palette System section:**
+- Explain the `colorPalette` prop system
+- Rule: Components that support colorPalette prop → ALWAYS use colorPalette, not direct color tokens
+- Available palettes: primary, secondary, tertiary, error, neutral/gray
+- Radix scale explanation: 1-12 scale where 1=lightest, 12=darkest, 9=solid, a1-a12=alpha variants
+- When to use `colorPalette="primary"` vs `bg="primary.9"` directly
+
+**Common Mistakes section** with ❌/✅ examples:
+```tsx
+// ❌ WRONG: Hardcoded hex value
+<Box bg="#4C662B">
+
+// ❌ WRONG: Using Tailwind class name
+<Box className="bg-primary">
+
+// ❌ WRONG: Using raw Radix scale when component supports colorPalette
+<Button bg="primary.9" color="primary.contrast">
+
+// ✅ CORRECT: Semantic token
+<Box bg="canvas">
+
+// ✅ CORRECT: colorPalette on component
+<Button colorPalette="primary">
+
+// ✅ CORRECT: Radix scale for custom styling outside components
+<Box bg="primary.3">
+```
+
+Cross-reference: Link to `Documentation/Guidelines/99-Colors` for full M3 color role details.
+
+### File 3: `02-Typography.mdx`
+
+**Storybook sidebar:** `Documentation/Figma Translation/02-Typography`
+
+**Tailwind → M3 textStyle mapping table:**
+
+| Source (Tailwind) | Discourser | Size | Notes |
+|---|---|---|---|
+| `text-xs` | `textStyle="labelSmall"` | 11px | Smallest readable text |
+| `text-sm` | `textStyle="bodySmall"` | 12px | Captions, help text |
+| `text-base` | `textStyle="bodyMedium"` | 14px | Default body text |
+| `text-lg` | `textStyle="bodyLarge"` | 16px | Emphasized body |
+| `text-xl` | `textStyle="titleSmall"` | 14px/500wt | Card titles, list headers |
+| `text-2xl` | `textStyle="titleLarge"` or `<Header size="xl">` | 22px | Section titles |
+| `text-3xl` | `textStyle="headlineSmall"` or `<Header size="2xl">` | 24px | Page subtitles |
+| `text-4xl` | `textStyle="headlineLarge"` or `<Header size="3xl">` | 32px | Page titles |
+| `text-5xl`+ | `textStyle="displaySmall"` or `<Header size="4xl">` | 36px+ | Hero text |
+
+**Font family mapping:**
+
+| Source | Discourser | Font |
+|---|---|---|
+| `font-sans` | `fontFamily="body"` | Poppins |
+| `font-serif` | `fontFamily="display"` | Fraunces |
+| `font-mono` | `fontFamily="mono"` | JetBrains Mono |
+
+**Font weight mapping:**
+
+| Source | Discourser | Value |
+|---|---|---|
+| `font-normal` | `fontWeight="normal"` | 400 |
+| `font-medium` | `fontWeight="medium"` | 500 |
+| `font-semibold` | `fontWeight="semibold"` | 600 |
+| `font-bold` | `fontWeight="bold"` | 700 |
+
+**Header component section:**
+- Rule: For headings, ALWAYS prefer `<Header size="...">` component over raw textStyle
+- Available sizes: xs, sm, md, lg, xl, 2xl, 3xl, 4xl, 5xl, 6xl, 7xl
+- Header renders as h-tag levels — map Figma heading levels to component
+
+**Common Mistakes** with ❌/✅ examples showing raw font-size vs textStyle vs Header component.
+
+Cross-reference: Link to `Documentation/Guidelines/99-Typography` for full M3 type scale.
+
+### File 4: `03-Spacing.mdx`
+
+**Storybook sidebar:** `Documentation/Figma Translation/03-Spacing`
+
+**Tailwind numeric → Panda CSS numeric mapping:**
+
+| Source (Tailwind) | Discourser | Pixels | Notes |
+|---|---|---|---|
+| `p-0`, `gap-0` | `p="0"`, `gap="0"` | 0px | Direct match |
+| `p-0.5` | `p="0.5"` | 2px | |
+| `p-1` | `p="1"` | 4px | |
+| `p-2` | `p="2"` | 8px | |
+| `p-3` | `p="3"` | 12px | |
+| `p-4` | `p="4"` | 16px | Most common |
+| `p-5` | `p="5"` | 20px | |
+| `p-6` | `p="6"` | 24px | |
+| `p-8` | `p="8"` | 32px | |
+| `p-10` | `p="10"` | 40px | |
+| `p-12` | `p="12"` | 48px | |
+| `p-16` | `p="16"` | 64px | |
+
+**Named token mapping** (from spacing.mdx):
+
+| Named Token | Numeric Equivalent | Pixels | Usage |
+|---|---|---|---|
+| `none` | `0` | 0px | Reset |
+| `xxs` | `0.5` | 2px | Minimal gaps |
+| `xs` | `1` | 4px | Tight spacing |
+| `sm` | `2` | 8px | Compact layouts |
+| `md` | `4` | 16px | Default spacing |
+| `lg` | `6` | 24px | Comfortable spacing |
+| `xl` | `8` | 32px | Major sections |
+| `xxl` | `12` | 48px | Large sections |
+| `xxxl` | `16` | 64px | Maximum spacing |
+
+**Figma Auto-Layout translation section:**
+
+| Figma Property | Discourser | Example |
+|---|---|---|
+| Auto-layout: Vertical, gap: 16 | `display="flex" flexDir="column" gap="4"` or `<VStack gap="4">` | Form fields |
+| Auto-layout: Horizontal, gap: 8 | `display="flex" flexDir="row" gap="2"` or `<HStack gap="2">` | Button groups |
+| Auto-layout: Wrap | `<Flex wrap="wrap" gap="4">` | Tag clouds |
+| Padding: 16px all sides | `p="4"` | Card content |
+| Padding: 24px H, 16px V | `px="6" py="4"` | Page sections |
+| Padding: 16px top, 8px bottom | `pt="4" pb="2"` | Asymmetric spacing |
+| Gap: 16px | `gap="4"` | Between siblings |
+
+**Common Mistakes** with ❌/✅ examples showing pixel values vs token values.
+
+Cross-reference: Link to `Documentation/Guidelines/99-Spacing`.
+
+### File 5: `04-Shadows-Radii.mdx`
+
+**Storybook sidebar:** `Documentation/Figma Translation/04-Shadows & Radii`
+
+**Shadow mapping:**
+
+| Source (Tailwind) | Discourser | M3 Level | Notes |
+|---|---|---|---|
+| `shadow-none` | `shadow="none"` | Level 0 | Flat |
+| `shadow-sm` | `shadow="xs"` | — | Subtle lift |
+| `shadow` | `shadow="sm"` | Level 1 | Cards |
+| `shadow-md` | `shadow="md"` | Level 2 | Raised elements |
+| `shadow-lg` | `shadow="lg"` | Level 3 | Dialogs, menus |
+| `shadow-xl` | `shadow="xl"` | Level 4 | Drawers |
+| `shadow-2xl` | `shadow="2xl"` | Level 5 | Modals |
+
+Note: Verify exact Park UI shadow token names against `src/preset/shadows.ts`. The above mapping is approximate — confirm every token exists.
+
+Include a note: M3 primarily uses surface tint (surfaceContainer colors) for elevation, not shadows alone. Shadows are supplementary.
+
+**Border radius mapping:**
+
+| Source (Tailwind) | Discourser | Pixels | Notes |
+|---|---|---|---|
+| `rounded-none` | `rounded="none"` | 0 | |
+| `rounded-sm` | `rounded="l1"` | 2px | Subtle rounding |
+| `rounded` | `rounded="l2"` | 6px | Default |
+| `rounded-md` | `rounded="l2"` | 6px | Same as default |
+| `rounded-lg` | `rounded="l3"` | 8px | Cards, dialogs |
+| `rounded-xl` | `rounded="xl"` | 12px | Large cards |
+| `rounded-2xl` | `rounded="2xl"` | 16px | Pills, large containers |
+| `rounded-full` | `rounded="full"` | 9999px | Avatars, circular |
+
+Note: Verify radii tokens. The l1/l2/l3 tokens are defined in panda.config.ts semanticTokens.radii. Standard Panda preset radii (xs, sm, md, lg, xl, 2xl, full) also exist from @pandacss/preset-panda.
+
+**Common Mistakes** with ❌/✅ examples.
+
+Cross-reference: Link to `Documentation/Guidelines/99-Elevation`.
+
+---
+
+## Technical Requirements
+
+1. **Every MDX file must start with:**
+```tsx
+import { Meta } from '@storybook/addon-docs/blocks';
+<Meta title="Documentation/Figma Translation/[XX-Name]" />
+```
+
+2. **Tables must use consistent columns across all files.** First column = external/source term. Second column = Discourser equivalent. This is non-negotiable — machine parsing depends on it.
+
+3. **Each mapping entry must be self-contained** — an agent or human can look up a single row and get a complete answer without reading surrounding context.
+
+4. **Verify EVERY token name against actual config files** before writing it in a table. Check:
+   - `panda.config.ts` semanticTokens section
+   - `src/preset/semantic-tokens.ts`
+   - `src/preset/shadows.ts`
+   - `src/preset/colors/` directory
+   
+   If a token doesn't exist in config, DO NOT include it. Add a comment noting the gap instead.
+
+5. **Run `pnpm storybook --no-open` briefly** after creating all files to verify MDX parses without errors. Kill after confirming no parse errors in terminal output.
+
+---
+
+## DO NOT
+
+- Change any existing files outside the new `stories/documentation/figma-translation/` directory
+- Modify `panda.config.ts` or any preset files
+- Install any packages
+- Create any `.stories.tsx` files — these are MDX documentation only
+- Invent token names that don't exist in the config
+
+---
+
+## Acceptance Criteria
+
+- [ ] `stories/documentation/figma-translation/` directory created
+- [ ] `00-FigmaTranslation.mdx` — overview with architecture summary and links to all sub-pages
+- [ ] `01-Colors.mdx` — complete color mapping (backgrounds, text, border, M3 surface, colorPalette system)
+- [ ] `02-Typography.mdx` — complete typography mapping (text sizes, fonts, weights, Header component)
+- [ ] `03-Spacing.mdx` — complete spacing mapping (numeric scale, named tokens, Figma auto-layout)
+- [ ] `04-Shadows-Radii.mdx` — complete shadow + border-radius mapping
+- [ ] Every token referenced verified against actual config files
+- [ ] All files render in Storybook without MDX parse errors
+- [ ] Common Mistakes (❌/✅) section in each file (01-04)
+- [ ] Cross-references to existing Guidelines MDX docs