3. Critical Rules

Plugin API basics (from use_figma skill — enforced here too):

• Use return to send data back (auto-serialized). Do NOT wrap in IIFE or call closePlugin.
• Return ALL created/mutated node IDs in every return value
• Page context resets each call — always await figma.setCurrentPageAsync(page) at start
• figma.notify() throws — never use it
• Colors are 0–1 range, not 0–255
• Font MUST be loaded before any text write: await figma.loadFontAsync({family, style})

Design system rules:

1. Variables BEFORE components — components bind to variables. No token = no component.
2. Inspect before creating — run read-only use_figma to discover existing conventions. Match them.
3. One page per component (default) — exception: tightly related families (e.g., Input + helpers) may share a page with clear section separation.
4. Bind visual properties to variables (default) — fills, strokes, padding, radius, gap. Exceptions: intentionally fixed geometry (icon pixel-grid sizes, static dividers).
5. 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).
6. 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.
7. Alias semantics to primitives — { type: 'VARIABLE_ALIAS', id: primitiveVar.id }. Never duplicate raw values in semantic layer.
8. Position variants after combineAsVariants — they stack at (0,0). Manually grid-layout + resize.
9. INSTANCE_SWAP for icons — never create a variant per icon. Cap variant matrices: if Size × Style × State > 30 combinations, split into sub-component.
10. Deterministic naming — use consistent, unique node names for idempotent cleanup and resumability. Track created node IDs via return values and the state ledger.
11. No destructive cleanup — cleanup scripts identify nodes by name convention or returned IDs, not by guessing.
12. Validate before proceeding — never build on unvalidated work. get_metadata after every create, get_screenshot after each component.
13. 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.
14. Never hallucinate Node IDs — always read IDs from the state ledger returned by previous calls. Never reconstruct or guess an ID from memory.
15. Use the helper scripts — embed scripts from scripts/ into your use_figma calls. Don't write 200-line inline scripts from scratch.
16. 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.

4. State Management (Required for Long Workflows)

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).

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."

5. search_design_system — Reuse Decision Matrix

Search FIRST in Phase 0, then again immediately before each component creation.

search_design_system({ query, fileKey, includeComponents: true, includeVariables: true, includeStyles: true })

Reuse if all of these are true:

• Component property API matches your needs (same variant axes, compatible types)
• Token binding model is compatible (uses same or aliasable variables)
• Naming conventions match the target file
• Component is editable (not locked in a remote library you don't own)

Rebuild if any of these:

• API incompatibility (different property names, wrong variant model)
• Token model incompatible (hardcoded values, different variable schema)
• Ownership issue (can't modify the library)

Wrap if visual match but API incompatible:

• Import the library component as a nested instance inside a new wrapper component
• Expose a clean API on the wrapper

Three-way priority: local existing → subscribed library import → create new.

6. User Checkpoints

Mandatory. Design decisions require human judgment.

If user rejects: fix before moving on. Never build on rejected work.

7. Naming Conventions

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

8. Token Architecture

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.

11. Scripts

Reusable Plugin API helper functions. Embed in use_figma calls: