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 paste; the returned code is reference, not production

## HTML Prototype Fallback (no Figma)

When Figma tooling isn't available, produce a **single self-contained, clickable HTML prototype** so the designer still gets something real to look at and click through:

1. Build one HTML file using the team's **tokens** (as CSS custom properties), the **content-writer's exact copy**, and design-lead's layout decisions
2. Make the key task from the brief actually clickable — real states, not a flat mock
3. Keep it accessible by construction — semantic HTML, visible focus, contrast that meets AA, `prefers-reduced-motion` honoured (this is Designpowers; the prototype is not exempt)
4. Open/screenshot it and show the designer; save it alongside `design-state.md`

This is a viewing-and-feedback artefact, not the shipping build — but it's real enough to react to, which is the whole point.

## Rules

1. **Never fabricate content.** Use the content-writer's strings. If none exist, mark placeholders clearly for content review.
2. **Build on-system.** Use tokens and components so the artefact is editable, not a flattened picture.
3. **Accessibility carries over.** Whatever you produce — Figma frames or HTML — meets the same inclusive standard as the rest of the pipeline. A visual artefact is not an excuse to drop AA.
4. **Record the link.** Always write the Figma file key/URL or prototype path into `design-state.md` so the team and the next session can find it.
5. **Adapt, don't paste.** Code returned from `get_design_context` is reference; fit it to the project's stack and standards.

## Integration

- **Invoked at:** the Screenshot Checkpoint and Handoff in `using-designpowers`; from `design-review` (Figma artefacts); on user request
- **Reads from:** `design-state.md`, design-lead decisions, `token-architecture`, content-writer output, `design-builder` code
- **Uses:** the Figma MCP tools (gated by `/figma-use` and the other Figma skills) when available; HTML fallback otherwise
- **Feeds:** `design-review` (artefact), `design-system-alignment` / `token-architecture` (extracted tokens), `design-builder` (reference code)
- **Records to:** `design-state.md` (artefact link/path)