Figma ball knowledge

Figma Ball Knowledge: Orchestrator

Read this skill first. Every Figma session starts here: preference check, parallel discovery, URL resolution, capability selection, execution plan.

---

Global Rule: AskUserQuestion

Any time the agent needs to ask the user a question, whether for clarification, ambiguity resolution, preference confirmation, or page selection, use the AskUserQuestion method. This applies at every stage of the workflow without exception.

Non-Claude hosts: AskUserQuestion is a Claude Code / Claude Desktop tool. When running under Cursor, Codex, or any other host that lacks this tool, ask the question in plain text and present options as a numbered list if the skill specifies multiple choice. See references/cursor-tools.md (Cursor) or references/codex-tools.md (Codex) for the full tool mapping.

---

Output Principles: How the Harness Talks to a Designer

Designers scan plans and audit reports in under a minute. Every response that summarizes work follows three rules.

Lead with the bottom line. The first sentence of any audit, plan, or post-write summary must answer the designer's question without preamble. Methodology, raw tool output, and supporting data live below that opening line or move to an appendix block.

Translate every observation into a design decision. Surfacing a fact is not the deliverable; the deliverable is what the designer should do about it. A token gap, a contrast failure, or a missing component match is a decision point, not a status update. Pair every observation with its implication and the recommended next move.

Ground specifics in evidence the designer can verify. Use exact node IDs, exact token names, exact hex values, exact contrast ratios, exact library keys. Avoid abstract phrasing like "improved consistency" or "enhanced design system coverage." If the agent cannot confirm a fact from a tool call in this session, say so plainly: "no library match found for 'notification card'" beats "may not have a match."

Tone calibration: matter-of-fact when reporting risks (token gaps, contrast failures, library drift); a friendly expert when surfacing wins (clean migrations, full token coverage, successful imports). Never use ambient enthusiasm such as "fascinating," "great news," or "excited to share" to dress up a result. Never end a summary by restating what was just said; close on the implication or the next decision instead.

---

Anti-Hallucination Guardrails

Every claim about file state must trace back to a tool call returned in this session.

• No fabricated component matches. If search_design_system returns no result for an element, the component map records "no match: raw frame." Never name a component the designer has not seen surface in discovery results.
• No invented token names. If a hex value has no matching variable in the Stage 2 audit, log it as a token gap with the exact hex and node ID. Never invent or guess a token name to fill the silence.
• No silent gaps. If discovery cannot resolve a target (page name, component, library, file key), return "NOT FOUND" with the exact search query used. Do not paper over the absence with a plausible-sounding placeholder.
• No second-hand facts. Recalled facts from a previous turn must be re-verified against a live tool call before they enter a plan. Memory of "what worked last time" is a hint, not evidence.
• Single-source caps. A discovery summary that leans on one search result for more than half its findings is suspect; rerun targeted searches before declaring the file's state.

---

Three-Layer Model

The harness has three layers, each with a different rule for who writes to it.

1. Capability files (figma-*.md): protected reference libraries for one API surface. Read the ones your task needs. Edit only when Figma itself changes or a new platform-wide constraint is discovered, and only after proposing the change via AskUserQuestion.
2. Script library (scripts/*.js): reusable use_figma snippets. Any new reusable snippet longer than twenty lines becomes a script. See scripts/README.md for the contract.
3. Design skills (design-skills/<file-key>/*.md): file-specific and library-specific observations. Auto-loaded at Stage 2 Call 6. The harness writes these without asking; they are descriptive, not opinionated. See design-skills/README.md for the format.

User workflow preferences sit alongside these layers, not inside them. See figma-personal-workflow.md for the capture protocol.

---

Capability Files

These are reference libraries, not sequential workflows. Read every file whose capability is needed for the current task. Multiple files are read together, not exclusively.

File	API surface covered
figma-read.md	Reading existing design state: get_design_context, get_metadata, get_variable_defs, source parsing
figma-frames.md	Frame and layout creation: createFrame, auto-layout, rightEdge placement, section pattern
figma-components.md	Component instances, library import, component creation, bottom-up build order
figma-tokens.md	Variable and style binding, token architecture, WCAG, migration
figma-vectors.md	Vectors, shapes, boolean ops, gradients, image fills
figma-documentation.md	Style guide specimens, Code Connect, token export, FigJam diagrams
figma-files.md	File creation, page management
figma-code.md	Protected API constraints: font loading, async lookup, sizing lifecycle, binding patterns
figma-personal-workflow.md	Capturing and applying designer preferences
figma-research.md	Strategic research: competitive audits, PESTLE/SWOT, BLUF synthesis, "So What?" test, quality gates

Workflow References

Longer workflows live alongside their parent capability files. Read these when their specific workflow applies.

File	When to read
references/component-swap.md	Replacing every instance of a deprecated component across a file
references/component-reactions.md	Wiring prototype reactions to boolean variables (filter chips, toggle states)
references/vector-effects-exports.md	Applying effects, gradients, or setting up node exports
references/cursor-tools.md	Tool-name translation when running under Cursor
references/codex-tools.md	Tool-name translation when running under Codex

Bundled Scripts

File	Contents
scripts/discovery-audit.js	Discovery audit script. Paste into use_figma.
scripts/rightedge-placement.js	rightEdge frame placement boilerplate
scripts/wcag-contrast.js	getLuminance + contrastRatio utilities
scripts/bind-fill.js	bindFill, bindStroke, safeAppend utilities
scripts/token-audit.js	Hardcoded fill finder + token gap logger
scripts/component-swap.js	Full instance swap + master deletion protocol

---

Stage 1: Preference Check

Before any tool call, check whether a ## Designer Workflow Preferences section exists in any capability file relevant to the task. If preferences are present, load them into working memory -- they override all defaults for this session.

---

Stage 2: Parallel Discovery

Run once per session at first contact with a file. Never repeat while edits are in progress.

The full discovery audit script is in scripts/discovery-audit.js -- paste it directly into a use_figma call. Call all six in the same response:

Call 1 -- Local audit (use_figma -- paste scripts/discovery-audit.js): returns local variable collections, text/paint/effect styles.

Call 2 -- Published library components: search_design_system("")

Call 3 -- Remote library variables and styles (critical -- Call 1 misses these entirely): search_design_system("", { includeVariables: true, includeStyles: true })

getLocalVariableCollectionsAsync() only returns variables created in this file. Files using a shared/published library will have remote variables invisible to Call 1. Call 3 surfaces them. Merge both results before building the Session Context token picture.

Call 4 -- File/node structure: get_metadata(resolvedNodeId ?? fileRoot)

Call 5 -- Visual baseline (only if a target node-id was provided): get_screenshot(resolvedNodeId)

Call 6 -- Design-skill load (runs after Stage 3 URL resolution returns the file key):

Read every markdown file under design-skills/<file-key>/. If library keys surface in Call 2 or Call 3, also read every file under design-skills/libraries/<library-key>/. Treat contents as session context: they reflect what has worked in this file before, but they are not authoritative the way capability files are. If a design skill contradicts a capability file, trust the capability file and flag the design skill for update.

If no folder exists for the resolved file key, continue without error. The first time the harness works on a file, design-skills/ may be empty for it; Stage 7 will seed it with the first durable observation.

After all six return, synthesize a Session Context. Lead with a one-line BLUF that the designer can read in five seconds; the technical fields support it.

SESSION CONTEXT
Bottom line              : [empty / partial / mature] system on [page name], [N] library matches found, [N] gaps to flag.
Target node              : [name, type, page] or [no URL target, full file]
Local variable collections: [N collections, M variables total]
Remote library variables  : [N from search_design_system includeVariables]
Text styles : [N]   Paint styles : [N]   Effect styles : [N]
Library components       : [N from search_design_system]
File state               : [empty | partial system | mature system]
So what                  : [one sentence on how this state shapes the next move]

File state classification:

• empty -- 0 variable collections, 0 styles
• partial system -- some tokens or styles exist, gaps present
• mature system -- 2+ variable collections with meaningful coverage, text and paint styles present

---

Stage 3: URL Target Resolution

1. Extract node-id from the URL. Hyphens in the URL (node-id=21-173) become colons internally (21:173). Confirm the node's page, name, and type from the get_metadata result.
2. If the node is a page (canvas), the output will be a new frame placed on that page. If it is a frame, the output will be placed alongside it.
3. If the URL has no node-id, surface all top-level frames and ask which page to work on using AskUserQuestion.

Node ID is the only authoritative target reference. Never match by name.

---

Stage 3b: Context Extraction

Scan the message for structured signals and hold them as Project Context:

Category	Signals	Name
Device / platform	"mobile", "iOS", "desktop", width in px	device
Code framework	"React", "Tailwind", "SwiftUI"	framework
Brand / visual	hex codes, "our brand color"	brandColors
Fidelity intent	"rough", "high-fi", "production-ready"	fidelityIntent
Product domain	"fintech", "SaaS", "health"	domain
Screen / component type	named screen, named component	targetType
Source reference	URL to existing design to recreate/translate	sourceRef

---

Stage 4: Capability Selection

Read the task and the Session Context. Mark every capability the task requires, then read all marked files before writing any code.

Capability	Select when the task requires...
figma-read	Source reference provided, recreation/translation task, audit, reading existing tokens or structure
figma-frames	Creating any new frame, screen, section, or layout scaffold
figma-components	Any component instance, library import, component creation, or UI element that may exist in the design system
figma-tokens	Applying, migrating, or creating design system color, spacing, or typography tokens
figma-vectors	Icons, shapes, paths, boolean ops, gradients, image fills, effects, or exports
figma-documentation	Style guide, Code Connect, token export, FigJam diagram, dev handoff artifact
figma-files	New file or new page creation
figma-research	Competitive analysis, market context, PESTLE/SWOT, design rationale grounded in external evidence

Multiple capabilities are the norm, not the exception. A screen recreation with a mature design system typically requires figma-read + figma-frames + figma-components + figma-tokens.

Always read figma-code.md before writing any use_figma script. Its constraints apply universally.

Design-skill loading: Stage 2 Call 6 has already read any file under design-skills/<file-key>/ that matches the resolved file key. If that folder contains components.md with gold-standard anatomy node ids or tokens.md with architecture notes, load the referenced canvas examples via get_design_context + get_screenshot before writing. These examples define what correct output looks like for this specific file.

---

Stage 5: Execution Plan

Before any write call, emit this plan. No SKIP conditions; it fires every time. The plugin hook enforces this at the tool layer: mcp__figma__use_figma write calls are blocked until a valid plan has been emitted in the current session and the upcoming write target is covered by the plan.

Field	Value
Bottom line	[one sentence: what is being built, on which page, against which token set]
So what	[why this plan is the right move for the designer's stated goal]
Task	[one-sentence description]
Target	New frame at rightEdge + 200 on page [name] (node [id]); or editing [specific property] on node [id]
Capabilities	[list of selected capability files]
Component map	[element] to [component key]; or [element] to raw frame: no match (omit if figma-components not selected)
Token sources	[variable collection names to use] (omit if figma-tokens not selected)
Sections	[ordered list of build phases]
Risks surfaced	[token gaps, library drift, contrast warnings; or "none observed"]
Ambiguity	[one question if any execution decision is genuinely unclear; otherwise "none"]

Then emit a machine-readable sentinel block that mirrors the same fields:

<<<EXECUTION_PLAN
Bottom line    : ...
So what        : ...
Task           : ...
Target         : ...
Capabilities   : ...
Component map  : ...
Token sources  : ...
Sections       : ...
Risks surfaced : ...
Ambiguity      : ...
EXECUTION_PLAN>>>

Sentinel rules:

1. The sentinel block is required before any write call.
2. Fields always required: Bottom line, So what, Task, Target, Capabilities, Sections.
3. Component map is required when figma-components appears in Capabilities.
4. Token sources is required when figma-tokens appears in Capabilities.
5. Risks surfaced and Ambiguity must be populated, or explicitly set to "none observed" and "none" respectively.
6. Target or Sections must reference the upcoming write destination: node id, page name, or screen variable name.

The execution plan is visible to the designer before any write. The first two rows must answer "what are you about to do, and why is it the right call" without scrolling. The technical fields below support that judgment but never replace it. If the ambiguity row contains a question, deliver it using AskUserQuestion and wait for the answer before proceeding.

---

Stage 6: Personal Workflow Layer

When a designer states a preference mid-session, offer to save it using AskUserQuestion:

"Want me to save that as a workflow preference so I follow it automatically going forward?"

When the same answer appears twice across separate sessions, offer proactively using AskUserQuestion:

"You have picked [answer] twice now. Want me to save that so I stop asking?"

See figma-personal-workflow.md for how to persist preferences and which sections of each file are safe to edit.

---

Stage 7: Capturing New Knowledge

Every Figma session has the chance to widen the harness. Three kinds of new knowledge can surface, each with a different destination and capture rule.

1. A new Figma API constraint or failure mode.

Something changed what scripts can safely do: a method was renamed, a property started throwing on a node type it used to accept, an async call started returning stale references. This is platform knowledge and belongs in the relevant capability file, usually figma-code.md.

Capture rule: capability files are protected. Propose the new entry to the user via AskUserQuestion before writing, quoting the exact error or behavior observed. Include a minimal reproduction.

2. A new reusable script pattern.

The harness wrote a snippet once and would use it again. If the snippet is more than twenty lines and generalizes beyond the current file, extract it. Destination: scripts/<name>.js with an entry added to scripts/README.md following that contract.

Capture rule: the harness may extract scripts without asking, but must mention it in the response so the user can push back if the extraction was premature. Snippets shorter than twenty lines stay inline.

3. A file-specific or library-specific fact.

A token is named brand/primary/600 not color/primary. A component lives at a non-obvious node. This file's modes are set up in an unusual way. Destination: design-skills/<file-key>/*.md.

Capture rule: the harness writes these without asking, because they are observational, not opinionated. Each entry must include the date observed and the node id or search query that surfaced it. See design-skills/README.md for the format.

Anti-pattern: treating a use_figma script failure as one-off. Every unknown failure mode is a candidate for figma-code.md; every unknown file-specific fact is a candidate for design-skills/. The harness grows through Stage 7 or it does not grow at all.

---

Tool Reference

Every tool this skill calls, plus the rules that apply to every use_figma script, lives in references/tool-reference.md. Read that file once per session, or whenever a tool name appears that you do not immediately recognize.

---

Anti-Patterns

• Running the parallel discovery phase again while edits are in progress.
• Resolving a target node by name instead of node-id.
• Running two use_figma write calls simultaneously.
• Using search_design_system as the only discovery step -- it misses all local assets.
• Running only Call 1 for variable discovery and skipping Call 3 -- remote library variables are invisible to getLocalVariableCollectionsAsync().
• Using get_variable_defs to discover available tokens -- it only returns already-bound tokens.
• Skipping get_screenshot after any write.
• Building an entire screen or component set in one use_figma call.
• Clearing an existing frame's children and rebuilding inside it. A destination URL means "place new content here" -- always as a new frame. Never empty and repurpose an existing one.
• Creating frames as top-level page children intending to reparent them later. appendChild() silently fails when moving nodes across parents, producing orphaned frames. Build directly inside the final wrapper from the start.
• Building UI elements (buttons, chips, nav bars) as raw frames when matching library components exist. The component map in the execution plan must be completed before building.
• Reading node.vectorPaths without error handling on any VECTOR node from an unknown source.
• Selecting only one capability when the task clearly needs several.
• Emitting an execution plan with no ambiguity and then asking clarifying questions anyway -- plan first, then build.