figma-bridge

# Figma Bridge — Implement Design

## Overview

Structured workflow to translate Figma designs into production-ready code with 1:1 visual fidelity. Ensures integration with the Figma MCP server, correct use of design tokens, and visual parity with mockups.

## Prerequisites

- **Figma MCP** configured in the project's `.mcp.json` (automatically created by `init-project.sh`). On first session, authenticate: `/mcp` → figma → Authenticate → Allow Access.
- Figma URL in the format: `https://figma.com/design/:fileKey/:fileName?node-id=1-2`
- **Or** with `figma-desktop` MCP: direct node selection in the desktop app (no URL required)

## Workflow — Follow these steps in order. Do not skip steps.

### Step 0: Verify Figma MCP is configured

If an MCP call fails because the Figma server is not connected, stop and configure:

1. Verify that `.mcp.json` in the project root contains the `figma` server (see `references/figma-mcp-setup.md`)
2. If missing, create it or run `init-project.sh`
3. Authenticate: `/mcp` → figma → Authenticate → Allow Access
4. Restart Claude Code after configuration
5. Verify with a test call (e.g., `get_screenshot` on a known node)

Once configured, this step does not need to be repeated in subsequent sessions (the OAuth token is persisted).

### Step 1: Get the Node ID

#### Option A: Parse from the Figma URL

URL format: `https://figma.com/design/:fileKey/:fileName?node-id=1-2`

Extract:
- **File key:** the segment after `/design/`
- **Node ID:** the value of the `node-id` parameter

Example:
- URL: `https://figma.com/design/kL9xQn2VwM8pYrTb4ZcHjF/DesignSystem?node-id=42-15`
- File key: `kL9xQn2VwM8pYrTb4ZcHjF`
- Node ID: `42-15`

#### Option B: Selection from desktop app (figma-desktop MCP only)

With the desktop MCP, tools automatically use the selected node in the open file. No need to pass `fileKey`.

### Step 2: Read the Design Context

Use `get_design_context` with the extracted file key and node ID:

```
get_design_context(fileKey=":fileKey", nodeId="1-2")
```

Provides:
- Layout (Auto Layout, flex, grid, constraints, sizing)
- Typographic specs
- Colors and design tokens
- Component structure and variants
- Spacing and padding

**If the response is truncated or too large:**

1. Use `get_metadata(fileKey=":fileKey", nodeId="1-2")` to get the high-level node map
2. Identify the needed child nodes from metadata
3. Fetch individual children with `get_design_context(fileKey=":fileKey", nodeId=":childNodeId")`

### Step 3: Capture the Visual Reference

Use `get_screenshot` as the visual source of truth:

```
get_screenshot(fileKey=":fileKey", nodeId="1-2")
```

Don't rely solely on the data structure — the screenshot confirms the expected appearance. Keep it accessible throughout the implementation.

### Step 4: Download Assets

Download images, icons, and SVGs returned by the Figma MCP server.

**Asset rules:**
- If the MCP returns a `localhost` source for an image or SVG, use it directly
- DO NOT import or add icon packages — all assets must come from the Figma payload
- DO NOT use or create placeholders if a `localhost` source is available
- Assets are served from the Figma MCP server's assets endpoint

### Step 5: Verify Project Tokens

Use `get_variable_defs` to verify that design tokens match those in the theme CSS files. Flag discrepancies to the designer.

Read these CSS files for actual values — don't rely on markdown tables:

| File | Content |
|------|---------|
| `{{TOKEN_FILE_THEME}}` | `@theme {}` block — colors, spacing, radius, font, breakpoints, gradients |
| `{{TOKEN_FILE_CUSTOM_PROPS}}` | `:root` semantic CSS vars |
| `{{TOKEN_FILE_SEMANTIC}}` | `@utility` for semantic colors, bg, border, link |
| `{{TOKEN_FILE_TYPOGRAPHY}}` | Heading and body classes |

### Step 6: Translate to Project Conventions

Generate code based on the structure read from MCP, not invented layout.

**Principles:**
- Treat Figma output as a representation of design and behavior, not as final code style
- Use project tokens — not hardcoded values
- Reuse existing components (buttons, inputs, typography) instead of duplicating functionality
- Consult `{{COMPONENTS_CATALOG}}` — use existing components where possible
- If a component doesn't exist, generate markup following the design system pattern
- Apply accessibility rules (skill `accessibility`)
- Flag if new components are needed

### Step 7: Completion and Verification

Report completion to the user. Visual verification is the user's responsibility — if they provide a screenshot for comparison, adjust the implementation accordingly.

#### Self-check checklist

- [ ] Spacing consistent with the px → Tailwind mapping (see `component-workflow` step 5.5)
- [ ] Correct typography (appropriate `rtds-heading-N` or `rtds-body-N` class)
- [ ] Colors via semantic vars or utilities (no hardcoded hex)
- [ ] Interactive states working (hover, active, disabled)
- [ ] Responsive behavior consistent with Figma constraints
- [ ] Assets rendered correctly
- [ ] Accessibility standards met

## Token Pipeline: Figma → Code

```
Figma Variables
     ↓
Variables2CSS plugin (in browser)
     ↓
{{TOKEN_FILE_THEME}} (@theme block)
     ↓
{{TOKEN_FILE_CUSTOM_PROPS}} (:root vars)
{{TOKEN_FILE_SEMANTIC}} (semantic @utility)
     ↓
TW4 classes with project prefix (e.g.: {{PREFIX}}:bg-primary-500, {{PREFIX}}:p-4)
+ semantic utilities (e.g.: {{PREFIX}}-content-01, {{PREFIX}}-background-primary)
```

### Token update

When the designer updates tokens in Figma:
1. Opens the Variables2CSS plugin
2. Selects the collections to export
3. Chooses "CSS Custom Properties" format
4. Copies the output and updates `{{TOKEN_FILE_THEME}}` / `{{TOKEN_FILE_CUSTOM_PROPS}}`
5. The browser auto-refreshes (Vite hot reload)

No need to modify `app.css` — the `@theme` mapping uses `var()` which updates automatically.

## Figma → Tailwind 4 Mapping

| Figma Property | How to find the value | Example class/variable |
|---|---|---|
| Fill > color | 1) Find hex. 2) Search in `{{TOKEN_FILE_THEME}}`. 3) Search semantic var in `{{TOKEN_FILE_CUSTOM_PROPS}}`. 4) Use var or utility from `{{TOKEN_FILE_SEMANTIC}}` | `var(--color-content-primary)` or `{{PREFIX}}-content-primary` or `{{PREFIX}}:bg-primary-500` |
| Auto Layout > Gap | **px / 4 = Tailwind number**. E.g.: 16px / 4 = 4 | `{{PREFIX}}:gap-4` |
| Padding | **px / 4 = Tailwind number**. E.g.: 24px / 4 = 6 | `{{PREFIX}}:p-6`, `{{PREFIX}}:px-8` |
| Corner Radius | Search in `{{TOKEN_FILE_THEME}}` → `--radius-*` | `{{PREFIX}}:rounded-md`, `{{PREFIX}}:rounded-lg` |
| Drop Shadow | Search in `{{TOKEN_FILE_THEME}}` → `--shadow-*` | `{{PREFIX}}:shadow-sm`, `{{PREFIX}}:shadow-md` |
| Font Outfit | Use heading class matching the size | `.{{PREFIX}}-heading-1` ... `.{{PREFIX}}-heading-6` |
| Font DM Sans | Use body class matching the size | `.{{PREFIX}}-body-xs` ... `.{{PREFIX}}-body-xl` |
| Semantic color | Search in `{{TOKEN_FILE_SEMANTIC}}` for the utility class | `{{PREFIX}}-content-01`, `{{PREFIX}}-background-primary` |

> **Quick spacing rule**: `Figma px / 4 = Tailwind class number`. E.g.: 32px = `{{PREFIX}}:p-8`, 48px = `{{PREFIX}}:p-12`
>
> **Quick typography rule**: Outfit → `{{PREFIX}}-heading-N`, DM Sans → `{{PREFIX}}-body-N`
>
> **Full tables** for spacing, typography, and colors: see `component-workflow` skill, section 5.5.

## Discrepancies and Troubleshooting

### Common discrepancies

- **Token in design but not in CSS**: the designer needs to update CSS files with Variables2CSS
- **Hardcoded values in design**: ask the designer if the value should be a token
- **Figma component without counterpart**: generate markup following the design system pattern
- **Colors not in palette**: check `{{TOKEN_FILE_THEME}}` — might be a color with a different name

### Frequent issues

| Issue | Cause | Solution |
|-------|-------|----------|
| Truncated Figma output | Design too complex or too many nested levels | Use `get_metadata` for the node map, then fetch individual children with `get_design_context` |
| Design doesn't match after implementation | Visual discrepancies between code and mockup | Compare side-by-side with the Step 3 screenshot. Check spacing, colors, and typography in context data |
| Assets not loading | MCP assets endpoint not accessible or URLs changed | Verify the Figma MCP assets endpoint is accessible. Use `localhost` URLs directly without modifications |
| Token values differ from Figma | Project tokens have different values than those in the design | Prefer project tokens for consistency, but adjust spacing/sizing to maintain visual fidelity |

## Examples

### Example 1: Implementing a UI component

The user shares: `https://figma.com/design/kL9xQn2VwM8pYrTb4ZcHjF/DesignSystem?node-id=42-15`

**Actions:**
1. Parse URL → fileKey=`kL9xQn2VwM8pYrTb4ZcHjF`, nodeId=`42-15`
2. `get_design_context(fileKey="kL9xQn2VwM8pYrTb4ZcHjF", nodeId="42-15")`
3. `get_screenshot(fileKey="kL9xQn2VwM8pYrTb4ZcHjF", nodeId="42-15")` for visual reference
4. Download icons/images from the assets endpoint
5. Check if a similar component exists in `{{COMPONENTS_CATALOG}}`
6. If it exists → extend it with the new variant. If not → create a new component following the design system conventions
7. Map Figma colors to project tokens (e.g., `primary-500`, `primary-hover`)
8. Validate against the screenshot: padding, border radius, typography

**Result:** Component that respects the Figma design, integrated into the project's design system.

### Example 2: Implementing a page layout

The user shares: `https://figma.com/design/pR8mNv5KqXzGwY2JtCfL4D/Pages?node-id=10-5`

**Actions:**
1. Parse URL → fileKey=`pR8mNv5KqXzGwY2JtCfL4D`, nodeId=`10-5`
2. `get_metadata(fileKey="pR8mNv5KqXzGwY2JtCfL4D", nodeId="10-5")` to understand the structure (complex page)
3. Identify main sections (header, content, sidebar, footer) and their node IDs
4. `get_design_context` for each main section
5. `get_screenshot(fileKey="pR8mNv5KqXzGwY2JtCfL4D", nodeId="10-5")` for the full page
6. Download all assets (logos, icons, images)
7. Build the layout using existing components where possible
8. Implement each section reusing components from `{{COMPONENTS_CATALOG}}`
9. Validate responsive behavior against Figma constraints

**Result:** Complete page layout, faithful to the design, with reused design system components.

## Best Practices

### Always start from context

Don't implement based on assumptions. Always run `get_design_context` and `get_screenshot` before writing code.

### Validate incrementally

Compare your code with the Figma screenshot and design context data during implementation. Verify spacing, typography, and colors using the token mapping tables. If you have doubts about fidelity, flag it to the user.

### Document deviations

If you must deviate from the Figma design (e.g., for accessibility, technical constraints, or framework limitations), document the reason with a code comment.

### Design System First

When in doubt, prefer the project's design system patterns over a literal Figma translation. Codebase consistency matters more than exact replication.

### Reuse before recreation

Always check `{{COMPONENTS_CATALOG}}` for existing components before creating new ones. Extend rather than duplicate.

## References

- `references/figma-tools-and-prompts.md` — Complete MCP tool catalog and prompt patterns
- `references/figma-mcp-setup.md` — Setup, verification, and troubleshooting for the Figma MCP server