@design-ai/cli 4.55.0

package/docs/DOGFOOD-V4-NPM-FINDINGS.md

@@ -0,0 +1,157 @@
+# Dogfood findings - npm fresh install (Phase 41, refreshed for v4.13)
+
+End-to-end test of the npm distribution path. Pack the package, install into a clean temp project, run the full CLI lifecycle, and verify symlinks are created and removed against a fake `CLAUDE_HOME`.
+
+**Scope**: real `npm pack` -> real `npm install <tarball>` -> real `design-ai` package bin -> real symlink farm against a temporary Claude Code home.
+
+## Automated procedure
+
+```bash
+npm run package:smoke
+```
+
+`tools/audit/package-smoke.py` now performs the manual dogfood path:
+
+- reuses `tools/audit/smoke_assertions.py` for doctor JSON parsing, `doctor --strict` human diagnostics, ANSI detection, and required-check assertions
+- installs the packed `.tgz` into a fresh temp npm project
+- verifies `node_modules/.bin/design-ai` exists
+- runs human and JSON `version`, top-level `help`, `help --json`, every expected public `design-ai help <command>` topic with usage assertions, every documented help alias, every documented command alias with output assertions, functional aliases (`find`, `cat`, `recommend`, `example`, `ex`, `ls`, `lint`), human and JSON `list skills` / `list commands` / `list agents`, human and JSON `search` / `show` / `examples` / `check` output, explicit `show --lines` ranges and `route --explain` output, unknown route-id/option/value suggestion and numeric range failures, `install`, `doctor --json`, `doctor --strict`, human and JSON `status`, and `uninstall` with lifecycle output assertions
+- verifies prompt/pack `--out --force` file writes by seeding an existing file, then checking both the generated artifact content and the `Wrote <path>` confirmation output
+- asserts every required `doctor --json` package/release/install check reports `PASS` and `doctor --strict` prints the complete clean diagnostics summary
+- uses a fake `CLAUDE_HOME` and `DESIGN_AI_PREFIX=smoke-design-`
+- sets `NO_COLOR=1` and fails if wrapped commands emit ANSI escape sequences
+- runs a local tarball `npm exec --package ... -- design-ai ...` path to simulate one-shot `npx`, including its own human/JSON version and top-level help checks, `help --json` catalog read, help topic usage, help alias, command alias, functional alias output, human and JSON list catalog, corpus discovery smoke, explicit `show --lines` ranges, `route --explain` output, JSON `check` report smoke, unknown route-id/option/value suggestion and numeric range failures, prompt/pack forced file-write confirmation smoke, and install/`doctor --strict`/human+JSON status/uninstall lifecycle output assertions
+- asserts the `doctor --json` required PASS set for both direct install and one-shot `npm exec` install
+
+The local `npm run release:check` gate and the GitHub audit/publish/release workflows call `npm run release:self-test`, which runs the audit runner, coverage timestamp preservation, doctor, shared smoke, package smoke, registry smoke, and release metadata assertion self-tests before package contents or tarball smoke checks. The same package smoke runs in publish/release workflows after `npm pack`. Release metadata also fails with structured bullet errors if a required release policy doc drops out of the checked set, an unexpected policy doc enters it, the checked docs order drifts, a required policy doc is missing from disk, a core release input is missing, unreadable, or invalid JSON, or the audit-count source cannot be loaded or parsed. Its JSON output keeps stable summary keys, checked-doc order, and readable Korean structured errors. `design-ai check`, `design-ai route`, `design-ai prompt`, `design-ai pack`, `design-ai examples`, `design-ai search`, `design-ai show`, `design-ai help`, `design-ai doctor`, `design-ai list`, `design-ai status`, `design-ai audit`, and `design-ai version` now also route machine-readable reports through self-tested JSON formatters so smoke assertions keep validating the same automation-facing shape.
+
+## Current result
+
+Latest local tarball smoke:
+
+```text
+@design-ai/cli@4.13.0
+package size: 1.4 MB
+unpacked size: 4.5 MB
+total files: 500
+Smoke assertions self-test passed
+Release metadata self-test passed
+Package smoke passed
+```
+
+The installed-package doctor reported:
+
+```text
+Summary: 16 pass, 0 warning(s), 0 failure(s)
+Audit scripts: 8 repository audit script(s) found
+Doctor assertions helper: tools/audit/doctor_assertions.py found
+Smoke assertions helper: tools/audit/smoke_assertions.py found
+Package contents check: tools/audit/package-contents.py found
+Package smoke check: tools/audit/package-smoke.py found
+Registry smoke check: tools/audit/registry-smoke.py found
+Installed skills: 19/19 installed
+Installed agents: 4/4 installed
+Installed slash commands: 16/16 installed
+```
+
+Uninstall removed 39 symlinks: 19 skills + 4 agents + 16 slash commands.
+
+## What worked
+
+### 1. `npm pack` allowlist is release-safe
+
+Shipped: `cli/`, `install.sh`, `AGENTS.md`, `CLAUDE.md`, `CHANGELOG.md`, `LICENSE`, `README.md`, `.claude-plugin/`, `knowledge/`, `examples/`, `skills/`, `agents/`, `commands/`, `docs/`, `tools/audit/`, `tools/migrations/`, and `tools/preview/`.
+
+Not shipped:
+
+- `refs/` (large upstream source material)
+- `tools/extractors/` (dev-only extraction tooling)
+- `vscode-extension/` (separate package surface)
+- `node_modules/`, `.git/`, packed `*.tgz` outputs
+- `cli/**/*.test.mjs` and other test/spec files
+
+### 2. Version alignment resolves end-to-end
+
+`design-ai version` reports both CLI and plugin/corpus version as `4.13.0`. The installer banner also reads the package plugin manifest through the JS wrapper, so the user-facing install path no longer shows a stale legacy version.
+
+### 3. Catalog commands enumerate the shipped corpus
+
+`list skills`, `list commands`, and `list agents` read the packed plugin manifest and enumerate 19 skills, 16 commands, and 4 agents. The smoke assertions verify the section count and expected item names for each domain. `doctor --strict` confirms the installed package has all 39 expected symlink targets.
+
+### 4. Install lifecycle works against fake `CLAUDE_HOME`
+
+Package smoke installs into a temp Claude home, verifies all source/runtime checks are clean, then uninstalls the same symlink set. The symlinks point into the npm-installed package, so package upgrades refresh the installed design corpus without copying stale files.
+
+### 5. `NO_COLOR` behavior is covered
+
+The smoke path sets `NO_COLOR=1` and checks captured CLI output for ANSI escape sequences. This covers CI logs, package smoke logs, and non-interactive install usage.
+
+### 6. Shared smoke assertions are independently covered
+
+`npm run release:self-test` now includes `npm run smoke:assertions:self-test`, which exercises the common helper used by package and registry smoke tests. It proves that ANSI escape detection, malformed doctor JSON handling, and required doctor check failures fail closed before the helper is used inside tarball or registry smoke paths.
+
+### 7. Coverage timestamp preservation is covered
+
+`npm run release:self-test` now includes `npm run coverage:self-test`, which exercises `check-coverage.py` without touching `knowledge/COVERAGE.md`. It proves unchanged reports preserve the existing `generated_at` value while real report content changes refresh the date.
+
+### 8. Audit runner exit-code behavior is covered
+
+`npm run release:self-test` now includes `npm run audit:runner:self-test`, which exercises `run-all.py` without invoking the repository audits. It proves strict mode exits non-zero on failures, warn-only mode keeps exit code 0 while naming failed audits, and the eight-audit release gate count stays explicit.
+
+### 9. Release metadata drift is covered
+
+`npm run release:metadata` now verifies package/plugin version alignment, the top CHANGELOG entry, the current ROADMAP phase, required release sections, the documented eight-audit count, and the release-facing docs' `ci:local` MkDocs warning-policy baseline guidance across README, RELEASE-CHECKLIST, and Distribution docs. It also fails with structured bullet errors if the policy-doc coverage set or audit-count source drifts, and its JSON summary shape is self-tested. This prevents a release from passing when the implementation version and release narrative drift apart, or when English/Korean release guidance loses the docs warning-policy contract, its executable pre-push command, coverage membership, or audit-count grounding.
+
+## Issues surfaced
+
+### 1. `tools/migrations/` missing from npm package - resolved
+
+**Original severity**: MEDIUM.
+
+The v4.7 package omitted `tools/migrations/`, which blocked the documented `/stability-review` workflow for npm adopters. The package allowlist now includes `tools/migrations/`, and the v4.13 dry-run tarball includes those scripts.
+
+### 2. Legacy `install.sh` banner version - resolved
+
+**Original severity**: LOW.
+
+The old install path showed a hardcoded `v3.1` banner. The JS install command now reads `.claude-plugin/plugin.json` and prints `v4.13.0`; the package smoke verifies the shipped install path.
+
+### 3. ANSI color leaked into package smoke logs - resolved
+
+**Original severity**: LOW.
+
+The shell installer previously emitted color escapes in non-interactive smoke output. `install.sh` now disables color when `NO_COLOR` is set or stdout is not a TTY, and `package-smoke.py` fails if wrapped commands emit ANSI escapes.
+
+### 4. `npm test` remains repo-only in installed package - accepted
+
+**Severity**: INFO.
+
+The package intentionally excludes test files. Adopter health is covered by `tools/audit/package-smoke.py` and `design-ai doctor --strict`, while repository correctness remains covered by `npm test` before packing.
+
+## Verified fresh-install path
+
+This dogfood approximates what a clean adopter sees:
+
+1. Install the packed CLI package.
+2. Run human and JSON `design-ai version`, top-level `help`, `help --json`, every expected command-specific help topic from the catalog with usage assertions, every documented help alias, every documented command alias with output assertions, functional aliases (`find`, `cat`, `recommend`, `example`, `ex`, `ls`, `lint`), all three `list` catalog domains in human and JSON mode, human / JSON `search`, `show`, `examples`, and `check`, explicit `show --lines` ranges and `route --explain` output, unknown route-id/option/value suggestion and numeric range failures, and prompt/pack forced file-output flows.
+3. Run `design-ai install` against an empty Claude Code home and assert the installer reports 19 skills, 4 agents, and 16 slash commands.
+4. Run `design-ai audit --strict --quiet`, `design-ai audit --strict --quiet --json`, `design-ai doctor --strict`, `design-ai status`, and `design-ai status --json`, asserting the audit reports all 8 checks passing, doctor reports 16 pass / 0 warnings / 0 failures, and status reports the same installed counts in human and JSON mode.
+5. Run `design-ai uninstall` and assert the symlink farm removal reports 39 removed links.
+6. Run the same lifecycle through local tarball `npm exec --package ...` to cover the `npx`-style bin path, including independent human/JSON version and top-level help checks, `help --json` catalog read, documented help topic usage and alias smoke, command alias smoke, functional alias smoke, human and JSON list catalog smoke, corpus discovery smoke, explicit `show --lines` ranges and `route --explain` output, unknown route-id/option/value suggestion and numeric range failures, prompt/pack forced file-write confirmation smoke, lifecycle output smoke, `doctor --strict` human diagnostics assertions, status JSON assertions, and the same `doctor --json` PASS assertions.
+
+The path confirms package contents, bin shim creation, one-shot npm execution, version alignment, machine-readable version metadata JSON shape, machine-readable help-topic catalog JSON shape, route recommendation JSON shape, prompt-plan JSON shape, prompt-context bundle JSON shape, worked-example discovery JSON shape, corpus search JSON shape, corpus file JSON shape, doctor diagnostics JSON shape, manifest list catalog JSON shape, install-status JSON shape, manifest catalog enumeration, human-readable corpus discovery, artifact quality check JSON shape, explicit line-range display, route explanation details, route-id, option, search-directory value typo recovery, and numeric range validation, prompt/pack forced file-write UX, symlink creation, symlink cleanup, Korean character handling in catalog output, and no-color smoke logs.
+
+## What this does not validate
+
+- Windows install behavior; POSIX symlinks may need a separate implementation.
+- Corporate npm proxy, sandboxed shell, or restricted filesystem environments.
+- Concurrent `design-ai install` executions.
+- Actual `npm publish`, which would push to the public registry.
+- Public-registry `npx @design-ai/cli install`; package smoke covers the equivalent local tarball `npm exec --package` path before publish.
+
+## Cross-reference
+
+- [`docs/DOGFOOD-V4-FINDINGS.md`](DOGFOOD-V4-FINDINGS.md) - Phase 39 corpus content dogfood
+- [`docs/DOGFOOD-V4-VSCODE-FINDINGS.md`](DOGFOOD-V4-VSCODE-FINDINGS.md) - Phase 40 VS Code extension dogfood
+- [`docs/RELEASE-CHECKLIST.md`](RELEASE-CHECKLIST.md) - pre-release verification checklist
+- `tools/audit/package-smoke.py` - automated npm tarball smoke

package/docs/DOGFOOD-V4-VSCODE-FINDINGS.md

@@ -0,0 +1,135 @@
+# Dogfood findings — VS Code extension (Phase 40)
+
+Headless validation of the VS Code extension that was scaffolded in v3.8 and extended in v4.3 / v4.6 with new commands.
+
+**Scope of this dogfood**: extension's pure logic (search algorithm, walkthrough pairing, README picking, manifest reading, glob/path utilities), shippability check via `.vsix` packaging, and command-manifest ↔ implementation parity.
+
+**Out of scope**: an actual VS Code instance running the extension. That requires `@vscode/test-electron` (boots a headless VS Code) and was deferred to a future pass — the pure-logic surface tested here exercises the parts that historically had bugs.
+
+## What worked
+
+### 1. Pure logic was 100% extractable
+
+The `vscode` API touches surface (window dialogs, quick-pick UI, document opening) is *small* relative to the work each command does. The work itself — file traversal, search matching, language-pair resolution, glob conversion — is pure Node.js. Extracted to `src/lib.ts`.
+
+After extraction:
+- `src/commands.ts` shrank from 423 → 310 lines (27% smaller).
+- All non-`vscode` logic is now testable via `node --test`.
+- 25 unit tests pass against `out/lib.js` (the *exact JS that ships*, not a transpiled shadow).
+
+### 2. .vsix builds cleanly
+
+After 2 fixes (below), `npx @vscode/vsce package` produces `design-ai-vscode-0.2.0.vsix`:
+- 13 files, 19.65 KB packed.
+- 5 compiled JS files + 2 icons + LICENSE + CHANGELOG + README + manifest.
+- No `src/`, `test/`, `*.map`, `node_modules/`, or `.vsix` regressions.
+
+### 3. Command-manifest ↔ implementation parity verified
+
+10 commands in `package.json` `contributes.commands`, 10 commands registered via `vscode.commands.registerCommand` in source. Zero drift.
+
+### 4. Compile remains clean
+
+`tsc --noEmit` zero errors after the lib extraction. TypeScript types caught two small issues during the refactor (one `null` vs `undefined`, one missing return type) before tests ran.
+
+## Bugs surfaced — and fixed
+
+### 1. Search preview lost the matching keyword
+
+**Found by**: writing `searchCorpus("Pretendard")` test asserting the preview contains "pretendard".
+
+**Symptom**: 6 of ~20 hits had previews that didn't contain the search term. The preview was always `line.trim().slice(0, 120)` from line *start*. If the match appeared past character 120, the user saw context but not the match.
+
+**Example before**:
+```
+file: docs/QUICKSTART.md:57
+preview: /design-from-brief Korean fintech for freelancers — invoice, expense tracking, tax estimation. Trustworthy, calm, mobile
+                                                                                                                       ^^^ truncated; actual match "Pretendard" was at column 142 ^^^
+```
+
+**Fix**: introduced `buildPreview(line, query)` that centers the preview on the match. ~50 chars before + match + remainder, with `…` markers on either side.
+
+**After**:
+```
+preview: …calm, mobile-first. **Pretendard** typography. Compliance with…
+```
+
+This is a real adopter-facing improvement — search results that don't show the matched term are confusing.
+
+### 2. Missing icon.png
+
+**Found by**: `vsce package` failure with `ERROR The specified icon 'extension/media/icon.png' wasn't found in the extension.`
+
+**Symptom**: `package.json` declared `"icon": "media/icon.png"` but only `media/icon.svg` existed. The extension would have failed to publish to the marketplace.
+
+**Fix**: generated a 128x128 PNG via PIL, matching the SVG's brand-teal gradient + white "D".
+
+This is a **must-fix** before VS Code marketplace publish.
+
+### 3. test/ directory leaked into .vsix
+
+**Found by**: inspecting the `.vsix` content listing — `test/lib.test.mjs` was in the package.
+
+**Symptom**: tests bloat the package by ~2KB and ship test fixtures to adopters.
+
+**Fix**: added `test/**` and `*.vsix` to `.vscodeignore`.
+
+After fix: 14 files → 13 files, 21.96 KB → 19.65 KB.
+
+## Bugs not fixed (deferred)
+
+### 4. No headless VS Code integration test
+
+The pure-logic tests are necessary but not sufficient. The `vscode` API surface (window.showQuickPick, workspace.openTextDocument, configuration.get) isn't covered. A real adopter session could surface bugs in:
+- Quick-pick item rendering (long labels truncating).
+- Configuration change propagation.
+- Tree provider refresh on file changes.
+
+**Action**: add `@vscode/test-electron` in a future phase. ~150 LOC + a CI matrix entry (Linux + macOS).
+
+### 5. No icon at intended quality
+
+The PIL-generated icon is functional but not the polished brand icon a real launch would ship. It looks like a placeholder.
+
+**Action**: replace with a designer-rendered 128x128 PNG before marketplace publish. This is launch-blocker-only.
+
+### 6. Configuration onChange handler edge cases
+
+`vscode.workspace.onDidChangeConfiguration` triggers a full tree refresh when `design-ai.path` changes — but if the new path is invalid, the trees clear without surfacing an error. Adopters might think the extension broke.
+
+**Action**: surface a warning in the new path is invalid (re-run `findDesignAiPath()` and message if it returns undefined).
+
+## What this validates
+
+- Extension code shape is correct — lib/cmds split is testable.
+- Manifest is internally consistent.
+- `.vsix` ships clean (after gitignore fix).
+- All 10 commands route to actual handlers.
+- Search algorithm now correct.
+
+## What this does NOT validate
+
+- Actual UI rendering inside VS Code.
+- Configuration change handling under real VS Code load.
+- Tree providers' performance on large knowledge corpora.
+- Marketplace publish flow (needs Azure DevOps PAT setup).
+
+These are real-VS-Code-instance concerns — Phase 40 stops at the boundary.
+
+## File-level summary
+
+| File | Status |
+| --- | --- |
+| `vscode-extension/src/extension.ts` | Unchanged |
+| `vscode-extension/src/commands.ts` | Refactored to import from lib.ts (310 lines, was 423) |
+| `vscode-extension/src/lib.ts` | **New** — 8 pure helpers (searchCorpus / pairWalkthroughs / chooseWalkthrough / readManifest / pickReadme / walkMd / globToRegex / splitGlob) |
+| `vscode-extension/src/paths.ts` | Unchanged |
+| `vscode-extension/test/lib.test.mjs` | **New** — 25 unit tests |
+| `vscode-extension/.vscodeignore` | Updated — exclude `test/`, `*.vsix` |
+| `vscode-extension/media/icon.png` | **New** — 128x128 placeholder (designer should replace) |
+
+## Cross-reference
+
+- [`docs/DOGFOOD-V4-FINDINGS.md`](DOGFOOD-V4-FINDINGS.md) — Phase 39 dogfood (corpus content)
+- Phase 41 — npm fresh-install test (next)
+- Phase 42 — mkdocs site build verification (after npm)

package/docs/FIGMA-INTEGRATION.md

@@ -0,0 +1,222 @@
+# Figma integration
+
+How design-ai outputs flow into and out of Figma. This is the bridge between agent-generated artifacts (markdown specs, JSON tokens) and the visual surface designers actually edit in.
+
+## The two-way relationship
+
+```
+                  ┌────────────────────────────┐
+                  │  design-ai (this repo)     │
+                  │  knowledge/, skills/,      │
+                  │  examples/, refs/          │
+                  └────────────────────────────┘
+                       ▲                  │
+                       │ extract          │ generate
+                       │                  ▼
+                  ┌────────────────────────────┐
+                  │           Figma            │
+                  │  Variables · Components    │
+                  │  Styles · Code Connect     │
+                  └────────────────────────────┘
+```
+
+Two flows:
+
+1. **design-ai → Figma**: agent generates tokens / specs; designer applies them in Figma as variables, styles, and component documentation.
+2. **Figma → design-ai**: agent reads existing Figma file; extracts tokens or specs; cross-checks against the knowledge base.
+
+## Tooling layers
+
+### Figma MCP (Model Context Protocol)
+
+The official Figma MCP server lets any AI agent that supports MCP read Figma files structurally. In Claude Code:
+
+- `mcp__Figma__get_metadata` — file structure
+- `mcp__Figma__get_design_context` — selected node's design context (tokens, styles, components used)
+- `mcp__Figma__get_variable_defs` — extract Figma Variables (the closest thing to design tokens in Figma's model)
+- `mcp__Figma__get_screenshot` — render a frame as an image
+- `mcp__Figma__get_code_connect_map` / `add_code_connect_map` — Code Connect mapping between Figma components and code
+
+Codex CLI: install the Figma MCP server in your `~/.codex/mcp.json` (Anthropic-compatible MCP config). Same tool names.
+
+### Figma Variables (design tokens)
+
+Figma Variables are Figma's first-class design token system (introduced 2023). They support:
+
+- **Color** (with mode/theme support — light/dark)
+- **Number** (spacing, radius, sizes)
+- **String** (text — labels, content)
+- **Boolean** (visibility, switch state)
+
+Variables are **the bridge token format**. Agent generates a token JSON (Style Dictionary or W3C DTCG); a designer (or a plugin) imports into Figma Variables.
+
+### Code Connect
+
+Figma Code Connect lets you map a Figma component to a real code component. Once mapped, `Inspect` panel shows the actual code snippet, including imports.
+
+For design-ai: when the agent specs a component (via `component-spec-writer`), include a `Code Connect mapping` section pointing at the production component. The designer then connects in Figma.
+
+## Workflow A: Token export from design-ai → Figma
+
+Goal: a palette/token set generated by `color-palette` skill lands in Figma as Variables.
+
+### Step 1 — Generate tokens
+
+Use the `color-palette` skill. Output should be Style Dictionary JSON (this is the most importable format).
+
+Reference: [examples/palette-saas-violet.md](../examples/palette-saas-violet.md)
+
+### Step 2 — Convert to Figma Variables JSON
+
+Figma Variables can be imported via:
+- The official **Tokens Studio plugin** ([free tier](https://tokens.studio/)) — supports Style Dictionary imports.
+- **Variables2CSS / variables-from-json plugins** — reverse direction.
+- **Figma's REST API** — programmatic import, requires a Figma access token.
+
+Tokens Studio JSON shape (compatible target for our extractor):
+
+```json
+{
+  "global": {
+    "color": {
+      "primary": {
+        "50":  { "value": "#F5F3FF", "type": "color" },
+        "500": { "value": "#8B5CF6", "type": "color" },
+        "600": { "value": "#7C3AED", "type": "color" }
+      }
+    }
+  }
+}
+```
+
+Our `Style Dictionary` output already matches this shape.
+
+### Step 3 — Import in Figma
+
+1. Open the target Figma file.
+2. Install the **Tokens Studio for Figma** plugin.
+3. `Plugins → Tokens Studio → Import` → paste JSON → choose theme set.
+4. `Apply to Figma` — creates/updates Variables. The variables are ready to assign to layers.
+
+### Step 4 — Roundtrip verification
+
+After Tokens Studio imports, verify in Figma:
+- Open `Local variables` panel (right sidebar → Variables).
+- Confirm each token name + value matches.
+- For multi-mode (light/dark): switch modes; values update.
+
+## Workflow B: Figma → design-ai (read existing design)
+
+Goal: an existing Figma file's tokens/components feed back into the knowledge base or get audited by the agent.
+
+### Step 1 — Connect
+
+Claude Code: invoke `mcp__plugin_design_figma__authenticate` first time. After auth, the file is readable.
+
+Codex CLI: per-session OAuth flow.
+
+### Step 2 — Extract tokens
+
+```
+mcp__Figma__get_variable_defs(file_key="...")
+```
+
+Returns a JSON of all Variables. Store under `refs/figma/<file-name>-variables.json` (gitignored — Figma tokens are private).
+
+### Step 3 — Audit against knowledge
+
+The agent compares the extracted tokens to:
+- [`knowledge/colors/color-theory.md`](../knowledge/colors/color-theory.md) — ramp construction rules
+- [`knowledge/a11y/contrast.md`](../knowledge/a11y/contrast.md) — contrast requirements
+- [`knowledge/design-tokens/ant-design.md`](../knowledge/design-tokens/ant-design.md) — naming conventions
+
+Output: a `ux-audit`-style report identifying missing semantic aliases, weak contrast pairs, naming inconsistencies.
+
+## Workflow C: Component spec → Figma component documentation
+
+Goal: a spec authored by `component-spec-writer` becomes the Description text on the Figma main component.
+
+### Step 1 — Generate the spec
+
+Use the skill. Reference: [examples/component-button.md](../examples/component-button.md).
+
+### Step 2 — Manual paste (current state)
+
+Figma's Component Description supports markdown-flavored text. Paste the full spec body. Figma renders headings, lists, links, code blocks.
+
+### Step 3 — Code Connect (optional but recommended)
+
+Map the Figma main component to the production component. Once mapped:
+
+```ts
+// in your repo, e.g., src/components/Button/Button.figma.tsx
+import { Button } from "./Button";
+import figma from "@figma/code-connect";
+
+figma.connect(Button, "https://figma.com/file/.../Button", {
+  props: {
+    intent: figma.enum("Intent", {
+      Primary: "primary",
+      Danger: "danger",
+    }),
+    size: figma.enum("Size", {
+      Small: "sm",
+      Medium: "md",
+      Large: "lg",
+    }),
+    children: figma.children("Label"),
+  },
+  example: ({ intent, size, children }) => (
+    <Button intent={intent} size={size}>{children}</Button>
+  ),
+});
+```
+
+After running `npx figma connect publish`, the Figma `Inspect` panel shows the actual Button code snippet with the prop values matched to the variant the designer selected.
+
+### Step 4 — Cross-link in spec
+
+The component spec should include a Code Connect section pointing both directions:
+
+```markdown
+## Code Connect
+
+- Figma component: `https://figma.com/file/abc123/...?node-id=4:567`
+- Production code: [`src/components/Button/Button.tsx`](../../../src/components/Button/Button.tsx)
+- Code Connect manifest: [`src/components/Button/Button.figma.tsx`](../../../src/components/Button/Button.figma.tsx)
+```
+
+## Tooling matrix
+
+| Need | Tool |
+| --- | --- |
+| Generate tokens (this repo → JSON) | `color-palette` skill, `design-system-builder` skill |
+| Import tokens into Figma | Tokens Studio plugin, `figma-tokens` CLI, Figma REST API |
+| Read Figma file structurally | Figma MCP (`mcp__Figma__*`), Figma REST API |
+| Generate component code from Figma node | Figma Dev Mode + Code Connect |
+| Sync component code back to Figma | Code Connect (`@figma/code-connect`) |
+| Render frame as image (for visual diff/audit) | `mcp__Figma__get_screenshot` |
+| Apply design-system rules to a Figma file | `mcp__Figma__create_design_system_rules` |
+
+## Limitations / caveats
+
+- **Figma MCP requires the file to be open in Figma desktop / web** in the same account. It's not a server-side reader.
+- **Figma Variables ≠ design tokens 1:1**: Figma doesn't support all token types (no shadow tokens — those go in Effect Styles separately; no motion tokens at all).
+- **Roundtrip is lossy**: importing tokens → exporting back may lose comments and grouping. Treat one direction as authoritative (usually: code/JSON is canonical, Figma is a mirror).
+- **Code Connect mapping is per-component manual work** — no auto-generation. Budget ~10 minutes per component for the initial map.
+- **Figma file URLs are sensitive** — they imply file access. Don't commit Figma URLs to public repos for unreleased designs.
+
+## Recommended setup for this repo
+
+1. Keep canonical tokens in code (this repo's `knowledge/design-tokens/` and `examples/`).
+2. Mirror to Figma via Tokens Studio when designs need them.
+3. Author component specs here (using `component-spec-writer`); paste into Figma component descriptions.
+4. Add Code Connect manifests in the consuming product repo (not here — design-ai stays generic).
+5. Use Figma MCP to read a designer's file when the agent needs to audit, not as a daily workflow tool.
+
+## Cross-reference
+
+- [docs/USING.md](USING.md) — running design-ai with various AI agents
+- [skills/color-palette/PLAYBOOK.md](../skills/color-palette/PLAYBOOK.md) — palette generator
+- [skills/component-spec-writer/PLAYBOOK.md](../skills/component-spec-writer/PLAYBOOK.md) — component spec authoring
+- [examples/palette-saas-violet.md](../examples/palette-saas-violet.md) — Style Dictionary JSON output ready for Tokens Studio import