Bridge Design

# Bridge Design

Guide the user through the complete design phase.

## Step 0 — Read design source from state

Read `.bridge-os/state.json` and check `design_source`.

- If `"figma"` → go directly to **PATH A — Figma MCP** below
- If `"design-os"` → go directly to **PATH B — Design OS** below
- If `null` or missing → ask the user:

---

**`/bridge-init` was not run yet, or the design source was not set.
How would you like to define your design tokens?**

**A) Figma MCP** — Pull colors, typography, and spacing directly from your Figma file.
**B) Design OS** — Full interactive design workflow with live preview.

**Which path? (A or B)**

---

Save the choice to `.bridge-os/state.json`:
- Path A → `"design_source": "figma"`
- Path B → `"design_source": "design-os"`

Then follow the corresponding path below.

---

---

# PATH A — Figma MCP

## Important

Figma MCP must be configured in Claude Code. The user should have added
`figma-developer/mcp` (or equivalent) to their Claude Code MCP settings.

This path pulls design tokens (colors, typography, spacing) from Figma variables.
Product vision, roadmap, and data shape are still defined through conversation here.

---

## Steps

### A-1. Verify Figma MCP is available

Try calling a Figma MCP tool (e.g. `get_local_variables` with a dummy key or any
lightweight tool) to detect if the Figma MCP is connected.

**If Figma MCP responds correctly → continue to Step A-2.**

**If Figma MCP is NOT available → run the setup guide below before continuing.**

---

#### 🔧 Figma MCP Setup Guide

Tell the user:

"Figma MCP is not connected. Let's set it up — it takes about 2 minutes.
You'll need a Figma account with access to your design file."

**Step 1 — Get a Figma Personal Access Token**

Tell the user:
1. Go to [figma.com](https://www.figma.com) and log in
2. Click your profile icon (top-left) → **Settings**
3. Scroll to **Security** → **Personal access tokens**
4. Click **Generate new token**
   - Name: `Bridge OS` (or anything)
   - Expiration: choose as needed
   - Scopes: enable **File content** (Read)
5. Copy the token — it starts with `figd_`

Ask: "Do you have your Figma token ready? (paste it here or type 'yes' when done)"

**Step 2 — Add Figma MCP to Claude Code settings**

Tell the user:
"Now I'll add the Figma MCP server to your Claude Code settings."

Check if `~/.claude/settings.json` exists. Read it.

Add the following inside the `mcpServers` object (create it if it doesn't exist):

```json
"Figma": {
  "command": "npx",
  "args": ["--yes", "figma-developer/mcp", "--stdio"],
  "env": {
    "FIGMA_ACCESS_TOKEN": "<TOKEN_FROM_STEP_1>"
  }
}

Replace <TOKEN_FROM_STEP_1> with the actual token the user provided.

The full ~/.claude/settings.json structure should look like:

{
  "mcpServers": {
    "Figma": {
      "command": "npx",
      "args": ["--yes", "figma-developer/mcp", "--stdio"],
      "env": {
        "FIGMA_ACCESS_TOKEN": "figd_xxxxxxxxxxxx"
      }
    }
  }
}

Write the updated settings file.

Step 3 — Restart Claude Code MCP connection

Tell the user: "Settings saved. Now restart Claude Code to activate the Figma MCP:

1. Press Cmd+Q (Mac) or close the Claude Code window
2. Reopen your project: claude in the terminal
3. Run /bridge-design again — Figma MCP will be available"

Stop here. Do not continue until the user restarts and re-runs /bridge-design.

---

Once Figma MCP is verified as available, ask the user for their Figma file URL.

A Figma URL looks like: https://www.figma.com/file/XXXXXXXXXXX/My-Product The file key is the segment after /file/ → XXXXXXXXXXX

A-2. Pull design tokens from Figma

Use the Figma MCP to read the file's local variables. Call the available Figma MCP tool (e.g. get_local_variables or figma_get_file_variables) with the extracted file key.

Parse the response to extract:

• Colors — variables of type COLOR → convert RGBA floats to hex
• Typography — variables of type STRING containing font names or sizes
• Spacing — variables of type FLOAT in collections named "Spacing", "Scale", or similar
• Any other relevant variables

Save the processed tokens to .bridge-os/figma-tokens.json in this format:

{
  "source": "figma",
  "fileKey": "<extracted-key>",
  "fileName": "<file name from API>",
  "syncedAt": "<ISO timestamp>",
  "colors": [
    { "name": "Primary/Blue", "cssVar": "--color-primary-blue", "value": "#6366F1" }
  ],
  "typography": [
    { "name": "Font/Sans", "cssVar": "--font-sans", "value": "Inter" },
    { "name": "Font/Size/Base", "cssVar": "--font-size-base", "value": "16px" }
  ],
  "spacing": [
    { "name": "Space/4", "cssVar": "--space-4", "value": "4px" }
  ],
  "other": []
}

Rules for naming CSS variables from Figma variable names:

• Replace / with -
• Lowercase everything
• Prefix by type: colors → --color-, fonts → --font-, spacing → --space-
• Example: Primary/Blue → --color-primary-blue

Confirm to the user: "✅ Figma tokens pulled: X colors, Y typography, Z spacing variables."

Show a summary table of the tokens found.

If the Figma MCP is not available or errors out, tell the user: "Figma MCP is not responding. Ensure figma-developer/mcp is configured in your Claude Code settings, or switch to Path B (Design OS)."

A-3. Product Vision

Tell the user: "Now let's define what you're building. I'll ask you a few questions."

Ask and document:

1. What is the product name and one-sentence description?
2. Who are the target users?
3. What are the 3-5 core features?
4. What problem does it solve?

Write the answers to agent-os/product/overview.md:

# Product Overview

## Product
[name and description]

## Target Users
[description]

## Core Features
[list]

## Problem Statement
[problem being solved]

A-4. Product Roadmap

Tell the user: "Now let's define the sections (screens/areas) of your product."

Ask:

• What are the main sections of the app? (e.g. Dashboard, Setti