/figma-bridge

name: figma-bridge
description: Use to turn Designpowers' markdown specs into something a designer can actually SEE and manipulate, and to pull existing Figma work back in. Bridges in both directions — push design-lead's visual decisions or built code into real Figma frames (code-to-design), and pull a Figma file in for review or as a design-system source (design-to-code). Falls back to a clickable HTML prototype when Figma isn't available. Invoke at the screenshot checkpoint, at handoff, when reviewing a Figma link, or whenever the user says "show me", "put this in Figma", or "make it real"

Figma Bridge

Designpowers produces excellent *specifications* — briefs, principles, layout decisions, token systems, copy. But designers think visually, and a spec is not a thing you can look at and feel. This skill closes the loop: it turns the team's decisions into a **visual artefact** the designer can see and manipulate, and it pulls existing visual work back into the workflow.

It bridges both directions:

• **Code/spec → design** ("make it real"): push design-lead's visual decisions, the design system, or the built code into real Figma frames
• **Design → code/spec** ("read this in"): pull an existing Figma file in as the artefact for `design-review`, or as the source for `token-architecture` / `design-system-alignment`

When Figma isn't available, it degrades gracefully to a **clickable HTML prototype** — no designer is left without something to look at.

When to Use

• **At the screenshot checkpoint** (after `design-builder`) — give the designer a manipulable artefact, not just a screenshot of code
• **At handoff** — sync the final design into Figma so engineering and design share one source
• **In `design-review`** — when the artefact to review is a Figma file or link, pull it in here
• **As a design-system source** — when the user has a Figma library, extract its tokens/components to seed `token-architecture` and `design-system-alignment`
• **On request** — "show me", "put this in Figma", "can I see it", "make it real"

Prerequisite: Detect Figma Availability

Check whether the Figma MCP tools are available in this environment (tools named `get_design_context`, `get_screenshot`, `use_figma`, `create_new_file`, `generate_figma_design`, etc.).

• **If available:** use the Figma direction below.
• **If not available:** skip to the **HTML Prototype Fallback**. Do not block the workflow waiting for Figma.

> ⚠️ **Mandatory before any Figma *write*:** load Figma's own usage guidance first — invoke the `/figma-use` skill if present, otherwise read the `skill://figma/figma-use/SKILL.md` MCP resource. Writing to Figma via `use_figma` without it causes common, hard-to-debug failures. The same applies to `/figma-generate-design` (capturing a web view), `/figma-generate-library` (building a design system in Figma), and `/figma-code-connect` (mapping components). This skill orchestrates *when* to bridge; those Figma skills govern *how* to write.

Direction A: Spec/Code → Figma (make it real)

Turn what the team designed into frames the designer can manipulate.

A1. Assemble the visual source of truth

Gather from `design-state.md` and the build:

• **design-lead's** layout, colour, typography, and component decisions
• The **token system** (from `token-architecture` / `design-system-alignment`) — these become Figma variables/styles
• The **content-writer's** exact strings — use them verbatim, never lorem ipsum or rewrites
• The **built code**, if `design-builder` has run

A2. Choose the right tool

| Situation | Tool | Notes | |-----------|------|-------| | Building a screen from scratch / from spec / from intent | `use_figma` | The default for all Figma writes. Build from design-system components where they exist | | Capturing an existing **running web view** into Figma for the first time | `generate_figma_design` **+** `use_figma` in parallel | `generate_figma_design` grabs a pixel-perfect screenshot; `use_figma` rebuilds it from real components; refine against the screenshot | | A brand-new file is needed | `create_new_file` | Then `use_figma` to populate it | | Pushing the **token system** into Figma | `use_figma` | Create variables/styles first, then build components that reference them — so the designer can re-theme |

Always build from the design system's tokens and components when they exist, so the result is editable and on-system — not a flat picture.

A3. Reconnect (optional but recommended)

If the project has real code components, map them to the Figma components via **Code Connect** (`/figma-code-connect`, `add_code_connect_map`) so design and code stay linked for the next round.

A4. Show and hand back

Screenshot the result (`get_screenshot`), show it to the designer, and record the Figma file key/URL in `design-state.md`. The designer can now manipulate it directly — and any changes they make can be pulled back via Direction B.

Direction B: Figma → Spec/Code (read it in)

Pull existing Figma work into the workflow.

B1. Get a node-specific URL

The design-to-code tools need a node id. If the user gives a bare file URL, ask for a URL with `?node-id=…` (or a specific frame selection). Extract `fileKey` and `nodeId` from the URL.

B2. Pull context

• `get_design_context` — reference code + screenshot + metadata for the node (the primary design-to-code call)
• `get_screenshot` — visual only, when you just need to see it (e.g., feeding `design-review`)
• `get_metadata` — structure/layer tree for large files
• `get_variable_defs` / `get_libraries` — extract tokens and library structure when seeding a design system

B3. Route the result

• **For review:** hand the screenshot + context to `design-review` as the artefact
• **For a design-system source:** feed variables and components into `token-architecture` and `design-system-alignment`
• **For a build:** adapt the reference code to the project's stack via `design-builder` — adapt, don't past