# FIGMA_SYNC.md — Updating from Figma

The repo is downstream of Figma. There are **two flavors** of sync: the **bulk token sync** (preferred — uses the DTCG export) and the **node-level sync** (for ad-hoc inspection / individual component pulls via the Figma MCP).

---

## A. Bulk token sync (preferred)

The repo's `/design-tokens/` directory is the canonical token export. Replace it whenever the design system's variables/styles change in Figma.

### Steps

1. In Figma, open the design system file → run the **Tokens plugin** (the one that exports DTCG-format with a `manifest.json` + per-mode files).
2. Export to a folder. **Replace** `/design-tokens/` in this repo with that folder's contents.
3. Run:
   ```bash
   pnpm tokens:build
   ```
4. Inspect the diff:
   ```bash
   git diff packages/tokens/dist packages/tokens/src/_generated.ts
   ```
5. If everything looks right, commit. If a token was renamed and breaks usage, search/replace across `apps/` and `packages/react/`.

### Prompt template (for AI agent)

> Sync tokens. I just re-exported `/design-tokens/`. Run `pnpm tokens:build`, summarize the diff, flag any breaking renames in component code, and propose fixes.

The agent will then:
1. Run the build and show what changed in `dist/tokens.css`
2. Grep for any token names that disappeared (likely renamed)
3. Update component code if needed
4. Append a `CHANGELOG.md` entry

---

## B. Node-level sync (Figma MCP)

For pulling a single component or inspecting a specific frame, use the Figma MCP tools directly.

### Prompt template

> Sync from Figma node: `<figma-url>`
> What changed: `<short description>`
> Update: `<component | gradient | docs>`

### Recipes

**Update a component implementation** (`packages/react/src/components/<name>.tsx`):
1. `mcp__figma__get_design_context(nodeId, fileKey)` — read structure + styles
2. Compare to existing component
3. Patch the `cva` variants — never inline a hex; if a new color is needed, **add it to Figma + re-export** (don't shortcut)
4. Update the MDX page
5. Changelog entry

**Add a new component**:
1. `mcp__figma__get_metadata` on the parent frame to inventory
2. `mcp__figma__get_design_context` on the component node
3. Check `packages/react/src/components/` for any primitive that fits — don't duplicate
4. Generate following `DESIGN.md` §6
5. MDX page + sidebar entry
6. Changelog entry

### Prerequisites

- Figma desktop app open with the relevant frame **selected** (MCP can't read variables/context without a selection)
- URL must include `node-id`

---

## C. Important — do not shortcut

The `/design-tokens/` export is the only legitimate way to add/rename a semantic token. If you encounter an unmet need:

- **Right way**: add it to Figma → re-export → re-run `pnpm tokens:build`
- **Wrong way**: edit `packages/tokens/src/_generated.ts` (gets overwritten)
- **Wrong way**: hardcode a hex in a component (violates `DESIGN.md` §1 forbidden patterns)

The only files in `packages/tokens/src/` you should hand-edit are:
- `gradients.ts` — until the styles-file importer lands
- `shadows.ts` — same
- `index.ts` — to expose new categories

---

## D. Field reference: DTCG path → CSS var

| Figma path | CSS var | Tailwind |
|---|---|---|
| `Semantics.background.base` | `--background` | `bg-background` |
| `Semantics.foreground.base` | `--foreground` | `text-foreground` |
| `Semantics.foreground.muted` | `--foreground-muted` | `text-muted-foreground` |
| `Semantics.button.primary.fill` | `--button-primary` | `bg-primary` |
| `Semantics.button.primary.foreground` | `--button-primary-foreground` | `text-primary-foreground` |
| `Semantics.card.fill` | `--card` | `bg-card` |
| `Semantics.popover.fill` | `--popover` | `bg-popover` |
| `Semantics.border.default` | `--border-default` | `border-border` |
| `Semantics.border.focus` | `--border-focus` | `border-focus` |
| `Semantics.sidebar.*` | `--sidebar-*` | `bg-sidebar`, etc. |
| `Liquid colors.Lilac.Full` | (not a CSS var; access via `liquid` export) | n/a |