@discourser/design-system 0.22.2 → 0.22.4

package/docs/active-stories/STORY-006b-figma-translation-components.md

@@ -0,0 +1,201 @@
+# STORY-006b: Figma Translation System — Component Mappings (05)
+
+> **Epic:** Kai Agent — Design System MCP Integration
+> **Parent Story:** STORY-006: Figma-to-Discourser Translation System
+> **Part:** 2 of 3
+> **Depends on:** STORY-006a (files 00-04 must exist)
+> **Estimate:** 2-3hr
+
+---
+
+## Context
+
+This prompt creates the **component registry** — the most comprehensive file in the translation suite. It maps every Discourser component from its Figma/Shadcn equivalent, including props, variants, import paths, and compound component anatomy.
+
+**This file must be accurate.** Every import path, prop name, variant value, and compound anatomy must come from reading the actual source files — not from memory or guessing.
+
+---
+
+## Prerequisites — READ THESE FIRST
+
+Before writing ANY code, read these files in this order:
+
+1. **`src/components/index.ts`** — The complete list of exported components. Every component here MUST appear in the mapping.
+2. **`panda.config.ts`** — Check the `recipes` and `slotRecipes` sections to know which components are simple (recipe) vs compound (slotRecipe).
+3. **Read each component's guideline MDX** in `stories/documentation/guidelines/components/` — these have variant tables, prop lists, and usage guidance.
+4. **Read each component's `.stories.tsx`** in `stories/` — these show actual prop values and usage patterns.
+5. **Read the source file** for each component in `src/components/` — for compound components, this shows the exact anatomy (Root, Trigger, Content, etc.).
+6. **`stories/documentation/figma-translation/00-FigmaTranslation.mdx`** — Read the overview from STORY-006a to understand the document conventions and architecture.
+
+---
+
+## Deliverable
+
+Create one file: `stories/documentation/figma-translation/05-Components.mdx`
+
+**Storybook sidebar:** `Documentation/Figma Translation/05-Components`
+
+```tsx
+import { Meta } from '@storybook/addon-docs/blocks';
+<Meta title="Documentation/Figma Translation/05-Components" />
+```
+
+### Structure
+
+Organize components into these groups:
+
+1. **Interactive Elements:** Button, IconButton, Input, InputGroup, InputAddon, Textarea, Select, Checkbox, RadioGroup, Switch, Slider
+2. **Layout & Containers:** Card, Accordion, Drawer, Tabs, Stepper
+3. **Feedback & Status:** Badge, Avatar, Progress, Skeleton, Spinner, Toast
+4. **Overlays:** Dialog, Popover, Tooltip
+5. **Typography:** Header
+6. **Utility:** CloseButton, Group, AbsoluteCenter, Icon, Loader
+
+### Per-Component Format
+
+For **simple components** (recipe — listed in `panda.config.ts` under `recipes`):
+
+```markdown
+### [ComponentName]
+
+**Maps from:** [Figma equivalent], [Shadcn equivalent if applicable]
+**Import:** `import { [ComponentName] } from '@discourser/design-system'`
+**Type:** Simple (recipe)
+
+| Source (Figma/Shadcn) Prop | Discourser Prop | Values | Notes |
+|---|---|---|---|
+| [external prop] | [discourser prop] | [available values] | [mapping notes] |
+```
+
+For **compound components** (slotRecipe — listed in `panda.config.ts` under `slotRecipes`):
+
+```markdown
+### [ComponentName]
+
+**Maps from:** [Figma equivalent], [Shadcn equivalent if applicable]
+**Import:** `import { [ComponentName] } from '@discourser/design-system'`
+**Type:** Compound (slot recipe)
+
+**Anatomy:**
+- `<ComponentName.Root>` — [purpose]
+- `<ComponentName.Part>` — [purpose]
+- ...
+
+| Source (Shadcn) | Discourser | Notes |
+|---|---|---|
+| `<ShadcnPart>` | `<ComponentName.Part>` | [mapping notes] |
+
+| Source Prop | Discourser Prop | Values | Notes |
+|---|---|---|---|
+| [external prop] | [discourser prop] | [available values] | [notes] |
+```
+
+### Detailed Mapping Requirements
+
+Here's what MUST be covered for key components. For each, read the actual source file and guideline MDX:
+
+**Button** (recipe):
+- Variant mapping: Shadcn "default" → Discourser "solid", "destructive" → `colorPalette="error"` (color, not variant)
+- All variant values from recipe: solid, outline, ghost, subtle, elevated (verify against actual recipe)
+- All size values from recipe (verify against actual recipe)
+- Note that `colorPalette` prop changes the color theme, not a variant
+
+**Card** (slotRecipe):
+- Anatomy: Root, Header, Body, Footer, Title, Description
+- Shadcn `<Card>` → `<Card.Root>`, `<CardHeader>` → `<Card.Header>`, etc.
+- Note that Card is compound in Discourser but flat in Shadcn
+
+**Dialog** (slotRecipe):
+- Anatomy: Root, Trigger, Backdrop, Positioner, Content, Title, Description, CloseTrigger
+- Critical: Shadcn `<DialogContent>` → `<Dialog.Positioner><Dialog.Content>` (needs positioner wrapper)
+- Shadcn `<DialogHeader>` → `<VStack gap="1.5">` (no dedicated component — use layout)
+- Shadcn `<DialogFooter>` → `<HStack gap="3" justify="flex-end">` (no dedicated component — use layout)
+
+**Select** (slotRecipe):
+- Full compound anatomy from Ark UI
+- Shadcn Select is much simpler — note the structural differences
+
+**Drawer** (slotRecipe):
+- Similar to Dialog but with slide-in behavior
+- Map Shadcn Sheet → Discourser Drawer
+
+**Input / InputGroup / InputAddon**:
+- Show how Shadcn's simple `<Input>` maps to potential InputGroup + InputAddon composition
+- Variant and size mappings
+
+**Toast** (slotRecipe):
+- Programmatic API: `toaster.create()` vs Shadcn's `toast()`
+- Show the different invocation pattern
+
+**Accordion** (slotRecipe):
+- Anatomy from Ark UI compound pattern
+
+For ALL other components: read the source, guideline, and story to produce accurate mappings. Do not skip any component exported from `src/components/index.ts`.
+
+### Common Mistakes Section
+
+Include at the bottom:
+
+```tsx
+// ❌ WRONG: Using flat Shadcn pattern for compound Discourser component
+<Dialog>
+  <DialogContent>...</DialogContent>
+</Dialog>
+
+// ✅ CORRECT: Using Ark UI compound pattern
+<Dialog.Root>
+  <Dialog.Trigger>Open</Dialog.Trigger>
+  <Dialog.Backdrop />
+  <Dialog.Positioner>
+    <Dialog.Content>...</Dialog.Content>
+  </Dialog.Positioner>
+</Dialog.Root>
+
+// ❌ WRONG: Using "destructive" as a variant
+<Button variant="destructive">Delete</Button>
+
+// ✅ CORRECT: Using colorPalette for destructive intent
+<Button variant="solid" colorPalette="error">Delete</Button>
+
+// ❌ WRONG: Importing from wrong path
+import { Button } from '@ark-ui/react'
+import { button } from '../preset/recipes/button'
+
+// ✅ CORRECT: Importing from design system
+import { Button } from '@discourser/design-system'
+```
+
+---
+
+## Technical Requirements
+
+1. **Read the actual source for every component** — Do not guess at anatomy, props, or variant values.
+2. **Consistent table columns** — `Source (Figma/Shadcn) | Discourser | Notes` pattern maintained.
+3. **Every import path must be `@discourser/design-system`** — this is the only valid import path for consumers.
+4. **Cross-reference each component** to its guideline MDX with a link like: "See [Guidelines/99-Button] for full usage guidance."
+5. **Verify against panda.config.ts** — recipe vs slotRecipe classification must match what's in config.
+
+---
+
+## DO NOT
+
+- Change any existing files
+- Modify any source code
+- Install any packages
+- Guess at component anatomy — read the source file
+- Omit any component from `src/components/index.ts`
+
+---
+
+## Acceptance Criteria
+
+- [ ] `05-Components.mdx` created with all components from `src/components/index.ts` mapped
+- [ ] Components grouped by category (Interactive, Layout, Feedback, Overlays, Typography, Utility)
+- [ ] Simple components have variant/size/prop tables from actual recipe definitions
+- [ ] Compound components have full anatomy listing from actual source files
+- [ ] Shadcn → Discourser structural mapping for all compound components (Dialog, Card, Select, etc.)
+- [ ] Common Mistakes section with ❌/✅ patterns
+- [ ] Every import path verified as `@discourser/design-system`
+- [ ] Cross-references to existing guideline MDX docs
+- [ ] Recipe vs slotRecipe classification matches `panda.config.ts`
+- [ ] File renders in Storybook without MDX parse errors

package/docs/active-stories/STORY-006c-figma-translation-layout-extension.md

@@ -0,0 +1,258 @@
+# STORY-006c: Figma Translation System — Layout Patterns + Extension Guide (06-07)
+
+> **Epic:** Kai Agent — Design System MCP Integration
+> **Parent Story:** STORY-006: Figma-to-Discourser Translation System
+> **Part:** 3 of 3
+> **Depends on:** STORY-006a (files 00-04) and STORY-006b (file 05)
+> **Estimate:** 1.5-2hr
+
+---
+
+## Context
+
+This prompt creates the final two files in the translation suite:
+- **06-Layout.mdx** — Maps Figma auto-layout and Tailwind flex/grid to Panda CSS patterns. This subsumes the work originally planned for STORY-005 (Panda CSS Layout Pattern MDX Docs).
+- **07-ExtensionGuide.mdx** — Templates and processes for maintaining the translation suite as the design system evolves. This is what makes the whole system sustainable.
+
+---
+
+## Prerequisites — READ THESE FIRST
+
+1. **All files created by STORY-006a and STORY-006b** — Read the existing translation files (00-05) to match conventions, column formats, and tone.
+2. `stories/documentation/guidelines/overview-patterns.mdx` — Existing layout/composition patterns. Reference but don't duplicate.
+3. `stories/documentation/guidelines/design-tokens/spacing.mdx` — Spacing scale (already mapped in 03-Spacing.mdx, reference for consistency).
+4. `panda.config.ts` — Check available breakpoint conditions, global CSS settings.
+5. `src/components/index.ts` — Full component list for completeness checks in extension guide.
+
+---
+
+## Deliverables
+
+### File 1: `stories/documentation/figma-translation/06-Layout.mdx`
+
+**Storybook sidebar:** `Documentation/Figma Translation/06-Layout Patterns`
+
+```tsx
+import { Meta } from '@storybook/addon-docs/blocks';
+<Meta title="Documentation/Figma Translation/06-Layout Patterns" />
+```
+
+**Figma/Tailwind → Panda CSS layout mapping:**
+
+| Source (Figma/Tailwind) | Discourser | When to Use |
+|---|---|---|
+| `flex flex-col` | `display="flex" flexDir="column"` or `<VStack>` | Vertical stacking |
+| `flex flex-row` | `display="flex" flexDir="row"` or `<HStack>` | Horizontal layout |
+| `flex flex-wrap` | `<Flex wrap="wrap">` | Wrapping items |
+| `grid grid-cols-2` | `display="grid" gridTemplateColumns="repeat(2, 1fr)"` or `<Grid columns={2}>` | Fixed column grid |
+| `grid grid-cols-3` | `<Grid columns={{ base: 1, md: 3 }}>` | Responsive grid |
+| `items-center` | `alignItems="center"` | Same prop name |
+| `justify-between` | `justifyContent="space-between"` | Same prop name |
+| `justify-center` | `justifyContent="center"` | Same prop name |
+| `container mx-auto` | `maxW="breakpoint-xl" mx="auto"` | Centered container |
+| `w-full` | `w="full"` | Full width |
+| `h-screen`, `min-h-screen` | `h="100vh"` or `minH="dvh"` | Full viewport height |
+| `space-y-4` | `display="flex" flexDir="column" gap="4"` | Use gap, not space utilities |
+| `space-x-4` | `display="flex" flexDir="row" gap="4"` | Use gap, not space utilities |
+| `divide-y` | Individual `borderBottom` on items or use gap + border approach | No direct equivalent |
+
+**VStack vs HStack vs Grid vs Flex decision tree:**
+
+| Layout Need | Use | Example |
+|---|---|---|
+| Stack items vertically with uniform gap | `<VStack gap="...">` | Form fields, card list |
+| Stack items horizontally with uniform gap | `<HStack gap="...">` | Button groups, icon + text |
+| Items need to wrap to next line | `<Flex wrap="wrap" gap="...">` | Tags, chips, badges |
+| Fixed column/row structure | `<Grid columns={...}>` | Card grid, dashboard |
+| Complex alignment + spacing | `display="flex"` with props | Custom layouts |
+
+**Responsive breakpoint translation:**
+
+| Source (Tailwind) | Discourser (Panda CSS) | Min Width |
+|---|---|---|
+| `sm:` | `sm:` or `{ sm: value }` | 640px |
+| `md:` | `md:` or `{ md: value }` | 768px |
+| `lg:` | `lg:` or `{ lg: value }` | 1024px |
+| `xl:` | `xl:` or `{ xl: value }` | 1280px |
+| `2xl:` | `2xl:` or `{ '2xl': value }` | 1536px |
+
+**Two responsive syntax forms** (show both):
+
+```tsx
+// Object syntax (JSX props) — preferred for component props
+<Box p={{ base: '4', md: '6', lg: '8' }}>
+<Grid columns={{ base: 1, md: 2, lg: 3 }}>
+
+// CSS utility syntax — preferred for css() calls
+const styles = css({
+  p: { base: '4', md: '6', lg: '8' },
+  display: { base: 'block', md: 'grid' },
+  gridTemplateColumns: { md: 'repeat(2, 1fr)', lg: 'repeat(3, 1fr)' },
+});
+```
+
+**Common page layout patterns** (from overview-patterns.mdx, translated):
+
+Show 3-4 common compositions:
+1. **Page shell** — sidebar + main content area
+2. **Form layout** — VStack of labeled fields with action buttons
+3. **Card grid** — responsive grid of Card components
+4. **Centered content** — max-width container with centered content
+
+For each, show the Figma auto-layout structure alongside the Discourser implementation.
+
+**Common Mistakes** section:
+
+```tsx
+// ❌ WRONG: Using Tailwind's space utilities
+<div className="space-y-4">
+
+// ✅ CORRECT: Using flex + gap
+<VStack gap="4">
+
+// ❌ WRONG: Fixed breakpoint values
+<Box display={{ '640px': 'grid' }}>
+
+// ✅ CORRECT: Named breakpoint tokens
+<Box display={{ sm: 'grid' }}>
+
+// ❌ WRONG: Using px for responsive queries
+@media (min-width: 768px) { ... }
+
+// ✅ CORRECT: Panda CSS responsive syntax
+const styles = css({
+  flexDir: { base: 'column', md: 'row' }
+});
+```
+
+Cross-reference: Link to `Documentation/Guidelines/99-Overview Patterns` for complete composition examples.
+
+---
+
+### File 2: `stories/documentation/figma-translation/07-ExtensionGuide.mdx`
+
+**Storybook sidebar:** `Documentation/Figma Translation/07-Extension Guide`
+
+```tsx
+import { Meta } from '@storybook/addon-docs/blocks';
+<Meta title="Documentation/Figma Translation/07-Extension Guide" />
+```
+
+This file documents how to maintain and extend the translation suite. It's the "meta-doc" that ensures consistency as the design system evolves.
+
+**Sections to include:**
+
+#### 1. Adding a New Component Mapping
+
+Provide the exact template:
+
+```markdown
+### [ComponentName]
+
+**Maps from:** [Figma equivalent], [Shadcn equivalent]
+**Import:** `import { [ComponentName] } from '@discourser/design-system'`
+**Type:** Simple (recipe) | Compound (slot recipe)
+**Added in:** v[X.Y.Z]
+
+| Source (Figma/Shadcn) Prop | Discourser Prop | Values | Notes |
+|---|---|---|---|
+
+**Compound Anatomy (if applicable):**
+- `<ComponentName.Root>` — [purpose]
+- `<ComponentName.Part>` — [purpose]
+```
+
+Step-by-step process:
+1. Check if component is recipe or slotRecipe in `panda.config.ts`
+2. Read source file in `src/components/[ComponentName].tsx` for anatomy
+3. Read guideline MDX in `stories/documentation/guidelines/components/[name].mdx` for variants/props
+4. Find the closest Shadcn equivalent (if any) from [shadcn/ui docs](https://ui.shadcn.com)
+5. Add entry to `05-Components.mdx` in the appropriate group
+6. Add cross-reference link to component's guideline MDX
+
+#### 2. Adding a New Token Mapping
+
+For each token type, specify which file to update:
+
+| Token Type | File to Update | Table to Add Entry To |
+|---|---|---|
+| Background color | `01-Colors.mdx` | Background colors table |
+| Text color | `01-Colors.mdx` | Text colors table |
+| Border color | `01-Colors.mdx` | Border colors table |
+| Typography | `02-Typography.mdx` | Text size or font mapping table |
+| Spacing | `03-Spacing.mdx` | Numeric or named token table |
+| Shadow | `04-Shadows-Radii.mdx` | Shadow mapping table |
+| Border radius | `04-Shadows-Radii.mdx` | Border radius table |
+
+Process:
+1. Verify new token exists in `panda.config.ts` (run `pnpm prepare` to regenerate)
+2. Find the closest Tailwind/Shadcn equivalent
+3. Add row to appropriate table maintaining column format: Source | Discourser | Notes
+4. Run verification test: `pnpm test -- --grep translation` (STORY-011)
+
+#### 3. Adding a New Color Palette
+
+When a new palette bridge is created (using `create-palette-bridge.ts`):
+1. Add palette name to `01-Colors.mdx` colorPalette system section
+2. Add background/text/border entries for the new palette
+3. Update `05-Components.mdx` — any components that support `colorPalette` need the new value listed
+4. Run verification tests
+
+#### 4. Versioning & Maintenance
+
+When to re-verify translation docs:
+- Any change to `panda.config.ts` semantic tokens
+- Any new component added to `src/components/index.ts`
+- Any recipe/slotRecipe modification (new variants, renamed props)
+- Any design system version bump
+- After running `pnpm prepare` if token output changes
+
+How to verify:
+```bash
+# Run all translation verification tests (STORY-011)
+pnpm test -- --grep translation
+
+# Or manually check Storybook render
+pnpm storybook
+# Navigate to Documentation/Figma Translation and verify each page
+```
+
+#### 5. Relationship to Kai Sidecar Knowledge
+
+The translation MDX files are comprehensive (for human + MCP consumption). Kai's sidecar knowledge fragments (`_bmad/_memory/kai-sidecar/knowledge/`) are **condensed extracts** optimized for agent context:
+- Tables only, no prose explanations
+- No Common Mistakes sections (Kai's instructions.md handles error prevention)
+- Fragment per concern (colors, typography, components, layout) for selective loading
+
+When updating translation MDX, also update the corresponding sidecar fragment (STORY-008).
+
+#### 6. Document Conventions
+
+- All tables: First column = Source/external term, Second column = Discourser equivalent
+- All MDX files start with `import { Meta }` and `<Meta title="Documentation/Figma Translation/[XX-Name]" />`
+- Common Mistakes in each file use ❌/✅ pattern
+- Cross-references use Storybook page titles, not file paths
+- File naming: `XX-Name.mdx` where XX is zero-padded number for sort order
+
+---
+
+## DO NOT
+
+- Change any existing files (00-05.mdx)
+- Modify source code or config
+- Install packages
+
+---
+
+## Acceptance Criteria
+
+- [ ] `06-Layout.mdx` created with layout primitive mapping, decision tree, responsive breakpoints, and page composition patterns
+- [ ] `07-ExtensionGuide.mdx` created with templates for components, tokens, palettes + versioning process
+- [ ] Layout file covers VStack/HStack/Grid/Flex with decision guidance
+- [ ] Responsive breakpoint table with both syntax forms
+- [ ] Extension guide has copy-pasteable templates for each type of addition
+- [ ] Versioning section documents when/how to re-verify
+- [ ] Kai sidecar relationship documented
+- [ ] Both files render in Storybook without MDX parse errors
+- [ ] Conventions section ensures future contributors maintain consistency
+- [ ] Common Mistakes section in layout file with ❌/✅ patterns

package/docs/active-stories/STORY-008-kai-sidecar-fragments.md

@@ -0,0 +1,137 @@
+# STORY-008: Extract Kai Sidecar Knowledge Fragments
+
+> **Epic:** Kai Agent — Design System MCP Integration
+> **Depends on:** STORY-006 (all parts), STORY-007 (sidecar structure scaffolded)
+> **Estimate:** 2-3hr
+> **Note:** This story executes in the **Discourser.ai** project, not the design system repo. However, the source content comes from the design system's translation docs. This file documents what to extract and how.
+
+---
+
+## Context
+
+STORY-006 created comprehensive Figma Translation MDX docs in Storybook — designed for human readability and MCP queryability. The Kai agent needs **condensed extracts** optimized for LLM context loading:
+- Tables only, no prose explanations
+- No Common Mistakes sections (Kai's `instructions.md` handles error prevention)
+- One fragment per concern for selective loading via `kai-index.csv`
+- Total fragment size per task stays under agent context budget
+
+This story extracts the translation MDX content into Kai-optimized sidecar fragments.
+
+---
+
+## Prerequisites
+
+1. **STORY-006 complete** — All 8 translation MDX files exist in `Discourser-Design-System/stories/documentation/figma-translation/`
+2. **STORY-007 complete** — Kai sidecar structure exists at `_bmad/_cfg/agents/kai/kai-sidecar/knowledge/`
+3. **STORY-011 complete (recommended)** — Translation docs verified as accurate before extracting
+
+---
+
+## Deliverables
+
+All files go in the Discourser.ai project's Kai sidecar knowledge directory:
+```
+_bmad/_cfg/agents/kai/kai-sidecar/knowledge/
+```
+
+### Fragment 1: `figma-translation-colors.md`
+
+**Source:** `01-Colors.mdx`
+**Extract:** All mapping tables (backgrounds, text, border, M3 surface, colorPalette). Strip prose, keep only tables and the colorPalette system rules (available palettes, when to use colorPalette vs direct token).
+
+### Fragment 2: `figma-translation-typography.md`
+
+**Source:** `02-Typography.mdx`
+**Extract:** Text size mapping table, font family table, font weight table, Header component size mapping. Strip prose.
+
+### Fragment 3: `figma-translation-spacing.md`
+
+**Source:** `03-Spacing.mdx`
+**Extract:** Numeric scale table, named token table, Figma auto-layout translation table. Strip prose.
+
+### Fragment 4: `figma-translation-shadows-radii.md`
+
+**Source:** `04-Shadows-Radii.mdx`
+**Extract:** Shadow mapping table, border radius table. Strip prose.
+
+### Fragment 5: `figma-translation-components.md`
+
+**Source:** `05-Components.mdx`
+**Extract:** All component entries with their type (recipe/slotRecipe), import path, key props, and compound anatomy. This will be the largest fragment. Consider splitting into `figma-translation-components-interactive.md` and `figma-translation-components-compound.md` if too large for single context load.
+
+### Fragment 6: `layout-patterns.md`
+
+**Source:** `06-Layout.mdx`
+**Extract:** Layout primitive mapping table, decision tree, responsive breakpoint table. Strip page composition examples (Kai can query Storybook MCP for those).
+
+### Fragment 7: `component-catalog.md`
+
+**Source:** Component guidelines in `stories/documentation/guidelines/components/` + `05-Components.mdx`
+**Content:** Quick-reference catalog of all components with: name, type, variants, sizes, import path. One table, all components. This is the "at a glance" view Kai checks before diving into specific component details.
+
+### Fragment 8: `token-decision-trees.md`
+
+**Source:** Design token MDX files in `stories/documentation/guidelines/design-tokens/` + translation files
+**Content:** Decision trees for common token choices:
+- Which background token? (canvas vs surface vs surfaceContainer vs component default)
+- Which text color? (fg.default vs fg.muted vs fg.subtle vs onSurface)
+- Which shadow? (none vs xs vs sm vs md vs lg — with component context)
+- Which border radius? (l1 vs l2 vs l3 vs none vs full — with component context)
+
+### Update: `kai-index.csv`
+
+Map task types to fragments:
+
+```csv
+task,fragment,description
+color-mapping,figma-translation-colors.md,Figma/Tailwind/Shadcn color → Discourser token mapping
+typography-mapping,figma-translation-typography.md,Text size/font/weight translation
+spacing-mapping,figma-translation-spacing.md,Spacing scale + auto-layout translation
+shadow-radius-mapping,figma-translation-shadows-radii.md,Shadow + border radius translation
+component-selection,figma-translation-components.md,Full component mapping with props and anatomy
+layout-decisions,layout-patterns.md,VStack/HStack/Grid/Flex selection + responsive patterns
+component-catalog,component-catalog.md,Quick-reference: all components at a glance
+token-decisions,token-decision-trees.md,Decision trees for semantic token selection
+design-translate-full,figma-translation-colors.md;figma-translation-typography.md;figma-translation-spacing.md;figma-translation-shadows-radii.md;figma-translation-components.md;layout-patterns.md,Full context for DT workflow
+design-validate,component-catalog.md;token-decision-trees.md;figma-translation-components.md,Context for DV (validation) workflow
+```
+
+---
+
+## Extraction Rules
+
+1. **Tables only** — Remove all prose paragraphs, introductions, and explanations
+2. **Keep column headers** — Every table must retain its header row
+3. **Keep section headers** — Use `##` for sections within a fragment so Kai can navigate
+4. **No Common Mistakes** — Kai's `instructions.md` handles this via critical_actions
+5. **No cross-references** — Kai loads fragments directly, doesn't follow Storybook links
+6. **Add fragment header** — Each file starts with:
+   ```markdown
+   # [Fragment Title]
+   > Source: stories/documentation/figma-translation/[XX-File.mdx]
+   > Last synced: [date]
+   > Design System version: [version from package.json]
+   ```
+7. **Size budget** — Each fragment should be under 2000 tokens. If larger, split.
+
+---
+
+## Verification
+
+After extraction:
+1. Spot-check 5 random entries from each fragment against the source MDX — they must match
+2. Load the `design-translate-full` fragment set via kai-index.csv — total size should be reasonable for agent context
+3. Give Kai a test query: "Translate a Figma card with primary background, 16px padding, medium shadow, containing a heading and body text" — verify the spec output references correct tokens
+
+---
+
+## Acceptance Criteria
+
+- [ ] 8 knowledge fragments created in Kai sidecar
+- [ ] `kai-index.csv` updated with all task-to-fragment mappings
+- [ ] Each fragment has header with source file, sync date, and version
+- [ ] Tables-only format (no prose except section headers)
+- [ ] Each fragment under 2000 tokens
+- [ ] `design-translate-full` fragment set covers all translation content
+- [ ] Spot-check accuracy: 5 random entries per fragment match source MDX
+- [ ] Fragment loading via kai-index.csv works correctly