@design-ai/cli 4.55.0

package/docs/integrations/cursor-walkthrough.md

@@ -0,0 +1,284 @@
+# Cursor walkthrough
+
+A concrete walkthrough of using design-ai with **Cursor IDE**. Picks up where [`docs/CURSOR-INTEGRATION.md`](../CURSOR-INTEGRATION.md) leaves off — that's setup; this is workflow.
+
+## Prerequisites
+
+```bash
+# Install Cursor (cursor.sh)
+# Get design-ai
+git clone https://github.com/sungjin9288/design-ai.git ~/dev/design-ai
+```
+
+## Setup (90 seconds)
+
+### Option A: `.cursorrules` in your consuming project
+
+The most common pattern. Create `.cursorrules` in the project where you want design-ai's expertise:
+
+```bash
+cd ~/projects/my-app
+cat > .cursorrules <<'EOF'
+You are a senior product designer with 20+ years of experience in UI/UX,
+design systems, accessibility (WCAG 2.1 AA), and Korean market design.
+
+For any design task, follow this protocol:
+1. Read /Users/sungjin/dev/design-ai/AGENTS.md (universal entry point).
+2. Read /Users/sungjin/dev/design-ai/knowledge/PRINCIPLES.md (30 load-bearing rules).
+3. Find the matching skill in /Users/sungjin/dev/design-ai/skills/<skill-name>/PLAYBOOK.md.
+4. Apply it. Cite knowledge files for every claim.
+5. For Korean content, default to Pretendard + 해요체 (consumer) or 합쇼체 (formal).
+6. Mark unsourced claims as "(judgment, not sourced)".
+
+Skills available:
+- color-palette, component-spec-writer, ux-audit, design-critique
+- design-system-builder, handoff-spec, design-system-qa, design-pr-review
+- figma-token-sync, design-broadcast, document-author, slide-deck-author
+- motion-designer, illustration-designer, print-designer, video-designer
+- game-ui-designer, conversational-ui-designer, spatial-designer
+
+Skills are at /Users/sungjin/dev/design-ai/skills/<name>/PLAYBOOK.md.
+EOF
+```
+
+Cursor auto-loads `.cursorrules` at chat start.
+
+### Option B: Add design-ai as workspace folder
+
+```
+File → Add Folder to Workspace → ~/dev/design-ai
+```
+
+Then reference files via `@` in chat:
+
+```
+@design-ai/skills/color-palette/PLAYBOOK.md apply this for a teal-blue
+fintech app.
+```
+
+The `@` autocomplete searches your whole workspace; design-ai's structured tree shows up clearly.
+
+## Walkthrough 1: Spec a component inline
+
+**Goal**: working in your app's codebase, ask Cursor to spec a Banner component, then implement it.
+
+### Session
+
+```
+You ▸ (in src/components/Banner.tsx, file open)
+      @design-ai/skills/component-spec-writer/PLAYBOOK.md
+      @design-ai/examples/component-banner.md
+
+      Spec a Banner component for our system. Persistent in-page strip
+      for system status. Variants: info / success / warning / error /
+      promo. Dismissible. Korean copy.
+
+Cursor ▸ I'll apply the component-spec-writer skill using the existing
+       Banner spec as reference, adapted to your codebase.
+
+       [generates a spec inline in chat]
+       [includes a tabular API, anatomy, states, tokens]
+
+You ▸  Now implement the spec as a React component in this file. Use
+       our existing token system (`var(--color-banner-bg-info)` etc).
+       Follow our patterns from src/components/Alert.tsx for the
+       dismiss button.
+
+Cursor ▸ [generates Banner.tsx implementation]
+```
+
+The two-step workflow — **spec first, then implement** — is the key Cursor pattern. Specs are knowledge artifacts; implementation is code.
+
+## Walkthrough 2: Audit existing component
+
+**Goal**: cursor reviews your current Button component against design-ai's spec.
+
+### Session
+
+```
+You ▸ Open src/components/Button.tsx side-by-side with
+      @design-ai/examples/component-button.md.
+
+      Audit my Button against the spec. Flag missing variants, missing
+      states, a11y gaps, and Korean considerations.
+
+Cursor ▸ Comparing your Button.tsx against component-button.md.
+
+       Findings:
+
+       [HIGH] Missing `loading` state. Spec section "States" requires
+       a loading variant with spinner + disabled events. Your
+       component has no loading prop.
+
+       [HIGH] Missing `asChild` support. Spec section "Composition
+       patterns" → asChild lets the Button render as a Link or other
+       slot. Your version is button-only.
+
+       [MEDIUM] Touch target. Spec requires ≥ 44pt for primary mobile;
+       your `size="sm"` is 32px tall. Acceptable for desktop secondary;
+       fail for mobile primary.
+
+       [LOW] Korean: no IME consideration. For inputs that lead to a
+       Button submit, IME composition can swallow Enter. Recommend
+       wrapping in Form's submit handler that respects compositionend.
+
+       [recommendations with file diffs]
+```
+
+This is `design-system-qa` skill applied per-component. Powerful for raising existing codebase quality to spec.
+
+## Walkthrough 3: Iterate on a Figma screenshot
+
+**Goal**: paste a Figma screenshot and get a critique with concrete fixes.
+
+### Session
+
+```
+You ▸ [pastes screenshot.png into chat]
+      @design-ai/agents/design-critic.md
+      @design-ai/agents/a11y-reviewer.md
+
+      Critique this hero section. KR fintech audience.
+
+Cursor ▸ Running design-critic + a11y-reviewer in parallel.
+
+       Top recommendation:
+       The headline carries 70% of the message but uses 24px Inter
+       Light. Korean target users won't get the warmth that the
+       Light weight implies in Latin. Bump to Pretendard 600
+       Semibold at 32px on mobile, 48px on desktop.
+
+       [CRITICAL]
+       - CTA contrast 3.4:1 (white text on
+         oklch(70% 0.16 240)) fails WCAG AA. Bump bg to
+         oklch(58% 0.18 240) to clear 4.5:1.
+
+       [HIGH]
+       - Sub-headline uses `당신의 ...` — too formal-distant.
+         Rewrite using `~해요`: "여러분의 송금을 더 쉽게 만들어요".
+       - Sale-30% badge near CTA competes for attention. Move
+         to upper-right corner of card or remove.
+
+       [Suggested rewrites]
+```
+
+## Walkthrough 4: Generate tokens from brand brief
+
+**Goal**: bootstrap a design token file from a brand brief, exported as both CSS and Tailwind config.
+
+### Session
+
+```
+You ▸ @design-ai/skills/color-palette/PLAYBOOK.md
+
+      Generate a full palette for a Korean fintech for freelancers.
+      Brand: trustworthy, calm, modern. Seed: oklch(56% 0.16 244).
+      Output: src/tokens/colors.css (CSS vars) + tailwind.config.ts
+      (extending colors). Include dark mode.
+
+Cursor ▸ [reads the playbook]
+       [generates both files in your project]
+
+You ▸  Now add semantic aliases (--color-primary-default, etc) per the
+       spec. And add a contrast matrix as a comment block at the top
+       of colors.css.
+
+Cursor ▸ [updates files]
+```
+
+## Walkthrough 5: Use Cursor's `Cmd+K` for in-place edits
+
+For tight iteration loops, Cursor's `Cmd+K` (inline edit) works with design-ai context if you set the rules globally.
+
+```
+[select a problematic JSX block]
+[press Cmd+K]
+"Make this match design-ai's component-button.md spec for the
+ 'destructive' variant. Use our color tokens."
+```
+
+Cursor reads the spec via the workspace context and rewrites in place.
+
+## Cursor-specific tips
+
+### MCP servers
+
+Cursor 0.40+ supports MCP. Add design-aware MCPs:
+
+```json
+// ~/.cursor/mcp.json
+{
+  "mcpServers": {
+    "figma": {
+      "command": "npx",
+      "args": ["-y", "figma-mcp"],
+      "env": { "FIGMA_TOKEN": "..." }
+    },
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "env": { "GITHUB_TOKEN": "..." }
+    }
+  }
+}
+```
+
+Then design-ai's Figma + GitHub-aware skills (`figma-token-sync`, `design-pr-review`) work with live data.
+
+### Composer mode
+
+For multi-file changes (e.g., refactoring 5 components to match a new spec), use Cursor Composer:
+
+```
+[Composer mode]
+"Apply the destructive variant from
+@design-ai/examples/component-button.md to all uses of
+DangerButton in src/. Update the component, the storybook,
+and any usage. Match our token system."
+```
+
+Composer reads the spec once, applies across files.
+
+### Per-project AGENTS.md fork
+
+For large projects, fork the design-ai AGENTS.md into your project:
+
+```bash
+cp ~/dev/design-ai/AGENTS.md ./AGENTS.md
+# Edit to add project-specific overrides + the design-ai paths.
+```
+
+Cursor reads project `AGENTS.md` (when present) AND `.cursorrules`.
+
+## Troubleshooting
+
+### Cursor doesn't pick up `.cursorrules`
+
+Restart Cursor. Or `Cmd+Shift+P → Developer: Reload Window`.
+
+### `@` doesn't autocomplete design-ai files
+
+Add the design-ai folder to your workspace (not just `.cursorrules`). Cursor's `@` indexes workspace folders only.
+
+### Korean conventions are inconsistent across the session
+
+Add an explicit reminder to `.cursorrules`:
+
+```
+For Korean content, ALWAYS:
+- Pretendard for typography
+- 해요체 (consumer) or 합쇼체 (formal) — never mix in one component
+- 명함 90×50mm not international 85×55
+```
+
+### Cursor uses GPT-4 instead of Claude
+
+design-ai is model-agnostic. Both work. For best output on long-form synthesis tasks, Claude Sonnet 4.6+ is slightly stronger; for code generation, GPT-4o + Claude both work. Switch via Cursor's model picker (Cmd+/ → Model).
+
+## Next
+
+- [`docs/CURSOR-INTEGRATION.md`](../CURSOR-INTEGRATION.md) — full setup reference
+- [`docs/integrations/codex-walkthrough.md`](codex-walkthrough.md) — Codex CLI variant
+- [`docs/integrations/aider-walkthrough.md`](aider-walkthrough.md) — Aider variant
+- [`docs/integrations/sdk-walkthrough.md`](sdk-walkthrough.md) — Anthropic / OpenAI SDK
+- [`docs/MCP-INTEGRATION.md`](../MCP-INTEGRATION.md) — MCP servers

package/docs/integrations/design-ai-mcp-server.md

@@ -0,0 +1,169 @@
+# design-ai MCP server
+
+Use this guide when you want Claude Code or Codex to call design-ai as an MCP server instead of asking the agent to read files manually.
+
+The server is local, stdio-based, and deterministic. It wraps existing `design-ai` CLI workflows such as route selection, prompt generation, corpus search, artifact checks, and Website Improvement MCP readiness checks.
+
+## What the server exposes
+
+| Tool | Purpose | Mutation risk |
+|---|---|---|
+| `design_ai_route` | Recommend the best design-ai route, skill, command, and knowledge files for a task brief. | Read-only |
+| `design_ai_prompt` | Generate a ready-to-use prompt from a brief. | Read-only by default; `withLearning` records local usage metadata |
+| `design_ai_pack` | Generate a prompt plus bounded context files. | Read-only by default; `withLearning` records local usage metadata |
+| `design_ai_search` | Search `knowledge/`, `examples/`, `skills/`, `docs/`, `agents/`, and `commands/`. | Read-only |
+| `design_ai_show` | Read a corpus file or line range. | Read-only |
+| `design_ai_examples` | Find worked examples by query or route. | Read-only |
+| `design_ai_check` | Check generated Markdown artifacts for grounding, accessibility, responsive notes, and unresolved markers. | Read-only |
+| `design_ai_site_mcp_check` | Validate Website Improvement MCP readiness from workspace JSON. | Read-only |
+| `design_ai_site_mcp_plan` | Generate a Website Improvement MCP action plan. | Read-only |
+| `design_ai_version` | Return CLI and corpus version metadata. | Read-only |
+
+## Start the server manually
+
+From a local clone:
+
+```bash
+cd /path/to/design-ai
+node cli/bin/design-ai-mcp.mjs
+```
+
+After package installation, use either entrypoint:
+
+```bash
+design-ai mcp
+design-ai-mcp
+```
+
+Do not run the server as a normal terminal command unless an MCP client is connected. It waits for newline-delimited JSON-RPC messages on stdin and writes MCP responses to stdout.
+
+## Connect Claude Code
+
+For a local-only server on the current machine:
+
+```bash
+claude mcp add --transport stdio design-ai -- design-ai mcp
+```
+
+If `design-ai` is not on `PATH`, point Claude Code at the local clone:
+
+```bash
+claude mcp add --transport stdio design-ai \
+  -- node /path/to/design-ai/cli/bin/design-ai-mcp.mjs
+```
+
+Then open Claude Code and run:
+
+```text
+/mcp
+```
+
+Confirm that `design-ai` is connected and exposes tools.
+
+Project-scoped Claude configuration can also live in `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "design-ai": {
+      "command": "design-ai",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+Claude Code asks for approval before using project-scoped `.mcp.json` servers.
+
+## Connect Codex
+
+Use the Codex CLI:
+
+```bash
+codex mcp add design-ai -- design-ai mcp
+```
+
+Or edit `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.design-ai]
+command = "design-ai"
+args = ["mcp"]
+startup_timeout_sec = 10
+tool_timeout_sec = 60
+```
+
+For a local clone without a global install:
+
+```toml
+[mcp_servers.design-ai]
+command = "node"
+args = ["/path/to/design-ai/cli/bin/design-ai-mcp.mjs"]
+cwd = "/path/to/design-ai"
+startup_timeout_sec = 10
+tool_timeout_sec = 60
+```
+
+In the Codex TUI, run:
+
+```text
+/mcp
+```
+
+Confirm that `design-ai` is active.
+
+## Recommended prompts
+
+Ask Claude or Codex to use the MCP server explicitly:
+
+```text
+Use the design-ai MCP server to route this task, then generate a prompt pack:
+Spec a dense Korean fintech AmountInput component with accessibility notes.
+```
+
+For Website Improvement work:
+
+```text
+Use design_ai_site_mcp_check on this Website Improvement workspace JSON.
+Then generate a design_ai_site_mcp_plan and summarize blocking MCP gaps.
+```
+
+## Safety boundaries
+
+- The server runs locally over stdio.
+- The default tools do not call external MCP servers.
+- Website Improvement MCP readiness tools inspect local workspace JSON only.
+- `design_ai_prompt` and `design_ai_pack` are read-only unless `withLearning` is set.
+- The server does not mutate target repositories.
+- Do not pass secrets in briefs, workspace JSON, or artifacts.
+
+## Verify locally
+
+Run the unit and subprocess smoke tests:
+
+```bash
+node --test cli/lib/mcp-server.test.mjs
+```
+
+Run a protocol smoke manually:
+
+```bash
+printf '%s\n' \
+  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25"}}' \
+  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
+  | node cli/bin/design-ai-mcp.mjs
+```
+
+The output must contain valid one-line JSON-RPC responses and a `tools` list.
+
+## References
+
+- [Model Context Protocol specification](https://modelcontextprotocol.io/specification/2025-11-25)
+- [Claude Code MCP documentation](https://code.claude.com/docs/en/mcp)
+- [Codex MCP documentation](https://developers.openai.com/codex/mcp)
+
+## Cross-reference
+
+- [`../MCP-INTEGRATION.md`](../MCP-INTEGRATION.md)
+- [`../CODEX-INTEGRATION.md`](../CODEX-INTEGRATION.md)
+- [`../USING.md`](../USING.md)

package/docs/integrations/figma-mcp.md

@@ -0,0 +1,149 @@
+# Figma MCP integration
+
+Use Figma MCP to bridge design-ai with real Figma files: read existing tokens/components, write generated tokens as Variables, set up Code Connect mappings.
+
+## Available tools (when MCP connected)
+
+| Tool | What it does |
+| --- | --- |
+| `mcp__Figma__get_metadata` | File structure — nodes, pages, components |
+| `mcp__Figma__get_design_context` | Selected node's design tokens, styles, components |
+| `mcp__Figma__get_variable_defs` | All Variables in the file |
+| `mcp__Figma__get_screenshot` | Render a frame as image |
+| `mcp__Figma__get_code_connect_map` | Existing Code Connect mappings |
+| `mcp__Figma__add_code_connect_map` | Add a new component mapping |
+| `mcp__Figma__create_design_system_rules` | Apply rule sets to file |
+
+## Workflow A: read tokens from Figma
+
+When a designer maintains tokens in Figma and you want to extract them.
+
+```
+You: Pull the latest tokens from this Figma file: <link>
+Agent:
+  1. mcp__Figma__get_variable_defs(file_key=...)
+  2. Transforms the result into design-ai's token format (W3C DTCG / Style Dictionary).
+  3. Saves to refs/figma/<file>-tokens.json (gitignored).
+  4. Shows summary: "Extracted 47 color, 12 spacing, 8 typography variables."
+```
+
+The output is then consumed by `tools/extractors/figma.py` (when added) or imported into Style Dictionary directly.
+
+## Workflow B: audit a Figma design
+
+When designs are in Figma and you want a design-ai review.
+
+```
+You: Audit this Figma frame: <link>
+Agent:
+  1. mcp__Figma__get_screenshot(file_key=..., node_id=...)
+     [image returned, agent inspects]
+  2. mcp__Figma__get_design_context(file_key=..., node_id=...)
+     [used components, applied tokens]
+  3. Apply skills/ux-audit/PLAYBOOK.md against the screenshot + tokens.
+  4. Output: severity-ranked findings.
+```
+
+The agent evaluates the design AND its token usage simultaneously.
+
+## Workflow C: spec a component from Figma
+
+User has a component in Figma but no spec.
+
+```
+You: Spec this component: <Figma link with node_id>
+Agent:
+  1. mcp__Figma__get_metadata(file_key=..., node_id=...)
+  2. Read variants from the component set.
+  3. Read tokens from the design context.
+  4. Apply skills/component-spec-writer/PLAYBOOK.md.
+  5. Output a spec markdown file matching examples/component-*.md format.
+```
+
+The Figma component is the source; the spec is the derived contract.
+
+## Workflow D: write tokens TO Figma
+
+When code is the source-of-truth and Figma needs updating.
+
+```
+You: Push our design-ai tokens to this Figma file: <link>
+Agent:
+  1. Read tokens/source.json from the project.
+  2. For each token, mcp__Figma__... (write Variable).
+
+  Note: as of mid-2025, Figma MCP's WRITE access for Variables is
+  limited. The Tokens Studio plugin is more capable for bidirectional
+  sync. For now, READ is the strong path.
+```
+
+For real two-way sync: use Tokens Studio (UI-based) AND Figma MCP (read-only verification). See [`docs/TOKEN-SYNC.md`](../TOKEN-SYNC.md).
+
+## Workflow E: Code Connect mapping via MCP
+
+Map a Figma component to its React code without leaving the agent.
+
+```
+You: Map our Figma Button to src/components/Button/Button.tsx
+Agent:
+  1. mcp__Figma__get_code_connect_map(file_key=...)
+     [check existing mappings]
+  2. Read the React component's TypeScript types.
+  3. Build a Code Connect manifest matching variants.
+  4. mcp__Figma__add_code_connect_map(file_key=..., mapping={...})
+  5. Confirm.
+```
+
+## Setup
+
+### Authentication
+
+Figma MCP requires:
+- A Figma account (free or paid).
+- The Figma desktop app open (some MCPs need active session).
+- An auth token with read scope (and write, for token-write workflows).
+
+```bash
+# Claude Code
+claude mcp add figma --command "npx" --args "@figma/mcp-server"
+
+# Codex CLI: add to ~/.codex/mcp.json
+```
+
+After setup, run `mcp__Figma__get_metadata` once to verify auth works.
+
+### File access
+
+Figma MCP reads files the authenticated user can access. For team files: ensure the auth user has been invited.
+
+For public Figma Community files: anyone can read with auth.
+
+## Common pitfalls
+
+| Pitfall | Fix |
+| --- | --- |
+| MCP can't find file | Verify `file_key` in URL: `figma.com/file/<file_key>/...` |
+| Variables not returned | File uses Styles (legacy), not Variables. Check Figma's Variables panel. |
+| Permission denied | Auth user needs file access. Re-auth or share the file. |
+| Rate limit | Figma API caps. Cache MCP responses; avoid polling. |
+
+## Privacy
+
+- Figma file URLs identify private design work. Don't commit them to public repos.
+- The auth token has access to all files the user can see — careful where it's deployed.
+- design-ai never logs or echoes the auth token (skills reference `mcp__Figma__*` tools, not the underlying credentials).
+
+## When Figma MCP is unavailable
+
+design-ai's `figma-token-sync` skill detects no MCP and falls back to:
+- Asking user to export tokens from Tokens Studio plugin manually.
+- Asking user to paste a screenshot for visual audits.
+- Skipping the Code Connect step (do it via Figma desktop directly).
+
+## Cross-reference
+
+- [`docs/MCP-INTEGRATION.md`](../MCP-INTEGRATION.md) — overview
+- [`docs/FIGMA-INTEGRATION.md`](../FIGMA-INTEGRATION.md) — broader Figma workflows (without MCP)
+- [`docs/TOKEN-SYNC.md`](../TOKEN-SYNC.md) — token sync strategy
+- [`skills/figma-token-sync/PLAYBOOK.md`](../../skills/figma-token-sync/PLAYBOOK.md) — the MCP-aware skill
+- `tools/figma-plugin/README.md` — alternative manual import path