Skip to content

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

Step 2 — Convert to Figma Variables JSON

Figma Variables can be imported via: - The official Tokens Studio plugin (free tier) — 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):

{
  "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 — ramp construction rules - knowledge/a11y/contrast.md — contrast requirements - 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.

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.

Map the Figma main component to the production component. Once mapped:

// 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.

The component spec should include a Code Connect section pointing both directions:

## 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.
  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