Figma Generate Library

1---2name: figma-generate-library3description: "Build or update a professional-grade design system in Figma from a codebase. Use when the user wants to create variables/tokens, build component libraries, set up theming (light/dark modes), document foundations, or reconcile gaps between code and Figma. This skill teaches WHAT to build and in WHAT ORDER — it complements the `figma-use` skill which teaches HOW to call the Plugin API. Both skills should be loaded together."4disable-model-invocation: false5---6 7# Design System Builder — Figma MCP Skill8 9Build professional-grade design systems in Figma that match code. This skill orchestrates multi-phase workflows across 20–100+ `use_figma` calls, enforcing quality patterns from real-world design systems (Material 3, Polaris, Figma UI3, Simple DS).10 11**Prerequisites**: The `figma-use` skill MUST also be loaded for every `use_figma` call. It provides Plugin API syntax rules (return pattern, page reset, ID return, font loading, color range). This skill provides design system domain knowledge and workflow orchestration.12 13**Always pass `skillNames: "figma-generate-library"` when calling `use_figma` as part of this skill.** This is a logging parameter — it does not affect execution.14 15---16 17## 1. The One Rule That Matters Most18 19**This is NEVER a one-shot task.** Building a design system requires 20–100+ `use_figma` calls across multiple phases, with mandatory user checkpoints between them. Any attempt to create everything in one call WILL produce broken, incomplete, or unrecoverable results. Break every operation to the smallest useful unit, validate, get feedback, proceed.20 21---22 23## 2. Mandatory Workflow24 25Every design system build follows this phase order. Skipping or reordering phases causes structural failures that are expensive to undo.26 27```28Phase 0: DISCOVERY (always first — no use_figma writes yet)29  0a. Analyze codebase → extract tokens, components, naming conventions30  0b. Inspect Figma file → pages, variables, components, styles, existing conventions31  0c. Search subscribed libraries → use search_design_system for reusable assets32  0d. Lock v1 scope → agree on exact token set + component list before any creation33  0e. Map code → Figma → resolve conflicts (code and Figma disagree = ask user)34  ✋ USER CHECKPOINT: present full plan, await explicit approval35 36Phase 1: FOUNDATIONS (tokens first — always before components)37  1a. Create variable collections and modes38  1b. Create primitive variables (raw values, 1 mode)39  1c. Create semantic variables (aliased to primitives, mode-aware)40  1d. Set scopes on ALL variables41  1e. Set code syntax on ALL variables42  1f. Create effect styles (shadows) and text styles (typography)43  → Exit criteria: every token from the agreed plan exists, all scopes set, all code syntax set44  ✋ USER CHECKPOINT: show variable summary, await approval45 46Phase 2: FILE STRUCTURE (before components)47  2a. Create page skeleton: Cover → Getting Started → Foundations → --- → Components → --- → Utilities48  2b. Create foundations documentation pages (color swatches, type specimens, spacing bars)49  → Exit criteria: all planned pages exist, foundations docs are navigable50  ✋ USER CHECKPOINT: show page list + screenshot, await approval51 52Phase 3: COMPONENTS (one at a time — never batch)53  For EACH component (in dependency order: atoms before molecules):54    3a. Create dedicated page55    3b. Build base component with auto-layout + full variable bindings56    3c. Create all variant combinations (combineAsVariants + grid layout)57    3d. Add component properties (TEXT, BOOLEAN, INSTANCE_SWAP)58    3e. Link properties to child nodes59    3f. Add page documentation (title, description, usage notes)60    3g. Validate: get_metadata (structure) + get_screenshot (visual)61    3h. Optional: lightweight Code Connect mapping while context is fresh62    → Exit criteria: variant count correct, all bindings verified, screenshot looks right63    ✋ USER CHECKPOINT per component: show screenshot, await approval before next component64 65Phase 4: INTEGRATION + QA (final pass)66  4a. Finalize all Code Connect mappings67  4b. Accessibility audit (contrast, min touch targets, focus visibility)68  4c. Naming audit (no duplicates, no unnamed nodes, consistent casing)69  4d. Unresolved bindings audit (no hardcoded fills/strokes remaining)70  4e. Final review screenshots of every page71  ✋ USER CHECKPOINT: complete sign-off72```73 74---75 76## 3. Critical Rules77 78**Plugin API basics** (from use_figma skill — enforced here too):79- Use `return` to send data back (auto-serialized). Do NOT wrap in IIFE or call closePlugin.80- Return ALL created/mutated node IDs in every return value81- Page context resets each call — always `await figma.setCurrentPageAsync(page)` at start82- `figma.notify()` throws — never use it83- Colors are 0–1 range, not 0–25584- Font MUST be loaded before any text write: `await figma.loadFontAsync({family, style})`. Use `await figma.listAvailableFontsAsync()` to discover available fonts and verify exact style strings — if a load fails, query available fonts to find the correct name or a fallback.85 86**Design system rules**:871. **Variables BEFORE components** — components bind to variables. No token = no component.882. **Inspect before creating** — run read-only `use_figma` to discover existing conventions. Match them.893. **One page per component** *(default)* — exception: tightly related families (e.g., Input + helpers) may share a page with clear section separation.904. **Bind visual properties to variables** *(default)* — fills, strokes, padding, radius, gap. Exceptions: intentionally fixed geometry (icon pixel-grid sizes, static dividers).915. **Scopes on every variable** — NEVER leave as `ALL_SCOPES`. Background: `FRAME_FILL, SHAPE_FILL`. Text: `TEXT_FILL`. Border: `STROKE_COLOR`. Spacing: `GAP`. Radii: `CORNER_RADIUS`. Primitives: `[]` (hidden).926. **Code syntax on every variable** — WEB syntax MUST use the `var()` wrapper: `var(--color-bg-primary)`, not `--color-bg-primary`. Use the actual CSS variable name from the codebase. ANDROID/iOS do NOT use a wrapper.937. **Alias semantics to primitives** — `{ type: 'VARIABLE_ALIAS', id: primitiveVar.id }`. Never duplicate raw values in semantic layer.948. **Position variants after combineAsVariants** — they stack at (0,0). Manually grid-layout + resize.959. **INSTANCE_SWAP for icons** — never create a variant per icon. Cap variant matrices: if Size × Style × State > 30 combinations, split into sub-component.9610. **Deterministic naming** — use consistent, unique node names for idempotent cleanup and resumability. Track created node IDs via return values and the state ledger.9711. **No destructive cleanup** — cleanup scripts identify nodes by name convention or returned IDs, not by guessing.9812. **Validate before proceeding** — never build on unvalidated work. `get_metadata` after every create, `get_screenshot` after each component.9913. **NEVER parallelize `use_figma` calls** — Figma state mutations must be strictly sequential. Even if your tool supports parallel calls, never run two use_figma calls simultaneously.10014. **Never hallucinate Node IDs** — always read IDs from the state ledger returned by previous calls. Never reconstruct or guess an ID from memory.10115. **Use the helper scripts** — embed scripts from `scripts/` into your use_figma calls. Don't write 200-line inline scripts from scratch.10216. **Explicit phase approval** — at each checkpoint, name the next phase explicitly. "looks good" is not approval to proceed to Phase 3 if you asked about Phase 1.103 104---105 106## 4. State Management (Required for Long Workflows)107 108> **`getPluginData()` / `setPluginData()` are NOT supported in `use_figma`.** Use `getSharedPluginData()` / `setSharedPluginData()` instead (these ARE supported), or use name-based lookups and the state ledger (returned IDs).109 110| Entity type | Idempotency key | How to check existence |111|-------------|----------------|----------------------|112| Scene nodes (pages, frames, components) | `setSharedPluginData('dsb', 'key', value)` or unique name | `node.getSharedPluginData('dsb', 'key')` or `page.findOne(n => n.name === 'Button')` |113| Variables | Name within collection | `(await figma.variables.getLocalVariablesAsync()).find(v => v.name === name && v.variableCollectionId === collId)` |114| Styles | Name | `getLocalTextStyles().find(s => s.name === name)` |115 116Tag every created **scene node** immediately after creation:117```javascript118node.setSharedPluginData('dsb', 'run_id', RUN_ID);        // identifies this build run119node.setSharedPluginData('dsb', 'phase', 'phase3');        // which phase created it120node.setSharedPluginData('dsb', 'key', 'component/button');// unique logical key121```122 123**State persistence**: Do NOT rely solely on conversation context for the state ledger. Write it to disk:124```125/tmp/dsb-state-{RUN_ID}.json126```127Re-read this file at the start of every turn. In long workflows, conversation context will be truncated — the file is the source of truth.128 129Maintain a state ledger tracking:130```json131{132  "runId": "ds-build-2024-001",133  "phase": "phase3",134  "step": "component-button",135  "entities": {136    "collections": { "primitives": "id:...", "color": "id:..." },137    "variables": { "color/bg/primary": "id:...", "spacing/sm": "id:..." },138    "pages": { "Cover": "id:...", "Button": "id:..." },139    "components": { "Button": "id:..." }140  },141  "pendingValidations": ["Button:screenshot"],142  "completedSteps": ["phase0", "phase1", "phase2", "component-avatar"]143}144```145 146**Idempotency check** before every create: query by name + state ledger ID. If exists, skip or update — never duplicate.147 148**Resume protocol**: at session start or after context truncation, run a read-only `use_figma` to scan all pages, components, variables, and styles by name to reconstruct the `{key → id}` map. Then re-read the state file from disk if available.149 150**Continuation prompt** (give this to the user when resuming in a new chat):151> "I'm continuing a design system build. Run ID: {RUN_ID}. Load the figma-generate-library skill and resume from the last completed step."152 153---154 155## 5. search_design_system — Reuse Decision Matrix156 157Search FIRST in Phase 0, then again immediately before each component creation.158 159```160search_design_system({ query, fileKey, includeComponents: true, includeVariables: true, includeStyles: true })161```162 163**Reuse if** all of these are true:164- Component property API matches your needs (same variant axes, compatible types)165- Token binding model is compatible (uses same or aliasable variables)166- Naming conventions match the target file167- Component is editable (not locked in a remote library you don't own)168 169**Rebuild if** any of these:170- API incompatibility (different property names, wrong variant model)171- Token model incompatible (hardcoded values, different variable schema)172- Ownership issue (can't modify the library)173 174**Wrap if** visual match but API incompatible:175- Import the library component as a nested instance inside a new wrapper component176- Expose a clean API on the wrapper177 178**Three-way priority**: local existing → subscribed library import → create new.179 180---181 182## 6. User Checkpoints183 184Mandatory. Design decisions require human judgment.185 186| After | Required artifacts | Ask |187|-------|-------------------|-----|188| Discovery + scope lock | Token list, component list, gap analysis | "Here's my plan. Approve before I create anything?" |189| Foundations | Variable summary (N collections, M vars, K modes), style list | "All tokens created. Review before file structure?" |190| File structure | Page list + screenshot | "Pages set up. Review before components?" |191| Each component | get_screenshot of component page | "Here's [Component] with N variants. Correct?" |192| Each conflict (code ≠ Figma) | Show both versions | "Code says X, Figma has Y. Which wins?" |193| Final QA | Per-page screenshots + audit report | "Complete. Sign off?" |194 195**If user rejects**: fix before moving on. Never build on rejected work.196 197---198 199## 7. Naming Conventions200 201Match existing file conventions. If starting fresh:202 203**Variables** (slash-separated):204```205color/bg/primary     color/text/secondary    color/border/default206spacing/xs  spacing/sm  spacing/md  spacing/lg  spacing/xl  spacing/2xl207radius/none  radius/sm  radius/md  radius/lg  radius/full208typography/body/font-size    typography/heading/line-height209```210 211**Primitives**: `blue/50` → `blue/900`, `gray/50` → `gray/900`212 213**Component names**: `Button`, `Input`, `Card`, `Avatar`, `Badge`, `Checkbox`, `Toggle`214 215**Variant names**: `Property=Value, Property=Value` — e.g., `Size=Medium, Style=Primary, State=Default`216 217**Page separators**: `---` (most common) or `——— COMPONENTS ———`218 219> Full naming reference: [naming-conventions.md](references/naming-conventions.md)220 221---222 223## 8. Token Architecture224 225| Complexity | Pattern |226|-----------|---------|227| < 50 tokens | Single collection, 2 modes (Light/Dark) |228| 50–200 tokens | **Standard**: Primitives (1 mode) + Color semantic (Light/Dark) + Spacing (1 mode) + Typography (1 mode) |229| 200+ tokens | **Advanced**: Multiple semantic collections, 4–8 modes (Light/Dark × Contrast × Brand). See M3 pattern in [token-creation.md](references/token-creation.md) |230 231Standard pattern (recommended starting point):232```233Collection: "Primitives"    modes: ["Value"]234  blue/500 = #3B82F6, gray/900 = #111827, ...235 236Collection: "Color"         modes: ["Light", "Dark"]237  color/bg/primary → Light: alias Primitives/white, Dark: alias Primitives/gray-900238  color/text/primary → Light: alias Primitives/gray-900, Dark: alias Primitives/white239 240Collection: "Spacing"       modes: ["Value"]241  spacing/xs = 4, spacing/sm = 8, spacing/md = 16, ...242```243 244---245 246## 9. Per-Phase Anti-Patterns247 248**Phase 0 anti-patterns:**249- ❌ Starting to create anything before scope is locked with user250- ❌ Ignoring existing file conventions and imposing new ones251- ❌ Skipping `search_design_system` before planning component creation252 253**Phase 1 anti-patterns:**254- ❌ Using `ALL_SCOPES` on any variable255- ❌ Duplicating raw values in semantic layer instead of aliasing256- ❌ Not setting code syntax (breaks Dev Mode and round-tripping)257- ❌ Creating component tokens before agreeing on token taxonomy258 259**Phase 2 anti-patterns:**260- ❌ Skipping the cover page or foundations docs261- ❌ Putting multiple unrelated components on one page262 263**Phase 3 anti-patterns:**264- ❌ Creating components before foundations exist265- ❌ Hardcoding any fill/stroke/spacing/radius value in a component266- ❌ Creating a variant per icon (use INSTANCE_SWAP instead)267- ❌ Not positioning variants after combineAsVariants (they all stack at 0,0)268- ❌ Building variant matrix > 30 without splitting (variant explosion)269- ❌ Importing remote components then immediately detaching them270 271**General anti-patterns:**272- ❌ Retrying a failed script without understanding the error first273- ❌ Using name-prefix matching for cleanup (deletes user-owned nodes)274- ❌ Building on unvalidated work from the previous step275- ❌ Skipping user checkpoints to "save time"276- ❌ Parallelizing use_figma calls (always sequential)277- ❌ Guessing/hallucinating node IDs from memory (always read from state ledger)278- ❌ Writing massive inline scripts instead of using the provided helper scripts279- ❌ Starting Phase 3 because the user said "build the button" without completing Phases 0-2280 281---282 283## 10. Reference Docs284 285Load on demand — each reference is authoritative for its phase:286 287Use your file reading tool to read these docs when needed. Do not assume their contents from the filename.288 289| Doc | Phase | Required / Optional | Load when |290|-----|-------|---------------------|-----------|291| [discovery-phase.md](references/discovery-phase.md) | 0 | **Required** | Starting any build — codebase analysis + Figma inspection |292| [token-creation.md](references/token-creation.md) | 1 | **Required** | Creating variables, collections, modes, styles |293| [documentation-creation.md](references/documentation-creation.md) | 2 | Required | Creating cover page, foundations docs, swatches |294| [component-creation.md](references/component-creation.md) | 3 | **Required** | Creating any component or variant |295| [code-connect-setup.md](references/code-connect-setup.md) | 3–4 | Required | Setting up Code Connect or variable code syntax |296| [naming-conventions.md](references/naming-conventions.md) | Any | Optional | Naming anything — variables, pages, variants, styles |297| [error-recovery.md](references/error-recovery.md) | Any | **Required on error** | Script fails, multi-step workflow recovery, cleanup of abandoned workflow state |298 299---300 301## 11. Scripts302 303Reusable Plugin API helper functions. Embed in `use_figma` calls:304 305| Script | Purpose |306|--------|---------|307| [inspectFileStructure.js](scripts/inspectFileStructure.js) | Discover all pages, components, variables, styles; returns full inventory |308| [createVariableCollection.js](scripts/createVariableCollection.js) | Create a named collection with modes; returns `{collectionId, modeIds}` |309| [createSemanticTokens.js](scripts/createSemanticTokens.js) | Create aliased semantic variables from a token map |310| [createComponentWithVariants.js](scripts/createComponentWithVariants.js) | Build a component set from a variant matrix; handles grid layout |311| [bindVariablesToComponent.js](scripts/bindVariablesToComponent.js) | Bind design tokens to all component visual properties |312| [createDocumentationPage.js](scripts/createDocumentationPage.js) | Create a page with title + description + section structure |313| [validateCreation.js](scripts/validateCreation.js) | Verify created nodes match expected counts, names, structure |314| [cleanupOrphans.js](scripts/cleanupOrphans.js) | Remove orphaned nodes by name convention or state ledger IDs |315| [rehydrateState.js](scripts/rehydrateState.js) | Scan file for all pages, components, variables by name; returns full `{key → nodeId}` map for state reconstruction |