Figma Intake — Structured Discovery

Purpose

Gather everything needed to build a React app from a Figma design in a single structured pass. Auto-discovers what it can, asks the user only what it must, and outputs a machine-readable build-spec.json that downstream skills consume without re-asking questions.

When to Use

• First phase of /build-from-figma pipeline
• Any time a user provides a Figma URL and wants to build from it
• When you need to understand a Figma file's structure before generating code

Inputs

• Required: Figma file URL (with optional node-id)
• Optional: Existing project directory to integrate into

Process

Step 0: Conversation Fast-Path (Skip the Interview)

If .claude/plans/build-spec.json already exists with "source": "conversation", the spec was produced by the conversation-intake skill and the Figma file was generated from it by design-brief-to-figma — the interview already happened in /build-from-conversation. Do not re-interview the user. Instead:

1. Verify the spec's figma block is populated (fileKey, url) and matches the
   URL this skill was invoked with. Mismatch → ask which file wins.
2. Verify the file is reachable: get_metadata(fileKey).
3. Backfill any pages[].figmaNodeId that is still null from the metadata
   (match generated frames to pages by name/order).
4. Keep "source": "conversation" unchanged — downstream phases treat the spec
   exactly like a Figma-sourced one; the source value preserves provenance.
5. Expect no Figma variables in the generated file: token extraction
   (design-token-lock) will fall back to computed styles, which is correct
   here because the captured mockups were rendered from the design brief's
   exact values.
6. Skip Steps 1-3 below entirely and proceed to Step 4 validation /
   Step 5 confirmation only if the spec is incomplete; otherwise report
   "fast-path: spec reused" and hand control back to the pipeline (Phase 2).

If the file at figma.url no longer exists, fall through to the normal flow below using the URL the user provided.

Step 1: Auto-Discovery (No User Input)

Run these Figma MCP calls to gather context automatically:

1. get_metadata(fileKey)        → File name, pages, frames, component counts
2. get_variable_defs(fileKey)   → Design tokens (colors, typography, spacing)
3. get_screenshot(fileKey)      → Visual overview of each page/top-level frame

Simultaneously scan the local project:

1. Detect framework via the renderer registry:
   - Run: node scripts/renderer-registry.js detect . --json
   - On { "renderer": "<name>", "language": "<lang>" }:
       set build-spec renderer = <name>
       set build-spec outputTarget = <language>  (react | vue | svelte | react-native)
   - On { "renderer": null }:
       no framework detected → New project needed (ask output target question)
   Do not hand-sniff config files or package.json deps; the registry owns detection.

2. Detect app type:
   - manifest.json with "manifest_version" → Chrome Extension
   - manifest.json with "start_url" or "display" → PWA
   - Otherwise → Web App

3. Scan existing components:
   - Glob: src/components/**/*.tsx, app/components/**/*.tsx
   - Build inventory: name, props interface, file path

4. Check package.json for UI libraries:
   - @shadcn/ui, @radix-ui/*, @headlessui/react
   - tailwindcss, @emotion/*, styled-components
   - State: zustand, jotai, @tanstack/react-query

5. Check for existing design tokens:
   - tailwind.config.ts theme.extend
   - src/styles/tokens.css or similar
   - design-tokens.lock.json (from prior runs)

6. Load pipeline config:
   - Read .claude/pipeline.config.json for thresholds and app type definitions
   - Use appTypes[detected] for E2E strategy defaults

Step 2: Compile Discovery Summary

Present findings to the user in a structured format:

## Figma File: [name]
- Pages: [list with frame counts]
- Components: [count] unique components
- Design tokens: [count] variables defined
- Color modes: [list if any]

## Local Project
- Framework: [detected or "none"]
- Existing components: [count] in [path]
- UI library: [detected or "none"]
- Design tokens: [existing or "none"]

## Component Mapping
| Figma Component | Existing Match? | Action |
|----------------|-----------------|--------|
| Button/Primary | src/components/ui/Button.tsx | Reuse / Regenerate |
| Card           | (none)                       | Generate new       |
| ...            | ...                          | ...                |

Step 3: Ask Targeted Questions (Max 5)

Only ask questions whose answers cannot be derived from the Figma file or local project. Skip any question where the answer is obvious from context.

Question 1 — Scope:

Which pages/frames should I build? [Show numbered list from Figma] (Default: all top-level frames)

Question 2 — Component Reuse:

I found [N] existing components that match Figma components. Should I: a) Reuse them and only generate missing ones b) Regenerate all from Figma (replaces existing) c) Generate alongside with new names (no overwrites) (Only ask if existing components were found)

Question 3 — Business Logic:

Are there any interactions or business logic beyond what's visible in the design? (e.g., form validation rules, API calls, auth requirements, state machines) (Default: pure presentational)

Question 4 — Text Content:

I extracted these labels/text from Figma. Confirm they're correct as-is? [Show condensed list of headings, button labels, placeholder text] (Default: use as-is)

Question 5 — Integration:

Should this be: a) A standalone app (new project scaffold) b) Integrated into the existing project at [detected path] (Only ask if existing project detected)

Question 6 — Output Target (only if no framework detected):

Run node scripts/renderer-registry.js list --json and present the returned renderer names as the choices (each entry has name and language): "Which renderer should I build this in? [numbered list of registry renderers]"

• Greenfield React default: vite.
• Set build-spec renderer = the chosen name and outputTarget = its language. (Skip if the registry already detected a framework for the existing project.)

Question 7 — App Type (only if ambiguous):

I detected this as a [chrome-extension / web-app / pwa]. Is that correct? (Skip if detection is unambiguous. Skip if manifest.json clearly identifies type.)

Step 4: Generate build-spec.json

Write the spec file that all downstream phases consume:

// .claude/plans/build-spec.json
{
  "version": "1.0.0",
  "source": "figma",              // "figma" | "canva" | "screenshot" | "conversation"
  "renderer": "vite",             // registry renderer name (from `renderer-registry list`): "nextjs" | "vite" | "sveltekit" | "expo" | "astro" | ...
  "outputTarget": "react",    // resolved language; equals the renderer's language. "react" | "vue" | "svelte" | "react-native"
  "createdAt": "2026-03-16T12:00:00Z",
  "figma": {
    "fileKey": "abc123",
    "fileName": "My App Design",
    "url": "https://figma.com/file/abc123/My-App-Design"
  },
  "appType": "web-app",          // "web-app" | "chrome-extension" | "pwa"
  "framework": {
    "type": "vite",           // DEPRECATED — superseded by top-level `renderer`. Retained for back-compat only.
    "version": "6.0.0",
    "outputDir": "src"
  },
  "styling": {
    "approach": "tailwind",   // "tailwind" | "css-modules" | "styled-components"
    "uiLibrary": "shadcn",   // "shadcn" | "radix" | "headless" | "none"
    "existingTokens": false
  },
  "pages": [
    {
      "figmaNodeId": "1:2",
      "name": "Home",
      "route": "/",
      "sections": ["hero", "features", "pricing", "footer"]
    }
  ],
  "components": [
    {
      "figmaNodeId": "3:45",
      "figmaName": "Button/Primary",
      "reactName": "Button",
      "category": "ui",          // "ui" | "layout" | "sections" | "pages"
      "action": "generate",      // "generate" | "reuse" | "extend"
      "existingPath": null,      // path if reusing
      "variants": ["primary", "secondary", "outline"],
      "props": ["variant", "size", "disabled", "children"]
    }
  ],
  "textContent": {
    "hero-heading": "Build faster with AI",
    "hero-subheading": "Ship production apps in days, not months",
    "cta-primary": "Get Started",
    "cta-secondary": "Learn More"
    // ... all text extracted from Figma
  },
  "businessLogic": {
    // User-provided requirements beyond the design
    "forms": [],
    "apiCalls": [],
    "auth": null,
    "stateManagement": null
  },
  "e2e": {
    "strategy": "navigate-interact-verify",  // From pipeline.config.json appTypes
    "flows": [
      {
        "name": "page-navigation",
        "description": "Navigate between all pages and verify rendering",
        "steps": ["navigate to /", "verify hero section visible", "click nav link"]
      }
    ],
    // Chrome extension specific (when appType === "chrome-extension"):
    "extensionManifest": {
      "hasPopup": true,
      "hasBackground": true,
      "hasContentScript": true,
      "contentScriptMatches": ["*://*.example.com/*"],
      "permissions": ["storage", "activeTab"],
      "buildCommand": "pnpm build",
      "extensionPath": "dist"
    }
  },
  "testStrategy": {
    "unit": true,                 // Vitest + RTL for components
    "e2e": true,                  // Playwright E2E
    "visual": true,               // Screenshot comparison
    "crossBrowser": false,        // Firefox + WebKit (web apps only)
    "coverageThreshold": 80
  },
  "options": {
    "componentReuse": "reuse",    // "reuse" | "regenerate" | "alongside"
    "integration": "existing"     // "standalone" | "existing"
  }
}

Renderer fields:

• renderer (string) is the authoritative framework field. Valid values are the renderer names from node scripts/renderer-registry.js list --json (currently nextjs, vite, sveltekit, expo, astro).
• outputTarget is retained and equals the resolved renderer's language (react / vue / svelte / react-native). Set both together from the registry detect/resolve output.
• framework.type is deprecated — folded into renderer. Keep it only for back-compat with older specs; renderer wins on any conflict.
• Back-compat rule: a build-spec carrying only outputTarget (no renderer) resolves to that language's DEFAULT renderer: react → vite, svelte → sveltekit, react-native → expo. (vue has no renderer yet — its default is unsupported/future.)

Step 5: Confirm and Proceed

Present a summary of the build plan:

## Build Plan Summary
- Framework: Vite 6.0
- Pages: 3 (Home, Pricing, Dashboard)
- Components: 12 to generate, 4 to reuse
- Design tokens: 45 variables to extract
- Output: src/components/, src/pages/

Proceed with token extraction? (This starts the autonomous pipeline)

Wait for user confirmation before the pipeline continues.

Output

Primary: .claude/plans/build-spec.json Secondary: Build plan summary displayed to user

Error Handling

• Figma MCP unavailable: Ask user to verify Figma Desktop is running or provide file key manually
• No Figma variables defined: Warn that token extraction will rely on computed styles (less accurate)
• Ambiguous framework: Ask user to specify rather than guessing
• Empty Figma file: Abort with clear message

Integration

• Consumed by: design-token-lock, tdd-from-figma, figma-to-react-workflow, /build-from-figma
• Fast-path trigger: a build-spec with "source": "conversation" (written by conversation-intake and completed by design-brief-to-figma in /build-from-conversation) skips the interview — see Step 0
• Uses: Figma MCP (get_metadata, get_variable_defs, get_screenshot), Glob, Read