figma-intake

name	figma-intake
description	Structured interview that auto-discovers Figma file structure, project context, and asks 3-5 targeted questions to produce a build-spec.json. Entry point for the autonomous build pipeline. Keywords: Figma intake, build spec, project discovery, figma interview, build plan

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 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:
   - next.config.* → Next.js (check App Router vs Pages Router)
   - vite.config.* → Vite
   - remix.config.* → Remix
   - None → New project needed

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

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

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

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)

Step 4: Generate build-spec.json

Write the spec file that all downstream phases consume:

// .claude/plans/build-spec.json
{
  "version": "1.0.0",
  "createdAt": "2026-03-16T12:00:00Z",
  "figma": {
    "fileKey": "abc123",
    "fileName": "My App Design",
    "url": "https://figma.com/file/abc123/My-App-Design"
  },
  "framework": {
    "type": "vite",           // "nextjs-app" | "nextjs-pages" | "vite" | "remix"
    "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
  },
  "options": {
    "componentReuse": "reuse",    // "reuse" | "regenerate" | "alongside"
    "integration": "existing"     // "standalone" | "existing"
  }
}

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
• Uses: Figma MCP (get_metadata, get_variable_defs, get_screenshot), Glob, Read