Build 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 pass
skillNames: "figma-generate-library"
when calling
use_figma
as part of this skill.
This is a logging parameter — it does not affect execution.
1. The One Rule That Matters Most
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.
2. Mandatory Workflow
Every design system build follows this phase order. Skipping or reordering phases causes structural failures that are expensive to undo.
Phase 0: DISCOVERY (always first — no use_figma writes yet)
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, ...
9. Per-Phase Anti-Patterns
Phase 0 anti-patterns:
❌ Starting to create anything before scope is locked with user
❌ Ignoring existing file conventions and imposing new ones
❌ Skipping
search_design_system
before planning component creation
Phase 1 anti-patterns:
❌ Using
ALL_SCOPES
on any variable
❌ Duplicating raw values in semantic layer instead of aliasing
❌ Not setting code syntax (breaks Dev Mode and round-tripping)
❌ Creating component tokens before agreeing on token taxonomy
Phase 2 anti-patterns:
❌ Skipping the cover page or foundations docs
❌ Putting multiple unrelated components on one page
Phase 3 anti-patterns:
❌ Creating components before foundations exist
❌ Hardcoding any fill/stroke/spacing/radius value in a component
❌ Creating a variant per icon (use INSTANCE_SWAP instead)
❌ Not positioning variants after combineAsVariants (they all stack at 0,0)
❌ Building variant matrix > 30 without splitting (variant explosion)
❌ Importing remote components then immediately detaching them
General anti-patterns:
❌ Retrying a failed script without understanding the error first
❌ Using name-prefix matching for cleanup (deletes user-owned nodes)
❌ Building on unvalidated work from the previous step
❌ Skipping user checkpoints to "save time"
❌ Parallelizing use_figma calls (always sequential)
❌ Guessing/hallucinating node IDs from memory (always read from state ledger)
❌ Writing massive inline scripts instead of using the provided helper scripts
❌ Starting Phase 3 because the user said "build the button" without completing Phases 0-2
10. Reference Docs
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
11. Scripts
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