/generating-figma-design

name: generating-figma-design
description: Use when the user requests to design, create, build, generate, or make a new Figma component or screen — including phrases like "make a button", "design a settings page", "build a new card", "generate X". Produces a CSpec, compiles it to a scene graph, executes it in Figma via MCP, and verifies the output.

{{ACTIVE_RULES}}

Generating Figma Design

Overview

Unified `make` flow: CSpec → scene graph → compiler → Figma execute → screenshot → verify. Replaces the legacy `spec → design → review` cycle with a single compiler-driven action. All tokens resolve against the knowledge base; all Figma API rules are enforced by the compiler.

When to Use

Invoke when the user:

• says `make`, `design`, `create`, `build`, `generate`, or asks for a "new component" / "new screen"
• has already run `setup` (knowledge base exists)
• has an MCP transport available (console or official)

Do NOT use if:

• the user is adjusting an existing design that is already in Figma — use `learning-from-corrections` instead
• the user is archiving or shipping — use `shipping-and-archiving`
• the knowledge base is missing — run `extracting-design-system` first

Procedure

**Before starting, load:**

• `references/compiler-reference.md` (repo-root) — scene graph JSON format and rules
• `references/transport-adapter.md` (repo-root) — transport detection and tool mapping

Prerequisites

• Knowledge base exists (registries populated) — if not: "Run `setup` first"
• MCP transport available (see `references/transport-adapter.md` (repo-root) Section A)

---

Phase A — Context (target: 30s)

A1. Detect transport

Read `references/transport-adapter.md` (repo-root) Section A. Determine console vs official transport.

Console: figma_get_status() -> setup.valid: true
Official: whoami() + test use_figma call

Report:

Transport: {console | official}

A2. Load registry index

Load the **summary** of available DS components — names and types only, not full registry data:

• `registries/components.json` — extract component names, variant property names, and keys
• `registries/variables.json` — extract variable name paths (for token reference validation)
• `registries/text-styles.json` — extract style names (for `$text/` reference validation)
• `registries/icons.json` — extract icon names (if file exists)
• `registries/logos.json` — extract logo names (if file exists)

**Do NOT load guides, patterns, or figma-api-rules.md.** The compiler handles all Figma API rules.

A2b. Check KB freshness (drift guard)

The compiler guarantees every `$token` resolves against the KB — but NOT that the KB still matches the live Figma library. A token removed/renamed in Figma but still present in a stale KB will **compile fine and then fail at execute time**. This check is a runtime guard; it deliberately lives here (not in the compiler), because a time-based check would break the compiler's determinism law.

Read `generatedAt` from each loaded registry and compare to today's date:

• **≤ 7 days** → fresh, no warning.
• **> 7 days** → surface: "⚠ KB last synced {N}d ago — the refresh cron may not be

running; tokens/components may have drifted from live Figma."

• **> 30 days, or `generatedAt` missing** → STRONGLY warn and recommend re-running

`setup` (or the KB cron) before generating: resolved tokens that were removed or renamed in Figma will pass compile but fail on execute.

Carry the KB age into the C4 plan ("KB age: {N}d"). This does not block generation — it informs the user before they commit to a `make`.

A3. Load learnings

Load `knowledge-base/learnings.json` (skip if file doesn't exist).

Filter by context matching the user's description:

• Include all **global** learnings (`scope: "global"`)
• Include **contextual** learnings where `context.screenType` or `context.component` matches

A4. Load recipe index

Load `knowledge-base/recipes/_index.json` (skip if file doesn't exist — no recipes yet).

---

Phase B — Recipe Match

B1. Extract archetype

From the user's description, identify:

• **Mode**: component or screen (ask if ambiguous)
• **Archetype**: screen type (settings, dashboard, form, detail, list...) or component type
• **Keywords**: key terms from the description (sidebar, form, table, cards, navigation...)

B2. Score against recipe index

For each recipe in `_index.json`, compute a match score:

| Dimension | Weight | Method | |-----------|--------|--------| | Archetype match | 0.40 | Exact match on `meta.archetype` vs extracted archetype | | Tag overlap | 0.25 | Jaccard similarity between recipe `tags` and extracted keywords | | Structural match | 0.20 | Zone count, component types, parameter compatibility | | Confidence | 0.15 | Recipe's current confidence score |

B3. Apply match result

| Score | Action | |-------|--------| | **>= 0.85** | **Exact match.** Load recipe file, pre-fill CSpec from recipe parameters. Report: "Recipe match: {name} (score: {score}). Using as template." | | **0.60 -- 0.84** | **Partial match.** Load recipe as scaffold. Report: "Partial recipe match: {name} (score: {score}). Using as starting point, will supplement missing zones." | | **< 0.60** | **No match.** Proceed from scratch. Report: "No recipe match. Generating from scratch." |

---

Phase C — CSpec (target: 30-60s)

C0. Decompose into sections, then classify each (design intelligence)

Before writing any node, break the request into its major sections, then decide HOW each section is built. This is where DS fidelity and composition are won.

**1. Decompose** the request into major sections, top to bottom:

• Screen → e.g. Header, Hero, Content panels, Footer.
• Modal / dialog → Title bar, Body / form sections, Action bar.
• Drawer / sidebar / panel → Navigation, Content area, Footer actions.
• Component → its part structure (container, leading, label, trailing, states).

**2. Classify each section into exactly one bucket**