figma-to-spec

name	figma-to-spec
description	Use when the user wants a bounded Figma design analyzed before coding, needs `design_analysis.md` or `page_spec.md` generated from traceable Figma evidence, or wants a design-to-code workflow that stops at structured spec instead of implementation.

Figma to Spec

Use this skill to turn a Figma design into a stable intermediate specification layer.

This skill is for analysis and documentation, not implementation. It should stop after producing structured specs that humans can review and downstream skills can consume.

Every output from this skill must preserve canonical Figma provenance and enough evidence for later review. A spec that cannot be traced back to concrete frame input is not implementation-ready.

What This Skill Produces

Default outputs live under docs/design/<scope_slug>/ unless the repository already has a better-established design/spec folder.

Primary outputs:

• design_analysis.md
• page_spec.md

Optional outputs:

• asset_manifest.md
• open_questions.md

Use the stable output contract in output-contract.md. Use the Markdown templates in templates.md. Use inference rules in analysis-signals.md. Use copyable prompts in usage-examples.md.

Quick Start

If the user is not specific yet, start with a bounded analysis request like this:

Use figma-to-spec to analyze this bounded Figma frame set.
Figma URLs:
- https://www.figma.com/design/FILEKEY/Example?node-id=123-456
Scope: this single frame only.
Mode: overview.
Target stack: Vue3 + Tailwind + shadcn/ui + Vite.
Generate a concise `design_analysis.md` and stop at spec.

For more examples, see usage-examples.md.

When to Use

Use this skill when the user wants to:

• inspect a Figma design before writing code
• extract token candidates from a Figma frame or section
• map a page into primitives, patterns, and sections
• create a reviewable design spec from Figma MCP output
• prepare a handoff artifact for a later theme or implementation step

Do not use this skill when the user already wants final code edits in the project. In that case, use this skill first, then hand off to an implementation-oriented workflow.

Required Inputs

Always confirm these inputs before doing detailed extraction:

• Figma source: one or more canonical Figma URLs, or a current selection that can be resolved into fileKey and nodeId
• Scope: single frame, single section, single page, responsive pair, state set, or explicitly approved bounded multi-frame / multi-section scope
• Mode: overview, tokens, section-spec, or full-spec
• Target stack if known: for example Vue3 + Tailwind + shadcn/ui + Vite

If the input is only "current selection", resolve it into canonical provenance before producing any output:

• original user-provided Figma URL or equivalent selection reference
• fileKey
• nodeId or node list

If you cannot preserve canonical provenance, stop and ask for a traceable source instead of emitting a spec that looks authoritative.

Default to a single frame or single section if scope is ambiguous, but never discard the original frame URL(s) from the final metadata. Do not silently analyze an entire Figma file unless the user explicitly asks for it.

Scope Strategy

This skill can analyze several related frames or sections when one static frame is not enough.

In practice, multi-scope analysis is often more accurate for:

• desktop + tablet + mobile variants of the same page or section
• default + hover + active + open + error + loading states of the same component or module
• 2-5 sibling sections from the same page
• a bounded multi-step flow from the same user journey

Preferred bounded scope patterns:

Responsive Set

Use a matched set such as:

• Homepage / Desktop
• Homepage / Tablet
• Homepage / Mobile

State Set

Use a matched set such as:

• Filter Bar / Default
• Filter Bar / Expanded
• Filter Bar / Active Filter

Section Pack

Use a bounded sibling set such as:

• Hero
• Feature Grid
• Pricing
• FAQ

Flow Pack

Use a bounded flow such as:

• Sign In
• Verification
• Success State

Rules for multi-scope extraction:

• all selected nodes should belong to the same page, component family, or user flow
• prefer 2-6 related nodes instead of one isolated frame when accuracy clearly improves
• do not mix unrelated marketing pages, dashboard pages, and experiments in one pass
• if the user gives a broad file-level request, narrow it to a bounded set before analysis
• if the set becomes too broad, split it into multiple specs instead of forcing one document

Do not use section-spec for a workspace-sized composite frame unless the scope is explicitly narrowed to a bounded internal module or related module state set. If the selected node behaves like a whole page or composite workspace, either:

• split it into a bounded section pack, or
• upgrade the task to full-spec

Modes

overview

Use for the first pass on a design.

Output:

• page/frame summary
• section inventory
• primitive inventory
• top-level token candidates
• notable risks and open questions

This mode works well for a bounded multi-frame set when you want a more reliable first pass.

tokens

Use when the user only wants the visual system extracted.

Output:

• color roles
• typography scale
• spacing rhythm
• radius, border, shadow, motion candidates
• token normalization notes

This mode is usually more reliable when it compares several related frames or sections rather than a single isolated frame.

section-spec

Use when the user wants one section or module analyzed in depth.

Output:

• section purpose
• node inventory
• primitive and pattern breakdown
• state and responsive clues
• implementation notes without writing code

This mode may inspect multiple nodes if they represent the same section across breakpoints or states.

full-spec

Use only for a bounded page or clearly defined frame set.

Output:

• complete design_analysis.md
• complete page_spec.md
• optional asset_manifest.md
• explicit uncertainty list

Evidence Capture

Before writing any spec, capture evidence in this order when available:

1. get_design_context
2. get_metadata
3. get_screenshot

Record the exact MCP tools used in the output metadata. Preserve screenshot references whenever available.

If a tool is unavailable, record the limitation explicitly rather than silently degrading. If you only have structural metadata or a text summary, reduce confidence and mark the output as not safe for direct implementation.

Workflow

1. Confirm Scope and Provenance First

Before extracting details:

• identify the exact page, frame, section, or bounded node set
• narrow broad requests to a bounded scope
• confirm why each selected node belongs in the same analysis set
• preserve the exact input URL(s), fileKey, and nodeId set that define the scope
• ask for clarification if the design target is ambiguous

2. Capture Evidence Before Interpretation

Before interpreting the design:

• fetch the strongest available Figma context for the chosen node set
• capture a screenshot reference when available
• note which states, breakpoints, and variants are directly evidenced versus missing

3. Read Structure Before Styling

Start from the design tree and identify:

• main sections
• repeated modules
• component instances and variants
• layout containers and hierarchy

Do not start by collecting raw colors or sizes without structural context.

4. Extract Only Reusable Signals

Prioritize reusable patterns over one-off values:

• repeated fills, text styles, spacing, radius, borders, shadows
• component variants and recurring states
• repeated layout patterns and content blocks

Avoid treating every local value as a token candidate.

5. Separate Four Layers

Every spec should clearly distinguish:

• Token: reusable visual rules
• Primitive: basic UI elements and component instances
• Pattern: repeated combinations of primitives
• Page: section order, page goal, and user path

6. Separate Facts From Inference

Every spec should make this distinction explicit:

• observed directly from Figma evidence
• inferred for implementation convenience
• missing evidence that prevents certainty

Do not present inferred behavior as directly observed truth.

7. Record Uncertainty Explicitly

When Figma cannot prove something, say so. Common uncertainty areas:

• hover and pressed states missing from static frames
• responsive behavior not represented in alternate frames
• data behavior and validation logic
• whether a repeated group should be a primitive or pattern

8. Emit Handoff Safety

Every spec must say whether it is:

• safe for token-to-theme
• safe for page-builder in plan mode
• safe for page-builder in direct implement mode

If the evidence is incomplete, explicitly require a follow-up spec pass instead of silently handing off a weak contract.

9. Stop at Spec

This skill must stop after producing documentation artifacts. It should not:

• write Vue or React components
• update tokens in code
• choose final component APIs
• modify Tailwind config or CSS variables

Hard Gates

Canonical Source Gate

Do not generate spec artifacts unless the final metadata can preserve:

• at least one canonical Figma URL or equivalent traceable selection reference
• fileKey
• nodeId list

Evidence Gate

Do not mark output as implementation-ready unless the metadata also records:

• MCP tools used
• screenshot reference or an explicit note that no screenshot was available
• evidence completeness

Composite Frame Gate

Do not emit section-spec from a single composite workspace frame without first narrowing the scope to an internal module or related state set.

Handoff Gate

If confidence is not high, or if key states / breakpoints are missing, the output must explicitly say it is not safe for direct page-builder implementation.

Figma MCP Fallback Rule

If Figma MCP is unavailable in the current environment:

• do not pretend the design has been inspected
• ask for a Figma link, node metadata, screenshots, or exported JSON/text
• continue only with clearly stated limitations

Handoff Guidance

This skill is intended to feed later implementation steps. A downstream workflow should be able to consume:

• design_analysis.md for theme and token work
• page_spec.md for section-by-section implementation
• asset_manifest.md for assets and missing resources
• explicit provenance and evidence fields for later review or regeneration
• handoff safety signals that tell later skills whether more spec work is required

Keep headings stable so later skills can read them without ad hoc parsing.