# TVU Design System — Figma Sync Pipeline

## Workflow

### Canonical library sync
```bash
pnpm sync:figma-library --with-extract
```

The orchestrator runs the full canonical pipeline and ends with **Step 14:
`audit:figma-vs-sot`**, which compares published Figma icon components against
the affordance SoT in `docs/internal/affordance-categories/` (sharded by Figma
icon folder; read via `figma-sync/lib/affordance-sot.mjs`). Type A/B/C drift blocks the sync so
newly added, removed, or renamed Figma icons are reviewed before the affordance
SoT drifts. Use `--skip-sot-audit` only for SoT-only refactor work where the
Figma mirror is intentionally not the comparison target.

### 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/audit-figma-vs-sot.mjs` | Audit published Figma icon components against the affordance SoT |
| `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`