Loading
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, create individual components with proper var
The skill file stays in the publisher's repository.
Paste the copied command in a terminal. It installs this SKILL.md into that agent.
npx skills add Devin-AXIS/iPolloWork --skill figma-generate-library -a cursor -y
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, create individual components with proper variant sets and variable bindings, set up theming (light/dark modes), document foundations, or reconcile gaps between code and Figma. Also use when the user asks to create or generate any component in Figma — even a single one — since components require proper variable foundations, variant states, and design token bindings to be production-quality. 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.
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, create individual components with proper variant sets and variable bindings, set up theming (light/dark modes), document foundations, or reconcile gaps between code and Figma. Also use when the user asks to create or generate any component in Figma — even a single one — since components require proper variable foundations, variant states, and design token bindings to be production-quality. 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.
figma-use skill which teaches HOW to call the Plugin API. Both skills should be loaded together."
disable-model-invocation: falseBuild 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).
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.
Always include figma-generate-library in the comma-separated skillNames parameter when calling use_figma as part of this skill. If this skill was loaded via an MCP resource, you MUST prefix the name with resource: (e.g. resource:figma-generate-library). This is a logging parameter — it does not affect execution.
For every phase, follow this communication contract.
Before starting a phase:
Phase N Checklist.During execution:
Working on Phase N.X: <section name>At the end of each phase:
Phase N Summary with:
Use one task ID format everywhere: P{phase}.{step}.
Rules:
P0.a, P0.b, P1.a, P3.d.No setup exception: Creating a new Figma file, importing a library, creating pages, variables, collections, styles, or components all count as creation/mutation. Do not treat any of them as harmless setup.
This is NEVER a one-shot task. Building a design system requires 20–100+ use_figma calls across multiple phases, with mandatory progress 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.
Work through the phases in order. Do not move to the next phase until the current phase's required actions and acceptance checks are complete. If a phase cannot pass, stop and report the blocker. Do not approximate, skip, or defer a failed phase unless the user explicitly approves the limitation. No best-effort substitutions. No quiet approximations. No handoff with missing source truth, missing visual truth, fake assets, approximate typography, broken interactions, or unverified states.
use_figma writes yet)search_design_system for reusable assetsALL_SCOPES)get_screenshot of every foundations page and print the page list to chat alongside the screenshotsFor EACH component (in dependency order: atoms before molecules), run the checklist below. Finish the current component before starting the next.
combineAsVariants + grid layout)get_metadata (structure) + get_screenshot (visual)Plugin API basics (from use_figma skill — enforced here too):
return to send data back (auto-serialized). Do NOT wrap in IIFE or call closePlugin.await figma.setCurrentPageAsync(page) at start. Call it at most once per script: each component or doc page is its own use_figma call. Never loop over figma.root.children and switch pages inside a mutating script — split that work into one focused call per target page (see figma-use → gotchas.md → Set current page once per use_figma call)figma.notify() throws — never use itawait 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.Design system rules:
use_figma to discover existing conventions. Match them.ALL_SCOPES. Background: FRAME_FILL, SHAPE_FILL. Text: TEXT_FILL. Border: STROKE_COLOR. Spacing: GAP. Radii: CORNER_RADIUS. Primitives: [] (hidden).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.{ type: 'VARIABLE_ALIAS', id: primitiveVar.id }. Never duplicate raw values in semantic layer.get_metadata after every create, get_screenshot after each component.use_figma calls — Figma state mutations must be strictly sequential. Even if your tool supports parallel calls, never run two use_figma calls simultaneously.scripts/ into your use_figma calls. Don't write 200-line inline scripts from scratch.
getPluginData()/setPluginData()are NOT supported inuse_figma. UsegetSharedPluginData()/setSharedPluginData()instead (these ARE supported), or use name-based lookups and the state ledger (returned IDs).
| Entity type | Idempotency key | How to check existence |
|---|---|---|
| Scene nodes (pages, frames, components) | setSharedPluginData('dsb', 'key', value) or unique name | node.getSharedPluginData('dsb', 'key') or page.findOne(n => n.name === 'Button') |
| Variables | Name within collection | (await figma.variables.getLocalVariablesAsync()).find(v => v.name === name && v.variableCollectionId === collId) |
| Styles | Name | getLocalTextStyles().find(s => s.name === name) |
Tag every created scene node immediately after creation:
node.setSharedPluginData('dsb', 'run_id', RUN_ID); // identifies this build run
node.setSharedPluginData('dsb', 'phase', 'phase3'); // which phase created it
node.setSharedPluginData('dsb', 'key', 'component/button');// unique logical key
State persistence: Do NOT rely solely on conversation context for the state ledger. Write it to disk:
/tmp/dsb-state-{RUN_ID}.json
Re-read this file at the start of every turn. In long workflows, conversation context will be truncated — the file is the source of truth.
Maintain a state ledger tracking:
{
"runId": "ds-build-2024-001",
"phase": "phase3",
"step": "component-button",
"entities": {
"collections": { "primitives": "id:...", "color": "id:..." },
"variables": { "color/bg/primary": "id:...", "spacing/sm": "id:..." },
"pages": { "Cover": "id:...", "Button": "id:..." },
"components": { "Button": "id:..." }
},
"pendingValidations": ["Button:screenshot"],
"completedSteps": ["phase0", "phase1", "phase2", "component-avatar"]
}
Idempotency check before every create: query by name + state ledger ID. If exists, skip or update — never duplicate.
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.
Continuation prompt (give this to the user when resuming in a new chat):
"I'm continuing a design system build. Run ID: {RUN_ID}. Load the figma-generate-library skill and resume from the last completed step."
Search FIRST in Phase 0, then again immediately before each component creation.
Start with get_libraries to understand what libraries are available before searching blindly:
// Discover all libraries accessible to the file
get_libraries({ fileKey })
// Returns:
// libraries_added_to_file: [{ name, libraryKey, description, source }, ...]
// libraries_available_to_add: [{ name, libraryKey, description, source }, ...]
// libraries_available_to_add_next_offset: number | null
Use the returned libraryKey values to scope searches to specific libraries via includeLibraryKeys. This avoids noisy results when many libraries are available.
If libraries_available_to_add_next_offset is non-null, more org libraries are available — call get_libraries again with offset set to that value. Org libraries page in batches of 20; community UI kits only appear on the first page.
// Search across all libraries (default)
search_design_system({ query, fileKey, includeComponents: true, includeVariables: true, includeStyles: true })
// Search within a specific library only
search_design_system({ query, fileKey, includeLibraryKeys: ["lk-abc123..."], includeComponents: true })
Reuse if all of these are true:
Rebuild if any of these:
Wrap if visual match but API incompatible:
Priority order: local existing → subscribed library import → unsubscribed UI Kit library from libraries_available_to_add (icons especially) → create new.
Ask the user when paths fork — when two or more reasonable answers exist and no clear winner comes from the codebase, the Figma file, or the locked plan. Don't silently default. Present each option with its tradeoff and your recommendation; pick only after the user steers.
When NOT to ask: if exactly one path is clearly correct from the source of truth (code, Figma file, agreed plan), take it. This section is for genuine ambiguity, not for offloading every decision.
| Fork situation | What to surface | Example ask |
|---|---|---|
| Code ≠ Figma on a token, component, or value | Both versions side by side, with provenance (file/line vs node) | "Code says --color-bg-primary = #FFFFFF, Figma has color/bg/primary = #FAFAFA. Which wins?" |
| Subscribed library has a close-but-not-exact match | Library component summary + gap list | "Library has Button with no loading state. Reuse + wrap locally, or rebuild from scratch?" |
| Scope ambiguity at plan-lock (0d) | What's clearly in, what's clearly out, what's ambiguous | "Spec lists Button and Input; Field is referenced but not defined. In or out of v1?" |
If the user rejects an option you already built on: fix before moving on. Never build on rejected work.
Match existing file conventions. If starting fresh:
Variables (slash-separated):
color/bg/primary color/text/secondary color/border/default
spacing/xs spacing/sm spacing/md spacing/lg spacing/xl spacing/2xl
radius/none radius/sm radius/md radius/lg radius/full
typography/body/font-size typography/heading/line-height
Primitives: blue/50 → blue/900, gray/50 → gray/900
Component names: Button, Input, Card, Avatar, Badge, Checkbox, Toggle
Variant names: Property=Value, Property=Value — e.g., Size=Medium, Style=Primary, State=Default
Page separators: --- (most common) or ——— COMPONENTS ———
Full naming reference: naming-conventions.md
| Complexity | Pattern |
|---|---|
| < 50 tokens | Single collection, 2 modes (Light/Dark) |
| 50–200 tokens | Standard: Primitives (1 mode) + Color semantic (Light/Dark) + Spacing (1 mode) + Typography (1 mode) |
| 200+ tokens | Advanced: Multiple semantic collections, 4–8 modes (Light/Dark × Contrast × Brand). See M3 pattern in token-creation.md |
Standard pattern (recommended starting point):
Collection: "Primitives" modes: ["Value"]
blue/500 = #3B82F6, gray/900 = #111827, ...
Collection: "Color" modes: ["Light", "Dark"]
color/bg/primary → Light: alias Primitives/white, Dark: alias Primitives/gray-900
color/text/primary → Light: alias Primitives/gray-900, Dark: alias Primitives/white
Collection: "Spacing" modes: ["Value"]
spacing/xs = 4, spacing/sm = 8, spacing/md = 16, ...
Phase 0 anti-patterns:
search_design_system before planning component creationPhase 1 anti-patterns:
ALL_SCOPES on any variablePhase 2 anti-patterns:
Phase 3 anti-patterns:
General anti-patterns:
Load on demand — each reference is authoritative for its phase:
Use your file reading tool to read these docs when needed. Do not assume their contents from the filename.
| Doc | Phase | Required / Optional | Load when |
|---|---|---|---|
| discovery-phase.md | 0 | Required | Starting any build — codebase analysis + Figma inspection |
| token-creation.md | 1 | Required | Creating variables, collections, modes, styles |
| documentation-creation.md | 2 | Required | Creating cover page, foundations docs, swatches |
| component-creation.md | 3 | Required | Creating any component or variant |
| code-connect-setup.md | 3–4 | Required | Setting up Code Connect or variable code syntax |
| naming-conventions.md | Any | Optional | Naming anything — variables, pages, variants, styles |
| error-recovery.md | Any | Required on error | Script fails, multi-step workflow recovery, cleanup of abandoned workflow state |
Reusable Plugin API helper functions. Embed in use_figma calls:
| Script | Purpose |
|---|---|
| inspectFileStructure.js | Discover all pages, components, variables, styles; returns full inventory |
| createVariableCollection.js | Create a named collection with modes; returns {collectionId, modeIds} |
| createSemanticTokens.js | Create aliased semantic variables from a token map |
| createComponentWithVariants.js | Build a component set from a variant matrix; handles grid layout |
| bindVariablesToComponent.js | Bind design tokens to all component visual properties |
| createDocumentationPage.js | Create a page with title + description + section structure |
| validateCreation.js | Verify created nodes match expected counts, names, structure |
| cleanupOrphans.js | Remove orphaned nodes by name convention or state ledger IDs |
| rehydrateState.js | Scan file for all pages, components, variables by name; returns full {key → nodeId} map for state reconstruction |