bitovi/ai-enablement-prompts/figma-from-code

Skill: Build Figma from Code (Orchestrator)

Thin dispatcher. Delegates every phase to a subagent, reads only small summary files, and tracks progress in state.json. Never calls use_figma or get_screenshot directly.

Required Inputs

• fileKey: Figma file key
• resume (optional): true to skip completed phases
• config (optional): per-project overrides; any omitted key falls back to the generic default shown below

{
  "devServerUrl": "http://localhost:5173",
  "devServerStart": "npm run dev",
  "sourceDir": "src",                          // app source root
  "componentsRoot": ["src/components"],        // array of component directories (supports monorepos); populated after Phase 0a discovery
  "pagesRoot": "src/pages",                    // where page/screen sources + figma-screen.json live
  "cssPath": "src/index.css",                  // CSS custom-properties file for token extraction
  "tailwindConfigPath": "tailwind.config.js",  // or null for Tailwind v4 / vanilla CSS projects
  "iconLibrary": "lucide-react",               // or null to skip icon extraction
  "skillRoot": "plugins/figma-from-code/skills/figma-from-code"  // where this skill tree lives; ${CLAUDE_PLUGIN_ROOT}/skills/figma-from-code when running as an installed plugin
}

Hard Gates — Files the Orchestrator Must Never Read

The orchestrator is a thin dispatcher. It must not open, read, or load any sub-skill SKILL.md files. Those files are for subagents only.

Forbidden reads (orchestrator):

What the orchestrator reads instead: only small summary/output files under .temp/figma-from-code/ (e.g., discovery-summary.json, tokens-summary.json, structure-summary.json).

If you find yourself opening a sub-skill SKILL.md to understand inputs, outputs, or workflow steps — stop. That information belongs in the dispatch table and per-phase notes in _this_ file. If those notes are missing, ask the user before proceeding.

Subagent Dispatch Pattern

When dispatching a subagent:

1. Give the subagent only: the skill filepath + fileKey + any state fields it needs (listed in the table below)
2. Instruct the subagent to read its own skill file for full instructions
3. Tell the subagent to report back only: { "success": true/false, "outputFile": "<path>" }
4. Read the output file yourself after the subagent completes

The orchestrator never re-explains what a skill does — the skill file is the source of truth. The orchestrator never opens a sub-skill's SKILL.md file — see Hard Gates above.

Config Placeholder Convention

Sub-skill files reference config values as {devServerUrl}, {sourceDir}, {componentsRoot}, {pagesRoot}, {cssPath}, {tailwindConfigPath}, {iconLibrary}, {skillRoot}, etc. Subagents resolve these placeholders from state.json → config before executing any commands. The orchestrator also substitutes resolved values from state.config when composing dispatch prompts so subagents always receive concrete paths and URLs.

`componentsRoot` is an array. Most config references pass the full array to subagents. Subagents that write .figma/ tracking files derive the write path from each component's sourcePath (in component-map.json) rather than from a single componentsRoot prefix. For synthetic components (icons, assets) that have no source file, use the first entry in the array.

State Ledger

Maintain .temp/figma-from-code/state.json:

{
  "fileKey": "{fileKey}",
  "startedAt": "ISO timestamp",
  "config": {
    "devServerUrl": "http://localhost:5173",
    "devServerStart": "npm run dev",
    "sourceDir": "packages/client/src",
    "componentsRoot": ["packages/client/src/components"],
    "pagesRoot": "packages/client/src/pages",
    "cssPath": "packages/client/src/index.css",
    "tailwindConfigPath": "packages/client/tailwind.config.js",
    "iconLibrary": "lucide-react",
    "skillRoot": "plugins/figma-from-code/skills/figma-from-code"
  },
  "phases": {
    "phase0a": "complete|in_progress|pending",
    "phase0b": "complete|in_progress|pending",
    "phase1": "complete|in_progress|pending",
    "phase2": "complete|in_progress|pending",
    "phase2_5": "complete|in_progress|pending",
    "phase3": "complete|in_progress|pending",
    "phase4": "complete|in_progress|pending",
    "phase5": "complete|in_progress|pending"
  },
  "tierProgress": { "tier1": "complete|complete_with_failures|in_progress|pending" },
  "buildOrder": { "tierCount": 0, "tiers": [{ "tier": 1, "label": "...", "components": ["..."] }] },
  "figmaNodes": {
    "foundationsPageId": "...",
    "componentsPageId": "...",
    "screensPageId": "...",
    "foundationsFrameId": "...",
    "iconsFrameId": "...",
    "screensFrameId": "...",
    "tier1FrameId": "...",
    "tier2FrameId": "..."
  },
  "existingCollections": [],
  "existingPages": [],
  "variableMapPath": ".temp/figma-from-code/variables.json",
  "builtComponents": {},
  "builtScreens": {},
  "preExistingComponents": {},
  "preExistingScreens": {},
  "screenBodySize": { "w": 1440, "h": 900 },
  "iconDiscovery": { "iconCount": 0, "icons": [], "assetCount": 0, "assets": [] }
}

Subagents do not modify state.json. Each writes its own output file; the orchestrator reads it and updates state.

figmaNodes uses the pattern tier{N}FrameId for each tier (e.g., tier1FrameId, tier2FrameId, ...). The number of keys matches buildOrder.tierCount.

Fresh Run: Initialize state.json

Config detection (runs once, before Phase 0a). On a fresh run the orchestrator detects project-specific values before writing state.json:

1. Read package.json (root and any workspace roots) — find the dev or start script and extract the port from --port, PORT=, or Vite/CRA defaults; derive devServerUrl.
2. Set componentsRoot to [] (empty array). Component directories are discovered by Phase 0a and confirmed by the user at the Wave 1 pause. Set sourceDir to the most likely app source root (e.g., src, packages/client/src) based on package.json workspace structure.
3. Locate the pages/screens directory: look for pages, screens, or routes under sourceDir.
4. Locate the CSS custom-properties file: prefer src/index.css, packages/*/src/index.css, or any *.css file containing -- custom properties.
5. Detect tailwindConfigPath: check for tailwind.config.js, tailwind.config.ts, tailwind.config.cjs at the repo root and likely package roots; set to null if absent (Tailwind v4 / vanilla CSS project).
6. Detect iconLibrary: grep package.json dependencies for lucide-react, react-icons, @heroicons/react, @radix-ui/react-icons; use the first match or null.
7. Present the resolved config to the user in a compact table. Note that componentsRoot will be populated after Phase 0a discovery. Ask for confirmation or corrections before proceeding.
8. Persist the confirmed object as config in state.json. On resume, read config from state.json — never re-detect.

After confirming config, create .temp/figma-from-code/state.json from the template above. Set fileKey and startedAt to current ISO timestamp; set config to the confirmed object; all phases values to "pending"; all other fields empty.

Pre-Existing Components Rule

preExistingComponents is an immutable snapshot from Phase 0a. Never update it after Phase 0a.

Hard rule: Pause and get explicit user authorization before any action that modifies, replaces, or deletes a node in preExistingComponents. This includes rebuilding, running the icon preamble over existing icons, or any Phase 3 build that resolves to a pre-existing node.

Phase Dispatch Table

All skill files live under {skillRoot}/. Shell steps (normalization after Phase 0b, aggregation scripts after Phase 3 tiers and Phase 4) are in Per-Phase Notes. After each subagent succeeds, set phases.{phase}: complete in addition to the listed state fields.

Important: Each subagent does all of its work inline — no subagent spawns further subagents. Phase 3 dispatches one subagent per component (fresh context each time). The validation subagent (Phase 5) processes all screens sequentially.