# TVU Design System — Figma Sync Pipeline

## Workflow

### When Figma design changes
Re-run the Figma extraction (requires a valid Figma Personal Access Token in `.env`):
1. Open Figma and this Claude session
2. Set a real `FIGMA_TOKEN` in `.env`
3. Run `pnpm sync:extract` to update `figma-data/raw/`
4. Run: `pnpm generate`
5. Commit `figma-data/` + updated components

### Day-to-day (no Figma changes)
```bash
pnpm sync:extract
pnpm generate   # regenerate src/ from figma-data/ (no Figma needed)
pnpm audit:design-system
pnpm test       # verify nothing broke
```

## Files

| File | Purpose |
|------|---------|
| `figma-sync/variable-map.mjs` | Figma variable name → CSS custom property |
| `figma-sync/api.mjs` | Authenticated Figma REST API client |
| `figma-sync/extract.mjs` | Export raw Figma variables and component JSON to `figma-data/raw/` |
| `figma-sync/normalize.mjs` | Add cssVar fields to figma-data/normalized/variables.json |
| `figma-sync/normalize-component-tokens.mjs` | Derive a tokenized component layer in `figma-data/normalized/components-tokenized/` |
| `figma-sync/generate-manifest.mjs` | Generate canonical Figma-first component manifest from the tokenized component layer |
| `figma-sync/generate-tokens.mjs` | Generate src/tokens/variables.css |
| `figma-sync/generate-vue.mjs` | Generate Vue SFC components |
| `figma-sync/audit-design-system.mjs` | Audit undefined tokens, hardcoded colors/fonts, and SVG injection usage in components |
| `figma-sync/sync.mjs` | Orchestrates all generation steps |
| `figma-data/normalized/variables.json` | Source of truth for design tokens |
| `figma-data/normalized/components.manifest.json` | Canonical Figma-first manifest for components and variant props |

## Adding a new component

1. Extract component data from Figma via `pnpm sync:extract`
2. Run `pnpm generate:component-tokens`
3. Run `pnpm generate:manifest`
4. Use the manifest as the source of truth for Code Connect and canonical components
5. Extend `figma-sync/generate-vue.mjs` only when a generated component needs custom implementation logic
6. Run `pnpm generate`