prototype-to-figma-skill
Claude skill: Prototype → Figma. Analyzes a Claude Code prototype, maps components to your Figma design system via search + Code Connect, explodes each interaction flow into state-by-state frames, and annotates triggers, transitions, and edge cases, making prototypes reviewable by PMs, designers, and engineers without running code.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/alima-max--prototype-to-figma-skill)HTML
<a href="/listings/alima-max--prototype-to-figma-skill"><img src="/api/listings/alima-max--prototype-to-figma-skill/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Claude.ai (Team / Enterprise)
1. Download the latest zip from the [Releases](../../releases) page (or clone this repo and zip the root folder) 2. Go to **Settings → Customize → Skills → "+" → "+ Create skill"** 3. Upload the zip 4. Share with your org via the skill sharing feature
Claude Code
git clone https://github.com/alima-max/prototype-to-figma-skill.git ~/.claude/skills/prototype-to-figma
Other clients (Cursor, VS Code, Copilot CLI, etc.)
Add `SKILL.md` and `figma-patterns.md` to your client's skills or context directory. Refer to your client's documentation for the exact location.
Claude API
Upload via the `/v1/skills` endpoint. See [Skills API docs](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) for details.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 551 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- ---
- name: prototype-to-figma
- description: >
- Converts a working Claude Code prototype into a structured Figma design file — exploding each
- interaction flow into separate frames, using the target file's design system components, and
- annotating interaction details natively in Figma. Use this skill whenever the user asks to
- turn a prototype into Figma frames, generate design specs from a prototype, create a Figma
- handoff from code, explode a prototype into states, or make a prototype reviewable by
- cross-functional partners. Also trigger when the user mentions "prototype to Figma",
- "design review from prototype", "async feedback on prototype", "break prototype into flows",
- "Figma specs from code", or wants to make a working prototype legible to non-technical
- stakeholders. Even if the user just says "put this in Figma" or "make this reviewable" in the
- context of a prototype, use this skill.
- ---
- # Prototype → Figma
- This skill takes a working Claude Code prototype and produces a structured Figma file that
- cross-functional partners can review asynchronously. The output has two equal goals:
- 1. **True 1:1 visual parity** — layout, colors, spacing, typography, content, and icons match the
- *rendered* prototype exactly, because the base is produced by a **headless render → serialize**
- (Rule 0), not a hand-reconstruction. Runs entirely in the terminal — no visible browser or tab.
- 2. **A design-system-native, reviewable result** — captured elements are reconciled to DS component
- instances / bound variables / text styles wherever the DS is published to Figma (Rule 2), and
- every state transition is annotated on its node.
- **This skill works across all Figma MCP clients.** The output format adapts to what your client
- supports — see [Client Compatibility](#client-compatibility) below.
- ---
- ## Five non-negotiable rules
- ### Rule 0: Capture headlessly (render → serialize), never open a visible browser; then reconcile to the DS
- **True 1:1 requires *rendering* the code — but rendering does NOT require a *visible* browser.** Use
- a **headless** browser (Playwright) so the whole run stays in the terminal: no window, no tab. That
- is the point for the target user — designers working exclusively in code who must not be pulled out
- of the IDE.
- Three options; only one is right:
- - ❌ **Read source and hand-build (no render).** An LLM re-deriving a browser's layout/render engine
- element-by-element is lossy, incomplete, and buggy on any non-trivial page. It is **not 1:1** — it
- only looks faithful on small, static UIs, and it drifts badly on real ones (collapsed grids,
- missing elements, half-built SVGs). Do not pretend this is 1:1.
- - ❌ **Visible capture** — `open "<url>#figmacapture=…"`, the in-app preview, or the GUI Figma
- extension. Correct fidelity, but it pops windows/tabs and drags the designer out of the terminal
- (and the bare extension gives no DS instances).
- - ✅ **Headless capture.** A headless browser renders the running app in the background and
- serializes the DOM **1:1 straight to Figma** (data goes browser→Figma, never through the model —
- so it's fast and cheap). The model then adds the design-system layer. Terminal-native, 1:1,
- invisible.
- **"Headless" = a separate Chrome process launched with `--headless`: no window, no tab, nothing on
- screen.** It does NOT attach to the designer's open browser and does NOT require Chrome to be
- *open* — only *installed*. It spins up invisibly, renders the localhost page in memory, serializes
- to Figma, and exits. The designer never leaves the terminal and sees nothing happen in their browser.
- **The capture (headless, terminal-only):**
- 1. Ensure the dev server is running — start it in the background if needed. Determine the route
- URLs from the codebase.
- 2. Launch a headless browser from the terminal and run the `generate_figma_design` capture script
- (navigate to the LOCAL dev URL → strip CSP → inject `capture.js` → `window.figma.captureForDesign(
- { captureId, endpoint, selector:'body' })`). **Prefer the machine's already-installed Chrome**
- (`puppeteer-core`, or Playwright with `channel:'chrome'`, or raw CDP) so there's **no download and
- no MCP** — Chrome need only be *installed*, not open. **Only if no Chrome/Chromium is found**, fall
- back to a one-time bundled-Chromium download (`npx playwright install chromium` / full
- `puppeteer`). **Never** launch a *new visible instance*, never attach to the user's live browser,
- never use `open "<url>#figmacapture=…"` or the in-app preview — all of those put a window/tab on
- screen.
- 3. Poll `generate_figma_design` (fileKey + captureId) until `completed`. You get a fully-layered 1:1
- base (frames / text / vectors) with tokens bound (`bindVariables=true`).
- **Then reconcile to the DS + annotate (`use_figma`, Rule 2):** swap repeated captured elements for DS
- component instances, bind variables / text styles **where the DS is actually published to Figma**,
- and attach Dev Mode annotations + flow arrows. This is the cheap, surgical layer — it touches a
- handful of components, not the whole page.
- **Requirements / honesty:** needs (a) a **headless browser** — ideally the machine's installed
- Chrome driven headless (no download, no MCP required); a bundled Chromium download is the fallback —
- and (b) a runnable dev server. No Playwright *MCP* is required; a headless Chrome runtime is. If
- there's genuinely no browser at all, **say so and stop** — do not fall back to a visible tab, and do
- not hand-build from source and call it 1:1 (it won't be). If the design system isn't published to
- Figma as components/variables, reconciliation is limited to what exists — flag that DS gap, don't
- swap in a foreign library's components.
- ### Rule 1: Never create new Figma components
- **Do not** call `figma.createComponent()` or `figma.createComponentSet()`. These pollute the
- design system with components that don't belong there.
- When a prototype element has **no component of any kind** in the DS (see Rule 2 for the bar):
- build it from primitives (`figma.createFrame()`, `figma.createRectangle()`, `figma.createText()`),
- add a **DS Drift annotation** explaining what was missing, and list it in the Phase 6 summary.
- ### Rule 2: Always use a DS component / variable / style when one exists — the capture does NOT relax this
- The capture (Rule 0) gives parity; this rule makes the file design-system-native. **It applies as
- you reconcile each captured element** — the captured node tells you *where*, *how big*, and *how it
- looks*, but the structure should come from the DS wherever a match exists. Walk the captured frame
- and reconcile *every* element to the linked library:
- 1. **Components — always instance, never shadow.** If a captured element matches a DS component,
- **replace it with an instance** and override props (fill, text, size) to match
- the captured pixels. If the component exists but lacks the exact variant, still instance it +
- override, and add a DS Drift annotation. Only when there is **no** matching component does the
- element stay a primitive — flagged DS Drift. Repeated elements especially: 60 badges = 60
- instances, never 60 frames. A frame full of primitives that shadow real components is a failed
- run even if the pixels are perfect.
- 2. **Color variables — always bind.** Every fill/stroke whose value matches a DS color variable
- MUST bind that variable. Never leave a raw hex where a color variable exists.
- 3. **Number variables — always bind.** Every spacing, gap, padding, corner radius, border width,
- size, and font-size that matches a DS number/dimension variable MUST bind it. Never leave a
- raw number where a number variable exists.
- 4. **Text styles — always apply.** Body/label/heading text binds to the library text style, not
- raw `fontSize`/`fontName`.
- The rule in one line: **prefer the component / color variable / number variable / text style
- over any literal whenever a match exists.** Raw hex, ad-hoc numbers, and shadow-primitives are
- drift — not parity — even when they look right. Phase 2 discovers the components, variables, and
- styles; Phase 4 swaps and binds them onto the captured base.
- ### Rule 3: Never omit a prototype element
- Every visible element must appear in the Figma output — DS instance or primitive. Skipping
- elements because you couldn't find a DS match is the most common cause of incomplete outputs.
- ### Rule 4: Annotations must be attached to nodes, and must be flow-critical only
- **Annotations are what make this output useful for review.** A frame with no annotations is
- just a static image. But annotating every tap target creates noise that buries the actual flow.
- Annotate using `node.annotations = [...]` on the actual layer — this surfaces in Figma Dev Mode
- on the correct element. **Never create floating text boxes or separate annotation frames** as a
- substitute. If the native API fails, fall back to `figma-patterns.md` Section 11.
- Two categories only:
- - **Interaction** (blue) — state transitions, primary CTAs, grouped controls
- - **DS Drift** (orange) — missing DS component, missing variant, or unbound color/spacing
- **Annotate (Interaction):**
- - **Frame-level** — one annotation per frame: what state this is and what the primary action does / where it goes next
- - **State-advancing CTAs** — the action(s) that trigger a state change (e.g., Submit, Confirm, Create goal, Move to completed)
- - **Grouped controls** — annotate the container once, not each item (annotate the amount picker row, not each chip; annotate the story pill rail, not each pill)
- - **Non-obvious tap targets** — elements that open a new state but don't look like buttons (e.g., a goal card that opens a detail sheet)
- **Do not annotate:**
- - Close / cancel / dismiss buttons
- - Nav bar buttons and tab items
- - Secondary utility actions (settings, prototype controls)
- - Individual chips or pills within a grouped picker
- - Backdrops and overlays
- - Decorative elements
- **Target: 2–4 Interaction annotations per frame.** A reviewer should be able to read all annotations on a frame in under 30 seconds and understand the complete flow.
- Every element with a DS Drift note from Phase 2 must have a DS Drift annotation.
- ---
- ## Client Compatibility
- | Tier | Inspect | Write | Code Connect | Output |
- |---|---|---|---|---|
- | **Full** | ✅ | ✅ | ✅ | Figma file with DS components, native annotations, Code Connect links |
- | **Write** | ✅ or ❌ | ✅ | ❌ | Figma file with native annotations |
- | **Inspect-only** | ✅ | ❌ | ❌ | Prototype Spec Document (markdown) |
- | **None** | ❌ | ❌ | ❌ | Prototype Spec Document from code analysis alone |
- | Client | Inspect | Write | Code Connect |
- |---|---|---|---|
- | Claude Code / Desktop / Cursor / VS Code / Copilot CLI / Augment / Factory | ✅ | ✅ | ✅ |
- | Android Studio / Gemini CLI / Kiro / Amazon Q / Openhands | ✅ | ❌ | ❌ |
- | Replit | ❌ | ✅ | ❌ |
- ---
- ## Figma MCP tools
- **Inspect:** `get_design_context` (primary), `get_metadata` (structure overview),
- `search_design_system` (components + variables), `get_variable_defs` (exact token values),
- `get_screenshot` (only if user explicitly requests a visual preview).
- **Capture (primary path — Rule 0):** `generate_figma_design` driven by a **headless** browser —
- ideally the machine's **installed Chrome** run headless (`puppeteer-core` / Playwright
- `channel:'chrome'` / CDP; no download, no MCP), bundled Chromium only as a fallback — against the
- local dev server. Renders + serializes 1:1 to Figma with no visible window/tab. NEVER the
- `open`-a-tab flow or the in-app preview (visible), and never attach to the user's open browser.
- **Write:** `use_figma` (reconcile captured nodes to DS instances + variables, annotate, assemble
- the flow), `whoami`, `create_new_file`.
- **Code Connect:** `get_code_connect_map`, `get_code_connect_suggestions`,
- `get_context_for_code_connect`, `send_code_connect_mappings`.
- ---
- ## The workflow
- ### Phase 0: Resolve file and detect capabilities
- **File:** Extract `fileKey` from a user-provided URL (`figma.com/design/:fileKey/...`). If no
- URL is given, call `whoami` then `create_new_file` — never block on a missing URL.
- **Capabilities:** Attempt `get_metadata` to confirm Inspect tools. Check tool list for
- `use_figma` (Write) and `get_code_connect_map` (Code Connect). Announce what you have.
- **Route:** Write tools available → Phases 1–6. Write tools unavailable → Phases 1–3, then
- [Prototype Spec Document](#prototype-spec-document--inspect-only-output).
- ---
- ### Phase 1a: Analyze the prototype
- Read all prototype source files before touching Figma.
- **Component inventory** — for every UI component, record: name, props/variants in use, visual
- structure (what's inside it), and whether it is interactive. This list is the completeness
- checklist for Phase 4.
- **Interaction flows** — for each flow, map: trigger → state change → before/after states →
- branching paths (success / error / edge cases). Include state count.
- **Layout structure** — note what's fixed vs. scrollable, what persists across states (nav,
- header), and the viewport dimensions. For the phone/device frame: if the prototype wraps screens
- in a `.phone`, `.device-frame`, or similar shell, **extract only the content dimensions** and
- use those for Figma frame size — do not recreate the shell as a wrapper frame in Figma.
- **Source read (for inventory + structure, NOT for pixel values)** — read the CSS modules,
- Tailwind config, and inline styles to understand each element's structure, variants, and which
- are interactive. Do **not** treat source CSS values as the pixel source of truth: responsive/
- computed CSS (grid `fr`, `clamp()`, `min/max`, `vw`, transforms, theme scopes) resolves to
- formulas, not pixels. The pixel source of truth is the **computed measurement** from the running
- app (Rule 0 / Phase 4). Use source reading only to know *what* to measure and match to the DS.
- ---
- ### Phase 1b: Present scope, get selection, confirm
- **Skip if the prototype has ≤ 2 flows.** Proceed directly to Phase 2 with all flows.
- For 3+ flows, present a categorized flow list with state counts, ask "which flows and how much
- detail (happy path / all states)?", and wait for a reply before proceeding. Confirm the
- interpretation explicitly before starting Phase 2.
- ---
- ### Phase 2: Discovery pass — map to the design system before drawing anything
- Do a full discovery pass against the linked library **first**, then map every element. Do not
- start building until this table exists. The default is *instance*, not primitive (Rule 2).
- **2a. Enumerate the library once, up front.** Before searching per component, pull the catalog so
- you know what exists:
- - **Components:** `search_design_system(fileKey, includeComponents=true)` with broad queries, plus
- category sweeps ("input", "navigation", "feedback", "card", "badge", "avatar", "table") to
- surface the full set — not just the names your code happens to use.
- - **Variables:** `search_design_system(..., includeVariables=true)` and `get_variable_defs` for
- color, spacing, radius, and **border-width** tokens. Record the keys.
- - **Text styles:** capture the library's typography styles (name → font, size, weight, line
- height) from `search_design_system` / `get_variable_defs`. These are what body copy, labels,
- and headings must bind to — not hardcoded hex + ad-hoc `fontSize`.
- **2b. Match each inventory element** (try in order before declaring "no match"):
- 1. `search_design_system(fileKey, query="ComponentName", includeComponents=true)`
- 2. Alternate names: Alert/Banner/Toast/Notification, Dropdown/Select/Menu, Tag/Chip/Badge,
- Nav/Sidebar/TabBar, TextField/Input, TextArea/Multiline, Avatar/UserPill, etc.
- 3. Visual category: "input", "navigation", "feedback", "card"
- 4. Parent component coverage (e.g., "Card" covers `Card.Header`)
- **For found components:** call `get_context_for_code_connect` to get exact variant prop names
- before setting properties in Phase 4.
- **When a component exists but the exact variant does not:** do **not** drop to a primitive.
- Instantiate the component and override the differing property per-instance (fill, text, size),
- then add a DS Drift annotation for the missing variant. Only elements with *no* matching
- component at all become primitives.
- **Build the mapping table — every row needs a build approach and drift note:**
- | Code component | DS match | Key | Build approach | Drift note |
- |---|---|---|---|---|
- | `<Button variant="primary">` | Button | abc123 | Import + setProperties | ✅ Clean match |
- | `<Badge tone="success">` | Badge | ghi789 | Import + per-instance fill override | ⚠️ No `success` variant — override fill |
- | `<CustomCard>` | — | — | Primitives | ⚠️ No DS match — searched: Card, Panel, Tile |
- | `<DataTable sortable>` | Table | def456 | Import + setProperties | ⚠️ No `sortable` variant in Figma |
- Also record, for each element, which **text style** and **color/spacing/radius/border-width
- variables** it should bind to in Phase 4. Any row with ⚠️ must get a DS Drift annotation in
- Phase 4. A row that says "Primitives" is only valid if 2b found nothing — not because a variant
- was missing.
- **2c. Resolve themed / runtime-remapped CSS-variable tokens — never trust the raw `var()`.**
- When colors, spacing, or radii come from CSS custom properties (`var(--token-…)`) that a runtime
- theme provider remaps — e.g. a `ThemeScope` / `data-theme` / class-based provider that changes
- what `--token-color-purple-100` resolves to per brand or per light/dark scheme — the **raw CSS
- value is not the rendered value**. Reading the stylesheet alone yields the variable *name* or its
- top-of-file default, not what the user actually sees in that themed context. This is a silent
- parity killer: the most common symptom is a themed surface (a dark footer, an inverted hero)
- rendering **blank/white** in Figma because its fill was never resolved and set.
- Resolve the *rendered* value, then bind it — three steps, in order:
- 1. **Get the true value from the running app, not the source.** Read the element's computed style
- in the browser (`getComputedStyle` / an inspect tool → `background-color`, `color`, `gap`,
- `border-radius`, …) so the theme remap collapses to a concrete `rgb()` / `px`. If no running
- app is available, resolve the variable chain manually through the active theme's mode, not the
- `:root` default.
- 2. **Match it to a native Figma variable.** Search the linked library (`search_design_system`
- with `includeVariables=true`, `get_variable_defs`) for a variable whose resolved value equals
- it under the corresponding mode/theme. If found, **bind the variable** (Phase 4 §3.2) so the
- node stays theme-aware — this is always preferred over a literal.
- 3. **If no Figma variable matches, apply the resolved literal as a primitive value AND add a DS
- Drift annotation.** The token exists in code but has no design-system variable counterpart —
- a real gap for the design team to close. Record it as a ⚠️ row in the mapping table.
- Never leave a themed token unresolved (raw `var()` name, `:root` default, or an unset fill). "I
- read it from the CSS" is not sufficient when a theme scope sits between the token and the pixel.
- ---
- ### Phase 3: Plan the page structure
- ```
- Page: "[Feature Name] — Prototype Flows"
- Section: "Flow 1: [Flow Name]"
- Frame: "1.1 — [State description]" ← left-to-right within a flow
- Frame: "1.2 — [State description]"
- Frame: "1.3a — Success"
- Frame: "1.3b — Error" ← branches stacked vertically
- Section: "Flow 2: [Flow Name]"
- ...
- ```
- Frame size: match the CSS-measured viewport (e.g., 390×844 mobile, 1440×900 desktop). For
- scrollable states, set frame height to full content height — never clip at viewport height. Add
- a fold marker line at the viewport height. ~200px gaps between frames, ~400px between sections.
- ---
- ### Phase 4: Headless-capture the pixels, then reconcile to the DS
- **Step 1 — Capture headlessly (Rule 0).** Make sure the dev server is running (start it in the
- background if needed) and resolve the route URLs from the codebase. For each route/state, call
- `generate_figma_design` (fileKey) to get a captureId + the capture script, then run the **headless
- Playwright** variant of that script against the LOCAL dev URL — navigate, strip CSP, inject
- `capture.js`, `window.figma.captureForDesign({...})`. **No `open`, no visible tab, no in-app
- preview.** Poll `generate_figma_design(fileKey, captureId)` until `completed`. Result: a fully
- layered 1:1 base per state, sent browser→Figma directly.
- **Step 2 — Reconcile to the DS (Rule 2).** Walk each captured frame and, for every element with a
- Phase 2 match, swap it for a DS component instance (override to match the captured pixels), bind
- color + number variables and text styles **where the DS is published to Figma**. Elements with no
- match stay as the captured node, flagged DS Drift. This is the cheap surgical layer — a handful of
- components, not the whole page. If the DS isn't in Figma at all, keep the capture as-is and flag it.
- **Step 3 — Assemble + annotate (Phase 5).** Arrange the state frames into the flow, add arrows, and
- attach Dev Mode annotations.
- > **If there's no headless browser or no dev server:** stop and tell the user what's missing. Do
- > NOT fall back to a visible tab, and do NOT hand-build from source and label it 1:1.
- **Placement:** scan the target page with `get_metadata` first. If matching frames/sections exist
- for this feature, insert beside them. If not, create a named section:
- `[Prototype] <feature name>`. Never place frames at an arbitrary far-Y without reporting
- coordinates and a deep-link in the Phase 6 summary.
- **DS component instances** — see `figma-patterns.md` Section 3 for `importComponentByKeyAsync`
- + `setProperties`.
- **Primitives** — see `figma-patterns.md` Section 4. Use the **computed measured values** (Rule 0)
- for all dimensions, radii, and colors.
- **Fixed-size square/circle containers (avatars, number badges, icon chips):** set **both** axes
- to fixed sizing — never let auto-layout hug. A hugging container collapses to the width of its
- glyph, so a 32×32 avatar renders 32px tall but ~10px wide. Use `primaryAxisSizingMode = 'FIXED'`
- and `counterAxisSizingMode = 'FIXED'` after `resize(size, size)`, or skip auto-layout and center
- the child manually. See `figma-patterns.md` Section 4.1.
- **DS variable + text-style binding** — for every fill, radius, spacing, and **border-width**
- where a variable key was found in Phase 2, bind it instead of hardcoding. Bind body/label/heading
- text to the library **text style** instead of setting raw `fontSize`/`fontName`. The variables API
- lives under `figma.variables.*` (NOT the `figma` global), and `setBoundVariableForPaint` takes a
- *paint* and returns a new one you must reassign:
- ```javascript
- // Color fill → variable. setBoundVariableForPaint returns a NEW paint — reassign node.fills.
- const colorVar = await figma.variables.importVariableByKeyAsync(colorVarKey);
- let fills = node.fills;
- if (fills && fills !== figma.mixed && fills.length && fills[0].type === 'SOLID') {
- fills = [...fills]; // copy — assigning into the live array is a no-op
- fills[0] = figma.variables.setBoundVariableForPaint(fills[0], 'color', colorVar);
- node.fills = fills; // reassign — required
- }
- // Scalar fields (radius / border-width / spacing) → node.setBoundVariable
- const radiusVar = await figma.variables.importVariableByKeyAsync(radiusVarKey);
- node.setBoundVariable('cornerRadius', radiusVar); // fallback: pass radiusVar.id
- const borderVar = await figma.variables.importVariableByKeyAsync(borderWidthVarKey);
- node.setBoundVariable('strokeWeight', borderVar); // not a raw strokeWeight
- // Typography → library text style (styles use figma.importStyleByKeyAsync, NOT the variables API)
- const textStyle = await figma.importStyleByKeyAsync(textStyleKey);
- await textNode.setTextStyleIdAsync(textStyle.id); // font/size/weight/lineHeight; fill stays separate
- ```
- > ⚠ `figma.importVariableByKeyAsync(...)` (no `.variables`) and `node.setBoundVariableForPaint('fills', 0, ...)`
- > THROW in the Figma MCP runtime — use the forms above. Cache imports (one per key), then bind.
- **Page and surface backgrounds** must bind to the surface/wash color variable too — never a raw
- page-background hex. Fall back to raw CSS values only when Phase 2 found no DS variable or text
- style for that role (and note it as drift).
- **Annotations — attach to nodes during build, not after**
- Set up two annotation categories once at the start of your first `use_figma` call:
- ```javascript
- let interactionCat = null, dsDriftCat = null;
- try {
- const existing = await figma.annotations.getAnnotationCategoriesAsync();
- interactionCat = existing.find(c => c.label === 'Interaction')
- ?? await figma.annotations.addAnnotationCategoryAsync({ label: 'Interaction', color: 'blue' });
- dsDriftCat = existing.find(c => c.label === 'DS Drift')
- ?? await figma.annotations.addAnnotationCategoryAsync({ label: 'DS Drift', color: 'orange' });
- } catch(e) { /* native API unavailable — use layer name fallback below */ }
- ```
- As you build each node, **annotate it immediately** — do not defer annotation to a separate
- pass. Keeping the node reference in scope is the only reliable way to attach to the right layer:
- ```javascript
- // Interaction annotation — on the node itself, right after creating it
- const ctaButton = figma.createFrame(); // ...build it...
- ctaButton.name = 'CTA: Submit';
- ctaButton.annotations = [{
- label: 'Tap → submits form; on 200 navigates to success screen; on 4xx shows inline error',
- ...(interactionCat ? { categoryId: interactionCat.id } : {})
- }];
- // DS Drift annotation — on any primitive or mismatched DS component
- const customCard = figma.createFrame(); // ...build it...
- customCard.name = 'Card: Goal (primitive)';
- customCard.annotations = [{
- label: 'DS Drift: no Card/Goal component found in library (searched: Card, Panel, Tile). DS gap for design team.',
- ...(dsDriftCat ? { categoryId: dsDriftCat.id } : {})
- }];
- // Fallback if native API failed: encode in layer name
- if (!interactionCat) ctaButton.name += ' [Interaction: tap → submit form]';
- if (!dsDriftCat) customCard.name += ' [DS Drift: no Card/Goal in DS]';
- ```
- **Annotation checklist per frame:**
- - [ ] Frame itself has one annotation: current state + what the primary action does / where it leads
- - [ ] Each state-advancing CTA has an annotation (trigger → result)
- - [ ] Grouped controls (pickers, pill rails, option lists) have one annotation for the group, not per item
- - [ ] Every primitive or mismatched DS component has a DS Drift annotation
- Completeness check: before moving to the next frame, verify every row from the Phase 2 mapping
- table that belongs in this frame is present in the layer tree.
- ---
- ### Phase 5: Add a flow overview frame
- One frame at the top of the page:
- - Feature name, flow list, frame count
- - Annotation legend: blue = Interaction, orange = DS Drift (filterable in Dev Mode)
- - DS gaps: list all primitives and mismatched components for the design team
- - Open questions: flag any ambiguous prototype behavior
- - Scope note if flows were omitted (offer to re-run skill to add them)
- ---
- ### Phase 6: Verify and present
- **6a. Completeness check** — via `get_metadata` on the output, verify:
- - Every row in the Phase 2 mapping table has a named layer in the correct frame
- - **Every element with a DS match is an instance, not a primitive** — including repeated
- elements (badges, nav, inputs, textareas, avatars). Primitives appear only for rows Phase 2
- confirmed had no match; each such primitive carries a DS Drift annotation.
- - Frame dimensions match the CSS-measured viewport
- - No new master components were created in local assets
- - DS variable bindings are present on color fills, border-radii, and **border-widths**; text
- binds to **library text styles**; page/surface backgrounds bind to a surface variable
- - **Square/circle containers render square** — width equals height (no hug collapse)
- - **Inline SVGs survived** — if the app has any `<svg>` (logo, icons, decorative blobs) the output
- must contain VECTOR nodes for them. A frame with **0 vectors** means every inline SVG was dropped
- (wrong/placeholder logo, empty footer, blob-less card art) — go back and add them via
- `createNodeFromSvg`.
- Fix anything missing with a follow-up `use_figma` call before presenting.
- **6b. Code Connect** *(optional)* — `get_code_connect_suggestions` → review → `send_code_connect_mappings`.
- **6c. Present to user:**
- - Figma file URL (always) + deep-link to the section node if not at the canvas origin
- - Flow count, frame count
- - DS instances vs. primitives used
- - Full list of DS gaps (primitives) for the design team
- - Any deviations from CSS measurements and why
- - Steps skipped due to capability limits
- ---
- ## Prototype Spec Document — Inspect-only output
- When Write tools are unavailable, produce a structured markdown document using the template in
- `figma-patterns.md` Section 12.
- ---
- ## Important principles
- **Instance first, primitive last.** The value of this skill is not rebuilding by hand. If the DS
- has a component — even without the exact variant — use it with an override. Bind typography,
- color, spacing, radius, and border-width to DS styles and variables. A pixel-accurate frame made
- of primitives that shadow real components is still a failed run.
- **Render, then serialize — headlessly.** True 1:1 comes from a headless browser rendering the code
- and serializing the result to Figma, not from an LLM re-deriving layout from source (lossy on any
- real page) and not from a visible capture (pulls the designer out of the terminal). Headless =
- same fidelity, invisible, terminal-native. The model's job is the DS + annotation layer on top, not
- reproducing the pixels by hand.
- **Annotate on the node, not the canvas.** `node.annotations = [...]` is what surfaces in Dev
- Mode. Floating text boxes and separate annotation frames are noise, not annotations.
- **Name everything.** "Frame 47" is useless. "2.3a — Save success with toast" tells a reviewer
- exactly where they are.
- **Annotate flows, not tap targets.** The goal is for a reviewer to read all annotations on a
- frame in under 30 seconds and understand the complete flow. Annotate the state transition, not
- the mechanism — one annotation on the amount picker row beats four identical annotations on each
- chip inside it.
- **Be explicit about DS gaps.** List every primitive in the summary so the design team knows what
- components are missing from the DS. This turns unmatched elements from a silent failure into
- actionable signal.
- ---
- ## Reference: Figma Plugin API patterns
- See `figma-patterns.md` for Plugin API patterns — frame creation, component importing,
- primitive helpers, `addNoDsMatchBadge`, auto-layout, text nodes, annotation setup, and the
- Prototype Spec Document template. Read this before your first `use_figma` call.
- *(Write-tier clients only.)*
README.md · README · 115 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # Prototype → Figma
- A Claude skill that converts working Claude Code prototypes into structured Figma design files — exploding each interaction flow into separate frames, using your design system components, and annotating interaction details natively in Figma.
- ## Why this exists
- When you build a prototype in Claude Code, getting async feedback from cross-functional partners (PMs, designers, engineers) is hard. They can't easily walk through a live prototype on their own. This skill bridges that gap by translating your prototype into a Figma file that reviewers can browse, comment on, and understand without running anything.
- ## What it produces
- - **One frame per interaction state** — every meaningful step in a user flow gets its own frame
- - **Design system components** — uses real DS components from your Figma file's linked libraries; elements with no DS match are built from primitives and flagged with a "No DS match" badge
- - **Native Figma annotations** — Dev Mode annotations with filterable categories (Interaction, Navigation, Validation, Error Handling, etc.) explaining triggers, transitions, conditions, and edge cases
- - **Flow arrows** — visual connectors showing the path a user takes through states
- - **Overview frame** — table of contents with a legend and open questions for reviewers
- - **Code Connect mappings** — optionally links Figma components back to your codebase
- ## Requirements
- - **Figma MCP tools** — this skill uses `use_figma`, `search_design_system`, `get_design_context`, `get_metadata`, `get_screenshot`, `get_code_connect_map`, `get_context_for_code_connect`, `get_code_connect_suggestions`, `send_code_connect_mappings`, `add_code_connect_map`, `whoami`, and `create_new_file`
- - **A working prototype** — built in Claude Code, typically using your team's actual component library
- - **A target Figma file** — optional; if you don't provide one, the skill creates a new file automatically
- ## Installation
- ### Claude.ai (Team / Enterprise)
- 1. Download the latest zip from the [Releases](../../releases) page (or clone this repo and zip the root folder)
- 2. Go to **Settings → Customize → Skills → "+" → "+ Create skill"**
- 3. Upload the zip
- 4. Share with your org via the skill sharing feature
- ### Claude Code
- ```bash
- git clone https://github.com/alima-max/prototype-to-figma-skill.git ~/.claude/skills/prototype-to-figma
- ```
- ### Other clients (Cursor, VS Code, Copilot CLI, etc.)
- Add `SKILL.md` and `figma-patterns.md` to your client's skills or context directory. Refer to your client's documentation for the exact location.
- ### Claude API
- Upload via the `/v1/skills` endpoint. See [Skills API docs](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) for details.
- ## Usage
- Once installed, just ask Claude naturally — no Figma URL required:
- - *"Take this prototype and put it in Figma so the team can review it"*
- - *"Explode this prototype into Figma frames for async feedback"*
- - *"Create Figma specs from my prototype for design review"*
- - *"Make this prototype reviewable by the design team"*
- If you want the output in a specific existing Figma file, include the URL:
- - *"Put this in Figma: figma.com/design/abc123/..."*
- Otherwise, Claude will create a new Figma file automatically and share the link when done.
- ## How it works
- 1. **Resolves the target file** — uses the file URL you provide, or creates a new Figma file automatically via `whoami` + `create_new_file`
- 2. **Analyzes the prototype** — reads the source code to inventory components, map interaction flows, and identify all UI states
- 3. **Maps to the design system** — searches the target Figma file's linked libraries for matching DS components; unmatched elements are built from primitives and flagged with a "No DS match" badge
- 4. **Plans the page structure** — organizes frames by flow, with branching paths for success/error states
- 5. **Builds in Figma** — creates frames, imports and configures DS component instances; never calls `createComponent()` or skips elements
- 6. **Annotates interactions** — adds native Figma annotations with filterable categories and a legend
- 7. **Verifies and presents** — screenshots the output, optionally creates Code Connect mappings, and shares the file URL with a summary
- ## Updating
- When a new version is released, you'll need to update your installation manually. No re-authentication required — it's just replacing files.
- ### Claude.ai (Team / Enterprise)
- 1. Download the latest zip from the [Releases](../../releases) page
- 2. Go to **Settings → Customize → Skills**, find "Prototype → Figma", and re-upload the new zip
- ### Claude Code
- ```bash
- cd ~/.claude/skills/prototype-to-figma
- git pull
- ```
- ### Other clients
- Replace `SKILL.md` and `figma-patterns.md` with the latest versions from this repo.
- To see what changed, check the [commit history](../../commits/main) or [releases](../../releases).
- ## Compatibility
- This skill works across all Figma MCP clients, but the output varies based on what tools your client supports:
- | Client | Builds in Figma | Code Connect |
- |---|---|---|
- | Claude Code, Claude Desktop, Cursor, VS Code, Copilot CLI, Augment Code, Factory, Firebender, Codex | ✅ | ✅ |
- | Android Studio, Gemini CLI, Kiro, Amazon Q, Openhands | ❌ (produces Prototype Spec Document instead) | ❌ |
- | Replit | ✅ | ❌ |
- See `SKILL.md` for full details on what each tier produces.
- ## Customization
- This skill was designed for teams whose prototypes use their actual shared component library. If your setup is different, you may want to fork and adjust:
- - **Component matching logic** — if your code and Figma use very different naming conventions
- - **Frame sizes** — defaults to 1440×900 (desktop) or 390×844 (mobile)
- - **Primitive fallback patterns** — `figma-patterns.md` contains helpers for Button, Input, Card, and Banner; add your own for other component types
- - **Flow granularity** — the skill groups micro-interactions into single annotated frames by default; you might want more or fewer frames per flow
- ## Related
- - **[`figma-make-to-spec`](https://github.com/alima-max/figma-make-to-spec)** — a sibling skill
- for turning a Figma Make prototype into a review-ready spec *inside* Figma (native-agent
- oriented). Reuses this skill's portable method; lives in its own repo.
- ## License
- MIT — see [LICENSE](LICENSE).
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.