Skip to content
Back to search

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/alima-max--prototype-to-figma-skill/badge.svg)](/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

i

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)

  1. ---
  2. name: prototype-to-figma
  3. description: >
  4. Converts a working Claude Code prototype into a structured Figma design file — exploding each
  5. interaction flow into separate frames, using the target file's design system components, and
  6. annotating interaction details natively in Figma. Use this skill whenever the user asks to
  7. turn a prototype into Figma frames, generate design specs from a prototype, create a Figma
  8. handoff from code, explode a prototype into states, or make a prototype reviewable by
  9. cross-functional partners. Also trigger when the user mentions "prototype to Figma",
  10. "design review from prototype", "async feedback on prototype", "break prototype into flows",
  11. "Figma specs from code", or wants to make a working prototype legible to non-technical
  12. stakeholders. Even if the user just says "put this in Figma" or "make this reviewable" in the
  13. context of a prototype, use this skill.
  14. ---
  15. # Prototype → Figma
  16. This skill takes a working Claude Code prototype and produces a structured Figma file that
  17. cross-functional partners can review asynchronously. The output has two equal goals:
  18. 1. **True 1:1 visual parity** — layout, colors, spacing, typography, content, and icons match the
  19. *rendered* prototype exactly, because the base is produced by a **headless render → serialize**
  20. (Rule 0), not a hand-reconstruction. Runs entirely in the terminal — no visible browser or tab.
  21. 2. **A design-system-native, reviewable result** — captured elements are reconciled to DS component
  22. instances / bound variables / text styles wherever the DS is published to Figma (Rule 2), and
  23. every state transition is annotated on its node.
  24. **This skill works across all Figma MCP clients.** The output format adapts to what your client
  25. supports — see [Client Compatibility](#client-compatibility) below.
  26. ---
  27. ## Five non-negotiable rules
  28. ### Rule 0: Capture headlessly (render → serialize), never open a visible browser; then reconcile to the DS
  29. **True 1:1 requires *rendering* the code — but rendering does NOT require a *visible* browser.** Use
  30. a **headless** browser (Playwright) so the whole run stays in the terminal: no window, no tab. That
  31. is the point for the target user — designers working exclusively in code who must not be pulled out
  32. of the IDE.
  33. Three options; only one is right:
  34. - ❌ **Read source and hand-build (no render).** An LLM re-deriving a browser's layout/render engine
  35. element-by-element is lossy, incomplete, and buggy on any non-trivial page. It is **not 1:1** — it
  36. only looks faithful on small, static UIs, and it drifts badly on real ones (collapsed grids,
  37. missing elements, half-built SVGs). Do not pretend this is 1:1.
  38. - ❌ **Visible capture** — `open "<url>#figmacapture=…"`, the in-app preview, or the GUI Figma
  39. extension. Correct fidelity, but it pops windows/tabs and drags the designer out of the terminal
  40. (and the bare extension gives no DS instances).
  41. - ✅ **Headless capture.** A headless browser renders the running app in the background and
  42. serializes the DOM **1:1 straight to Figma** (data goes browser→Figma, never through the model —
  43. so it's fast and cheap). The model then adds the design-system layer. Terminal-native, 1:1,
  44. invisible.
  45. **"Headless" = a separate Chrome process launched with `--headless`: no window, no tab, nothing on
  46. screen.** It does NOT attach to the designer's open browser and does NOT require Chrome to be
  47. *open* — only *installed*. It spins up invisibly, renders the localhost page in memory, serializes
  48. to Figma, and exits. The designer never leaves the terminal and sees nothing happen in their browser.
  49. **The capture (headless, terminal-only):**
  50. 1. Ensure the dev server is running — start it in the background if needed. Determine the route
  51. URLs from the codebase.
  52. 2. Launch a headless browser from the terminal and run the `generate_figma_design` capture script
  53. (navigate to the LOCAL dev URL → strip CSP → inject `capture.js` → `window.figma.captureForDesign(
  54. { captureId, endpoint, selector:'body' })`). **Prefer the machine's already-installed Chrome**
  55. (`puppeteer-core`, or Playwright with `channel:'chrome'`, or raw CDP) so there's **no download and
  56. no MCP** — Chrome need only be *installed*, not open. **Only if no Chrome/Chromium is found**, fall
  57. back to a one-time bundled-Chromium download (`npx playwright install chromium` / full
  58. `puppeteer`). **Never** launch a *new visible instance*, never attach to the user's live browser,
  59. never use `open "<url>#figmacapture=…"` or the in-app preview — all of those put a window/tab on
  60. screen.
  61. 3. Poll `generate_figma_design` (fileKey + captureId) until `completed`. You get a fully-layered 1:1
  62. base (frames / text / vectors) with tokens bound (`bindVariables=true`).
  63. **Then reconcile to the DS + annotate (`use_figma`, Rule 2):** swap repeated captured elements for DS
  64. component instances, bind variables / text styles **where the DS is actually published to Figma**,
  65. and attach Dev Mode annotations + flow arrows. This is the cheap, surgical layer — it touches a
  66. handful of components, not the whole page.
  67. **Requirements / honesty:** needs (a) a **headless browser** — ideally the machine's installed
  68. Chrome driven headless (no download, no MCP required); a bundled Chromium download is the fallback —
  69. and (b) a runnable dev server. No Playwright *MCP* is required; a headless Chrome runtime is. If
  70. there's genuinely no browser at all, **say so and stop** — do not fall back to a visible tab, and do
  71. not hand-build from source and call it 1:1 (it won't be). If the design system isn't published to
  72. Figma as components/variables, reconciliation is limited to what exists — flag that DS gap, don't
  73. swap in a foreign library's components.
  74. ### Rule 1: Never create new Figma components
  75. **Do not** call `figma.createComponent()` or `figma.createComponentSet()`. These pollute the
  76. design system with components that don't belong there.
  77. When a prototype element has **no component of any kind** in the DS (see Rule 2 for the bar):
  78. build it from primitives (`figma.createFrame()`, `figma.createRectangle()`, `figma.createText()`),
  79. add a **DS Drift annotation** explaining what was missing, and list it in the Phase 6 summary.
  80. ### Rule 2: Always use a DS component / variable / style when one exists — the capture does NOT relax this
  81. The capture (Rule 0) gives parity; this rule makes the file design-system-native. **It applies as
  82. you reconcile each captured element** — the captured node tells you *where*, *how big*, and *how it
  83. looks*, but the structure should come from the DS wherever a match exists. Walk the captured frame
  84. and reconcile *every* element to the linked library:
  85. 1. **Components — always instance, never shadow.** If a captured element matches a DS component,
  86. **replace it with an instance** and override props (fill, text, size) to match
  87. the captured pixels. If the component exists but lacks the exact variant, still instance it +
  88. override, and add a DS Drift annotation. Only when there is **no** matching component does the
  89. element stay a primitive — flagged DS Drift. Repeated elements especially: 60 badges = 60
  90. instances, never 60 frames. A frame full of primitives that shadow real components is a failed
  91. run even if the pixels are perfect.
  92. 2. **Color variables — always bind.** Every fill/stroke whose value matches a DS color variable
  93. MUST bind that variable. Never leave a raw hex where a color variable exists.
  94. 3. **Number variables — always bind.** Every spacing, gap, padding, corner radius, border width,
  95. size, and font-size that matches a DS number/dimension variable MUST bind it. Never leave a
  96. raw number where a number variable exists.
  97. 4. **Text styles — always apply.** Body/label/heading text binds to the library text style, not
  98. raw `fontSize`/`fontName`.
  99. The rule in one line: **prefer the component / color variable / number variable / text style
  100. over any literal whenever a match exists.** Raw hex, ad-hoc numbers, and shadow-primitives are
  101. drift — not parity — even when they look right. Phase 2 discovers the components, variables, and
  102. styles; Phase 4 swaps and binds them onto the captured base.
  103. ### Rule 3: Never omit a prototype element
  104. Every visible element must appear in the Figma output — DS instance or primitive. Skipping
  105. elements because you couldn't find a DS match is the most common cause of incomplete outputs.
  106. ### Rule 4: Annotations must be attached to nodes, and must be flow-critical only
  107. **Annotations are what make this output useful for review.** A frame with no annotations is
  108. just a static image. But annotating every tap target creates noise that buries the actual flow.
  109. Annotate using `node.annotations = [...]` on the actual layer — this surfaces in Figma Dev Mode
  110. on the correct element. **Never create floating text boxes or separate annotation frames** as a
  111. substitute. If the native API fails, fall back to `figma-patterns.md` Section 11.
  112. Two categories only:
  113. - **Interaction** (blue) — state transitions, primary CTAs, grouped controls
  114. - **DS Drift** (orange) — missing DS component, missing variant, or unbound color/spacing
  115. **Annotate (Interaction):**
  116. - **Frame-level** — one annotation per frame: what state this is and what the primary action does / where it goes next
  117. - **State-advancing CTAs** — the action(s) that trigger a state change (e.g., Submit, Confirm, Create goal, Move to completed)
  118. - **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)
  119. - **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)
  120. **Do not annotate:**
  121. - Close / cancel / dismiss buttons
  122. - Nav bar buttons and tab items
  123. - Secondary utility actions (settings, prototype controls)
  124. - Individual chips or pills within a grouped picker
  125. - Backdrops and overlays
  126. - Decorative elements
  127. **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.
  128. Every element with a DS Drift note from Phase 2 must have a DS Drift annotation.
  129. ---
  130. ## Client Compatibility
  131. | Tier | Inspect | Write | Code Connect | Output |
  132. |---|---|---|---|---|
  133. | **Full** | ✅ | ✅ | ✅ | Figma file with DS components, native annotations, Code Connect links |
  134. | **Write** | ✅ or ❌ | ✅ | ❌ | Figma file with native annotations |
  135. | **Inspect-only** | ✅ | ❌ | ❌ | Prototype Spec Document (markdown) |
  136. | **None** | ❌ | ❌ | ❌ | Prototype Spec Document from code analysis alone |
  137. | Client | Inspect | Write | Code Connect |
  138. |---|---|---|---|
  139. | Claude Code / Desktop / Cursor / VS Code / Copilot CLI / Augment / Factory | ✅ | ✅ | ✅ |
  140. | Android Studio / Gemini CLI / Kiro / Amazon Q / Openhands | ✅ | ❌ | ❌ |
  141. | Replit | ❌ | ✅ | ❌ |
  142. ---
  143. ## Figma MCP tools
  144. **Inspect:** `get_design_context` (primary), `get_metadata` (structure overview),
  145. `search_design_system` (components + variables), `get_variable_defs` (exact token values),
  146. `get_screenshot` (only if user explicitly requests a visual preview).
  147. **Capture (primary path — Rule 0):** `generate_figma_design` driven by a **headless** browser —
  148. ideally the machine's **installed Chrome** run headless (`puppeteer-core` / Playwright
  149. `channel:'chrome'` / CDP; no download, no MCP), bundled Chromium only as a fallback — against the
  150. local dev server. Renders + serializes 1:1 to Figma with no visible window/tab. NEVER the
  151. `open`-a-tab flow or the in-app preview (visible), and never attach to the user's open browser.
  152. **Write:** `use_figma` (reconcile captured nodes to DS instances + variables, annotate, assemble
  153. the flow), `whoami`, `create_new_file`.
  154. **Code Connect:** `get_code_connect_map`, `get_code_connect_suggestions`,
  155. `get_context_for_code_connect`, `send_code_connect_mappings`.
  156. ---
  157. ## The workflow
  158. ### Phase 0: Resolve file and detect capabilities
  159. **File:** Extract `fileKey` from a user-provided URL (`figma.com/design/:fileKey/...`). If no
  160. URL is given, call `whoami` then `create_new_file` — never block on a missing URL.
  161. **Capabilities:** Attempt `get_metadata` to confirm Inspect tools. Check tool list for
  162. `use_figma` (Write) and `get_code_connect_map` (Code Connect). Announce what you have.
  163. **Route:** Write tools available → Phases 1–6. Write tools unavailable → Phases 1–3, then
  164. [Prototype Spec Document](#prototype-spec-document--inspect-only-output).
  165. ---
  166. ### Phase 1a: Analyze the prototype
  167. Read all prototype source files before touching Figma.
  168. **Component inventory** — for every UI component, record: name, props/variants in use, visual
  169. structure (what's inside it), and whether it is interactive. This list is the completeness
  170. checklist for Phase 4.
  171. **Interaction flows** — for each flow, map: trigger → state change → before/after states →
  172. branching paths (success / error / edge cases). Include state count.
  173. **Layout structure** — note what's fixed vs. scrollable, what persists across states (nav,
  174. header), and the viewport dimensions. For the phone/device frame: if the prototype wraps screens
  175. in a `.phone`, `.device-frame`, or similar shell, **extract only the content dimensions** and
  176. use those for Figma frame size — do not recreate the shell as a wrapper frame in Figma.
  177. **Source read (for inventory + structure, NOT for pixel values)** — read the CSS modules,
  178. Tailwind config, and inline styles to understand each element's structure, variants, and which
  179. are interactive. Do **not** treat source CSS values as the pixel source of truth: responsive/
  180. computed CSS (grid `fr`, `clamp()`, `min/max`, `vw`, transforms, theme scopes) resolves to
  181. formulas, not pixels. The pixel source of truth is the **computed measurement** from the running
  182. app (Rule 0 / Phase 4). Use source reading only to know *what* to measure and match to the DS.
  183. ---
  184. ### Phase 1b: Present scope, get selection, confirm
  185. **Skip if the prototype has ≤ 2 flows.** Proceed directly to Phase 2 with all flows.
  186. For 3+ flows, present a categorized flow list with state counts, ask "which flows and how much
  187. detail (happy path / all states)?", and wait for a reply before proceeding. Confirm the
  188. interpretation explicitly before starting Phase 2.
  189. ---
  190. ### Phase 2: Discovery pass — map to the design system before drawing anything
  191. Do a full discovery pass against the linked library **first**, then map every element. Do not
  192. start building until this table exists. The default is *instance*, not primitive (Rule 2).
  193. **2a. Enumerate the library once, up front.** Before searching per component, pull the catalog so
  194. you know what exists:
  195. - **Components:** `search_design_system(fileKey, includeComponents=true)` with broad queries, plus
  196. category sweeps ("input", "navigation", "feedback", "card", "badge", "avatar", "table") to
  197. surface the full set — not just the names your code happens to use.
  198. - **Variables:** `search_design_system(..., includeVariables=true)` and `get_variable_defs` for
  199. color, spacing, radius, and **border-width** tokens. Record the keys.
  200. - **Text styles:** capture the library's typography styles (name → font, size, weight, line
  201. height) from `search_design_system` / `get_variable_defs`. These are what body copy, labels,
  202. and headings must bind to — not hardcoded hex + ad-hoc `fontSize`.
  203. **2b. Match each inventory element** (try in order before declaring "no match"):
  204. 1. `search_design_system(fileKey, query="ComponentName", includeComponents=true)`
  205. 2. Alternate names: Alert/Banner/Toast/Notification, Dropdown/Select/Menu, Tag/Chip/Badge,
  206. Nav/Sidebar/TabBar, TextField/Input, TextArea/Multiline, Avatar/UserPill, etc.
  207. 3. Visual category: "input", "navigation", "feedback", "card"
  208. 4. Parent component coverage (e.g., "Card" covers `Card.Header`)
  209. **For found components:** call `get_context_for_code_connect` to get exact variant prop names
  210. before setting properties in Phase 4.
  211. **When a component exists but the exact variant does not:** do **not** drop to a primitive.
  212. Instantiate the component and override the differing property per-instance (fill, text, size),
  213. then add a DS Drift annotation for the missing variant. Only elements with *no* matching
  214. component at all become primitives.
  215. **Build the mapping table — every row needs a build approach and drift note:**
  216. | Code component | DS match | Key | Build approach | Drift note |
  217. |---|---|---|---|---|
  218. | `<Button variant="primary">` | Button | abc123 | Import + setProperties | ✅ Clean match |
  219. | `<Badge tone="success">` | Badge | ghi789 | Import + per-instance fill override | ⚠️ No `success` variant — override fill |
  220. | `<CustomCard>` | — | — | Primitives | ⚠️ No DS match — searched: Card, Panel, Tile |
  221. | `<DataTable sortable>` | Table | def456 | Import + setProperties | ⚠️ No `sortable` variant in Figma |
  222. Also record, for each element, which **text style** and **color/spacing/radius/border-width
  223. variables** it should bind to in Phase 4. Any row with ⚠️ must get a DS Drift annotation in
  224. Phase 4. A row that says "Primitives" is only valid if 2b found nothing — not because a variant
  225. was missing.
  226. **2c. Resolve themed / runtime-remapped CSS-variable tokens — never trust the raw `var()`.**
  227. When colors, spacing, or radii come from CSS custom properties (`var(--token-…)`) that a runtime
  228. theme provider remaps — e.g. a `ThemeScope` / `data-theme` / class-based provider that changes
  229. what `--token-color-purple-100` resolves to per brand or per light/dark scheme — the **raw CSS
  230. value is not the rendered value**. Reading the stylesheet alone yields the variable *name* or its
  231. top-of-file default, not what the user actually sees in that themed context. This is a silent
  232. parity killer: the most common symptom is a themed surface (a dark footer, an inverted hero)
  233. rendering **blank/white** in Figma because its fill was never resolved and set.
  234. Resolve the *rendered* value, then bind it — three steps, in order:
  235. 1. **Get the true value from the running app, not the source.** Read the element's computed style
  236. in the browser (`getComputedStyle` / an inspect tool → `background-color`, `color`, `gap`,
  237. `border-radius`, …) so the theme remap collapses to a concrete `rgb()` / `px`. If no running
  238. app is available, resolve the variable chain manually through the active theme's mode, not the
  239. `:root` default.
  240. 2. **Match it to a native Figma variable.** Search the linked library (`search_design_system`
  241. with `includeVariables=true`, `get_variable_defs`) for a variable whose resolved value equals
  242. it under the corresponding mode/theme. If found, **bind the variable** (Phase 4 §3.2) so the
  243. node stays theme-aware — this is always preferred over a literal.
  244. 3. **If no Figma variable matches, apply the resolved literal as a primitive value AND add a DS
  245. Drift annotation.** The token exists in code but has no design-system variable counterpart —
  246. a real gap for the design team to close. Record it as a ⚠️ row in the mapping table.
  247. Never leave a themed token unresolved (raw `var()` name, `:root` default, or an unset fill). "I
  248. read it from the CSS" is not sufficient when a theme scope sits between the token and the pixel.
  249. ---
  250. ### Phase 3: Plan the page structure
  251. ```
  252. Page: "[Feature Name] — Prototype Flows"
  253. Section: "Flow 1: [Flow Name]"
  254. Frame: "1.1 — [State description]" ← left-to-right within a flow
  255. Frame: "1.2 — [State description]"
  256. Frame: "1.3a — Success"
  257. Frame: "1.3b — Error" ← branches stacked vertically
  258. Section: "Flow 2: [Flow Name]"
  259. ...
  260. ```
  261. Frame size: match the CSS-measured viewport (e.g., 390×844 mobile, 1440×900 desktop). For
  262. scrollable states, set frame height to full content height — never clip at viewport height. Add
  263. a fold marker line at the viewport height. ~200px gaps between frames, ~400px between sections.
  264. ---
  265. ### Phase 4: Headless-capture the pixels, then reconcile to the DS
  266. **Step 1 — Capture headlessly (Rule 0).** Make sure the dev server is running (start it in the
  267. background if needed) and resolve the route URLs from the codebase. For each route/state, call
  268. `generate_figma_design` (fileKey) to get a captureId + the capture script, then run the **headless
  269. Playwright** variant of that script against the LOCAL dev URL — navigate, strip CSP, inject
  270. `capture.js`, `window.figma.captureForDesign({...})`. **No `open`, no visible tab, no in-app
  271. preview.** Poll `generate_figma_design(fileKey, captureId)` until `completed`. Result: a fully
  272. layered 1:1 base per state, sent browser→Figma directly.
  273. **Step 2 — Reconcile to the DS (Rule 2).** Walk each captured frame and, for every element with a
  274. Phase 2 match, swap it for a DS component instance (override to match the captured pixels), bind
  275. color + number variables and text styles **where the DS is published to Figma**. Elements with no
  276. match stay as the captured node, flagged DS Drift. This is the cheap surgical layer — a handful of
  277. components, not the whole page. If the DS isn't in Figma at all, keep the capture as-is and flag it.
  278. **Step 3 — Assemble + annotate (Phase 5).** Arrange the state frames into the flow, add arrows, and
  279. attach Dev Mode annotations.
  280. > **If there's no headless browser or no dev server:** stop and tell the user what's missing. Do
  281. > NOT fall back to a visible tab, and do NOT hand-build from source and label it 1:1.
  282. **Placement:** scan the target page with `get_metadata` first. If matching frames/sections exist
  283. for this feature, insert beside them. If not, create a named section:
  284. `[Prototype] <feature name>`. Never place frames at an arbitrary far-Y without reporting
  285. coordinates and a deep-link in the Phase 6 summary.
  286. **DS component instances** — see `figma-patterns.md` Section 3 for `importComponentByKeyAsync`
  287. + `setProperties`.
  288. **Primitives** — see `figma-patterns.md` Section 4. Use the **computed measured values** (Rule 0)
  289. for all dimensions, radii, and colors.
  290. **Fixed-size square/circle containers (avatars, number badges, icon chips):** set **both** axes
  291. to fixed sizing — never let auto-layout hug. A hugging container collapses to the width of its
  292. glyph, so a 32×32 avatar renders 32px tall but ~10px wide. Use `primaryAxisSizingMode = 'FIXED'`
  293. and `counterAxisSizingMode = 'FIXED'` after `resize(size, size)`, or skip auto-layout and center
  294. the child manually. See `figma-patterns.md` Section 4.1.
  295. **DS variable + text-style binding** — for every fill, radius, spacing, and **border-width**
  296. where a variable key was found in Phase 2, bind it instead of hardcoding. Bind body/label/heading
  297. text to the library **text style** instead of setting raw `fontSize`/`fontName`. The variables API
  298. lives under `figma.variables.*` (NOT the `figma` global), and `setBoundVariableForPaint` takes a
  299. *paint* and returns a new one you must reassign:
  300. ```javascript
  301. // Color fill → variable. setBoundVariableForPaint returns a NEW paint — reassign node.fills.
  302. const colorVar = await figma.variables.importVariableByKeyAsync(colorVarKey);
  303. let fills = node.fills;
  304. if (fills && fills !== figma.mixed && fills.length && fills[0].type === 'SOLID') {
  305. fills = [...fills]; // copy — assigning into the live array is a no-op
  306. fills[0] = figma.variables.setBoundVariableForPaint(fills[0], 'color', colorVar);
  307. node.fills = fills; // reassign — required
  308. }
  309. // Scalar fields (radius / border-width / spacing) → node.setBoundVariable
  310. const radiusVar = await figma.variables.importVariableByKeyAsync(radiusVarKey);
  311. node.setBoundVariable('cornerRadius', radiusVar); // fallback: pass radiusVar.id
  312. const borderVar = await figma.variables.importVariableByKeyAsync(borderWidthVarKey);
  313. node.setBoundVariable('strokeWeight', borderVar); // not a raw strokeWeight
  314. // Typography → library text style (styles use figma.importStyleByKeyAsync, NOT the variables API)
  315. const textStyle = await figma.importStyleByKeyAsync(textStyleKey);
  316. await textNode.setTextStyleIdAsync(textStyle.id); // font/size/weight/lineHeight; fill stays separate
  317. ```
  318. > ⚠ `figma.importVariableByKeyAsync(...)` (no `.variables`) and `node.setBoundVariableForPaint('fills', 0, ...)`
  319. > THROW in the Figma MCP runtime — use the forms above. Cache imports (one per key), then bind.
  320. **Page and surface backgrounds** must bind to the surface/wash color variable too — never a raw
  321. page-background hex. Fall back to raw CSS values only when Phase 2 found no DS variable or text
  322. style for that role (and note it as drift).
  323. **Annotations — attach to nodes during build, not after**
  324. Set up two annotation categories once at the start of your first `use_figma` call:
  325. ```javascript
  326. let interactionCat = null, dsDriftCat = null;
  327. try {
  328. const existing = await figma.annotations.getAnnotationCategoriesAsync();
  329. interactionCat = existing.find(c => c.label === 'Interaction')
  330. ?? await figma.annotations.addAnnotationCategoryAsync({ label: 'Interaction', color: 'blue' });
  331. dsDriftCat = existing.find(c => c.label === 'DS Drift')
  332. ?? await figma.annotations.addAnnotationCategoryAsync({ label: 'DS Drift', color: 'orange' });
  333. } catch(e) { /* native API unavailable — use layer name fallback below */ }
  334. ```
  335. As you build each node, **annotate it immediately** — do not defer annotation to a separate
  336. pass. Keeping the node reference in scope is the only reliable way to attach to the right layer:
  337. ```javascript
  338. // Interaction annotation — on the node itself, right after creating it
  339. const ctaButton = figma.createFrame(); // ...build it...
  340. ctaButton.name = 'CTA: Submit';
  341. ctaButton.annotations = [{
  342. label: 'Tap → submits form; on 200 navigates to success screen; on 4xx shows inline error',
  343. ...(interactionCat ? { categoryId: interactionCat.id } : {})
  344. }];
  345. // DS Drift annotation — on any primitive or mismatched DS component
  346. const customCard = figma.createFrame(); // ...build it...
  347. customCard.name = 'Card: Goal (primitive)';
  348. customCard.annotations = [{
  349. label: 'DS Drift: no Card/Goal component found in library (searched: Card, Panel, Tile). DS gap for design team.',
  350. ...(dsDriftCat ? { categoryId: dsDriftCat.id } : {})
  351. }];
  352. // Fallback if native API failed: encode in layer name
  353. if (!interactionCat) ctaButton.name += ' [Interaction: tap → submit form]';
  354. if (!dsDriftCat) customCard.name += ' [DS Drift: no Card/Goal in DS]';
  355. ```
  356. **Annotation checklist per frame:**
  357. - [ ] Frame itself has one annotation: current state + what the primary action does / where it leads
  358. - [ ] Each state-advancing CTA has an annotation (trigger → result)
  359. - [ ] Grouped controls (pickers, pill rails, option lists) have one annotation for the group, not per item
  360. - [ ] Every primitive or mismatched DS component has a DS Drift annotation
  361. Completeness check: before moving to the next frame, verify every row from the Phase 2 mapping
  362. table that belongs in this frame is present in the layer tree.
  363. ---
  364. ### Phase 5: Add a flow overview frame
  365. One frame at the top of the page:
  366. - Feature name, flow list, frame count
  367. - Annotation legend: blue = Interaction, orange = DS Drift (filterable in Dev Mode)
  368. - DS gaps: list all primitives and mismatched components for the design team
  369. - Open questions: flag any ambiguous prototype behavior
  370. - Scope note if flows were omitted (offer to re-run skill to add them)
  371. ---
  372. ### Phase 6: Verify and present
  373. **6a. Completeness check** — via `get_metadata` on the output, verify:
  374. - Every row in the Phase 2 mapping table has a named layer in the correct frame
  375. - **Every element with a DS match is an instance, not a primitive** — including repeated
  376. elements (badges, nav, inputs, textareas, avatars). Primitives appear only for rows Phase 2
  377. confirmed had no match; each such primitive carries a DS Drift annotation.
  378. - Frame dimensions match the CSS-measured viewport
  379. - No new master components were created in local assets
  380. - DS variable bindings are present on color fills, border-radii, and **border-widths**; text
  381. binds to **library text styles**; page/surface backgrounds bind to a surface variable
  382. - **Square/circle containers render square** — width equals height (no hug collapse)
  383. - **Inline SVGs survived** — if the app has any `<svg>` (logo, icons, decorative blobs) the output
  384. must contain VECTOR nodes for them. A frame with **0 vectors** means every inline SVG was dropped
  385. (wrong/placeholder logo, empty footer, blob-less card art) — go back and add them via
  386. `createNodeFromSvg`.
  387. Fix anything missing with a follow-up `use_figma` call before presenting.
  388. **6b. Code Connect** *(optional)* — `get_code_connect_suggestions` → review → `send_code_connect_mappings`.
  389. **6c. Present to user:**
  390. - Figma file URL (always) + deep-link to the section node if not at the canvas origin
  391. - Flow count, frame count
  392. - DS instances vs. primitives used
  393. - Full list of DS gaps (primitives) for the design team
  394. - Any deviations from CSS measurements and why
  395. - Steps skipped due to capability limits
  396. ---
  397. ## Prototype Spec Document — Inspect-only output
  398. When Write tools are unavailable, produce a structured markdown document using the template in
  399. `figma-patterns.md` Section 12.
  400. ---
  401. ## Important principles
  402. **Instance first, primitive last.** The value of this skill is not rebuilding by hand. If the DS
  403. has a component — even without the exact variant — use it with an override. Bind typography,
  404. color, spacing, radius, and border-width to DS styles and variables. A pixel-accurate frame made
  405. of primitives that shadow real components is still a failed run.
  406. **Render, then serialize — headlessly.** True 1:1 comes from a headless browser rendering the code
  407. and serializing the result to Figma, not from an LLM re-deriving layout from source (lossy on any
  408. real page) and not from a visible capture (pulls the designer out of the terminal). Headless =
  409. same fidelity, invisible, terminal-native. The model's job is the DS + annotation layer on top, not
  410. reproducing the pixels by hand.
  411. **Annotate on the node, not the canvas.** `node.annotations = [...]` is what surfaces in Dev
  412. Mode. Floating text boxes and separate annotation frames are noise, not annotations.
  413. **Name everything.** "Frame 47" is useless. "2.3a — Save success with toast" tells a reviewer
  414. exactly where they are.
  415. **Annotate flows, not tap targets.** The goal is for a reviewer to read all annotations on a
  416. frame in under 30 seconds and understand the complete flow. Annotate the state transition, not
  417. the mechanism — one annotation on the amount picker row beats four identical annotations on each
  418. chip inside it.
  419. **Be explicit about DS gaps.** List every primitive in the summary so the design team knows what
  420. components are missing from the DS. This turns unmatched elements from a silent failure into
  421. actionable signal.
  422. ---
  423. ## Reference: Figma Plugin API patterns
  424. See `figma-patterns.md` for Plugin API patterns — frame creation, component importing,
  425. primitive helpers, `addNoDsMatchBadge`, auto-layout, text nodes, annotation setup, and the
  426. Prototype Spec Document template. Read this before your first `use_figma` call.
  427. *(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)

  1. # Prototype → Figma
  2. 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.
  3. ## Why this exists
  4. 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.
  5. ## What it produces
  6. - **One frame per interaction state** — every meaningful step in a user flow gets its own frame
  7. - **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
  8. - **Native Figma annotations** — Dev Mode annotations with filterable categories (Interaction, Navigation, Validation, Error Handling, etc.) explaining triggers, transitions, conditions, and edge cases
  9. - **Flow arrows** — visual connectors showing the path a user takes through states
  10. - **Overview frame** — table of contents with a legend and open questions for reviewers
  11. - **Code Connect mappings** — optionally links Figma components back to your codebase
  12. ## Requirements
  13. - **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`
  14. - **A working prototype** — built in Claude Code, typically using your team's actual component library
  15. - **A target Figma file** — optional; if you don't provide one, the skill creates a new file automatically
  16. ## Installation
  17. ### Claude.ai (Team / Enterprise)
  18. 1. Download the latest zip from the [Releases](../../releases) page (or clone this repo and zip the root folder)
  19. 2. Go to **Settings → Customize → Skills → "+" → "+ Create skill"**
  20. 3. Upload the zip
  21. 4. Share with your org via the skill sharing feature
  22. ### Claude Code
  23. ```bash
  24. git clone https://github.com/alima-max/prototype-to-figma-skill.git ~/.claude/skills/prototype-to-figma
  25. ```
  26. ### Other clients (Cursor, VS Code, Copilot CLI, etc.)
  27. 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.
  28. ### Claude API
  29. Upload via the `/v1/skills` endpoint. See [Skills API docs](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) for details.
  30. ## Usage
  31. Once installed, just ask Claude naturally — no Figma URL required:
  32. - *"Take this prototype and put it in Figma so the team can review it"*
  33. - *"Explode this prototype into Figma frames for async feedback"*
  34. - *"Create Figma specs from my prototype for design review"*
  35. - *"Make this prototype reviewable by the design team"*
  36. If you want the output in a specific existing Figma file, include the URL:
  37. - *"Put this in Figma: figma.com/design/abc123/..."*
  38. Otherwise, Claude will create a new Figma file automatically and share the link when done.
  39. ## How it works
  40. 1. **Resolves the target file** — uses the file URL you provide, or creates a new Figma file automatically via `whoami` + `create_new_file`
  41. 2. **Analyzes the prototype** — reads the source code to inventory components, map interaction flows, and identify all UI states
  42. 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
  43. 4. **Plans the page structure** — organizes frames by flow, with branching paths for success/error states
  44. 5. **Builds in Figma** — creates frames, imports and configures DS component instances; never calls `createComponent()` or skips elements
  45. 6. **Annotates interactions** — adds native Figma annotations with filterable categories and a legend
  46. 7. **Verifies and presents** — screenshots the output, optionally creates Code Connect mappings, and shares the file URL with a summary
  47. ## Updating
  48. When a new version is released, you'll need to update your installation manually. No re-authentication required — it's just replacing files.
  49. ### Claude.ai (Team / Enterprise)
  50. 1. Download the latest zip from the [Releases](../../releases) page
  51. 2. Go to **Settings → Customize → Skills**, find "Prototype → Figma", and re-upload the new zip
  52. ### Claude Code
  53. ```bash
  54. cd ~/.claude/skills/prototype-to-figma
  55. git pull
  56. ```
  57. ### Other clients
  58. Replace `SKILL.md` and `figma-patterns.md` with the latest versions from this repo.
  59. To see what changed, check the [commit history](../../commits/main) or [releases](../../releases).
  60. ## Compatibility
  61. This skill works across all Figma MCP clients, but the output varies based on what tools your client supports:
  62. | Client | Builds in Figma | Code Connect |
  63. |---|---|---|
  64. | Claude Code, Claude Desktop, Cursor, VS Code, Copilot CLI, Augment Code, Factory, Firebender, Codex | ✅ | ✅ |
  65. | Android Studio, Gemini CLI, Kiro, Amazon Q, Openhands | ❌ (produces Prototype Spec Document instead) | ❌ |
  66. | Replit | ✅ | ❌ |
  67. See `SKILL.md` for full details on what each tier produces.
  68. ## Customization
  69. 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:
  70. - **Component matching logic** — if your code and Figma use very different naming conventions
  71. - **Frame sizes** — defaults to 1440×900 (desktop) or 390×844 (mobile)
  72. - **Primitive fallback patterns** — `figma-patterns.md` contains helpers for Button, Input, Card, and Banner; add your own for other component types
  73. - **Flow granularity** — the skill groups micro-interactions into single annotated frames by default; you might want more or fewer frames per flow
  74. ## Related
  75. - **[`figma-make-to-spec`](https://github.com/alima-max/figma-make-to-spec)** — a sibling skill
  76. for turning a Figma Make prototype into a review-ready spec *inside* Figma (native-agent
  77. oriented). Reuses this skill's portable method; lives in its own repo.
  78. ## License
  79. MIT — see [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.