@fprad0/skill-master-mcp 0.0.8 → 0.0.10

package/docs/skill-candidates/v0.0.10/figma-generate-library/SKILL.md

@@ -0,0 +1,314 @@
+---
+name: figma-generate-library
+description: "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."
+---
+
+# Design System Builder — Figma MCP Skill
+
+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)
+  0a. Analyze codebase → extract tokens, components, naming conventions
+  0b. Inspect Figma file → pages, variables, components, styles, existing conventions
+  0c. Search subscribed libraries → use search_design_system for reusable assets
+  0d. Lock v1 scope → agree on exact token set + component list before any creation
+  0e. Map code → Figma → resolve conflicts (code and Figma disagree = ask user)
+  ✋ USER CHECKPOINT: present full plan, await explicit approval
+
+Phase 1: FOUNDATIONS (tokens first — always before components)
+  1a. Create variable collections and modes
+  1b. Create primitive variables (raw values, 1 mode)
+  1c. Create semantic variables (aliased to primitives, mode-aware)
+  1d. Set scopes on ALL variables
+  1e. Set code syntax on ALL variables
+  1f. Create effect styles (shadows) and text styles (typography)
+  → Exit criteria: every token from the agreed plan exists, all scopes set, all code syntax set
+  ✋ USER CHECKPOINT: show variable summary, await approval
+
+Phase 2: FILE STRUCTURE (before components)
+  2a. Create page skeleton: Cover → Getting Started → Foundations → --- → Components → --- → Utilities
+  2b. Create foundations documentation pages (color swatches, type specimens, spacing bars)
+  → Exit criteria: all planned pages exist, foundations docs are navigable
+  ✋ USER CHECKPOINT: show page list + screenshot, await approval
+
+Phase 3: COMPONENTS (one at a time — never batch)
+  For EACH component (in dependency order: atoms before molecules):
+    3a. Create dedicated page
+    3b. Build base component with auto-layout + full variable bindings
+    3c. Create all variant combinations (combineAsVariants + grid layout)
+    3d. Add component properties (TEXT, BOOLEAN, INSTANCE_SWAP)
+    3e. Link properties to child nodes
+    3f. Add page documentation (title, description, usage notes)
+    3g. Validate: get_metadata (structure) + get_screenshot (visual)
+    3h. Optional: lightweight Code Connect mapping while context is fresh
+    → Exit criteria: variant count correct, all bindings verified, screenshot looks right
+    ✋ USER CHECKPOINT per component: show screenshot, await approval before next component
+
+Phase 4: INTEGRATION + QA (final pass)
+  4a. Finalize all Code Connect mappings
+  4b. Accessibility audit (contrast, min touch targets, focus visibility)
+  4c. Naming audit (no duplicates, no unnamed nodes, consistent casing)
+  4d. Unresolved bindings audit (no hardcoded fills/strokes remaining)
+  4e. Final review screenshots of every page
+  ✋ USER CHECKPOINT: complete sign-off
+```
+
+---
+
+## 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).
+
+| 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:
+```javascript
+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:
+```json
+{
+  "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.
+
+| After | Required artifacts | Ask |
+|-------|-------------------|-----|
+| Discovery + scope lock | Token list, component list, gap analysis | "Here's my plan. Approve before I create anything?" |
+| Foundations | Variable summary (N collections, M vars, K modes), style list | "All tokens created. Review before file structure?" |
+| File structure | Page list + screenshot | "Pages set up. Review before components?" |
+| Each component | get_screenshot of component page | "Here's [Component] with N variants. Correct?" |
+| Each conflict (code ≠ Figma) | Show both versions | "Code says X, Figma has Y. Which wins?" |
+| Final QA | Per-page screenshots + audit report | "Complete. Sign off?" |
+
+**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](references/naming-conventions.md)
+
+---
+
+## 8. Token Architecture
+
+| 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](references/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](references/discovery-phase.md) | 0 | **Required** | Starting any build — codebase analysis + Figma inspection |
+| [token-creation.md](references/token-creation.md) | 1 | **Required** | Creating variables, collections, modes, styles |
+| [documentation-creation.md](references/documentation-creation.md) | 2 | Required | Creating cover page, foundations docs, swatches |
+| [component-creation.md](references/component-creation.md) | 3 | **Required** | Creating any component or variant |
+| [code-connect-setup.md](references/code-connect-setup.md) | 3–4 | Required | Setting up Code Connect or variable code syntax |
+| [naming-conventions.md](references/naming-conventions.md) | Any | Optional | Naming anything — variables, pages, variants, styles |
+| [error-recovery.md](references/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](scripts/inspectFileStructure.js) | Discover all pages, components, variables, styles; returns full inventory |
+| [createVariableCollection.js](scripts/createVariableCollection.js) | Create a named collection with modes; returns `{collectionId, modeIds}` |
+| [createSemanticTokens.js](scripts/createSemanticTokens.js) | Create aliased semantic variables from a token map |
+| [createComponentWithVariants.js](scripts/createComponentWithVariants.js) | Build a component set from a variant matrix; handles grid layout |
+| [bindVariablesToComponent.js](scripts/bindVariablesToComponent.js) | Bind design tokens to all component visual properties |
+| [createDocumentationPage.js](scripts/createDocumentationPage.js) | Create a page with title + description + section structure |
+| [validateCreation.js](scripts/validateCreation.js) | Verify created nodes match expected counts, names, structure |
+| [cleanupOrphans.js](scripts/cleanupOrphans.js) | Remove orphaned nodes by name convention or state ledger IDs |
+| [rehydrateState.js](scripts/rehydrateState.js) | Scan file for all pages, components, variables by name; returns full `{key → nodeId}` map for state reconstruction |

package/docs/skill-candidates/v0.0.10/figma-generate-library/agents/openai.yaml

@@ -0,0 +1,14 @@
+interface:
+  display_name: "Generate Figma Library"
+  short_description: "Build or update a design system library in Figma"
+  icon_small: "./assets/figma-small.svg"
+  icon_large: "./assets/figma.png"
+  default_prompt: "Use $figma-generate-library to build or update a Figma design system library from the codebase, including tokens, components, and documentation."
+
+dependencies:
+  tools:
+    - type: "mcp"
+      value: "figma"
+      description: "Figma MCP server"
+      transport: "streamable_http"
+      url: "https://mcp.figma.com/mcp"

package/docs/skill-candidates/v0.0.10/figma-generate-library/assets/figma-small.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" viewBox="0 0 16 16">
+  <path fill="currentColor" fill-rule="evenodd" d="M4.994 5.986a2.014 2.014 0 1 0 0 4.028h2.069V5.986H4.994Zm5.063-.98h.055a2.014 2.014 0 1 0 0-4.026h-2.07v4.027h2.015Zm1.697.49A2.994 2.994 0 0 0 10.112 0H4.994a2.994 2.994 0 0 0-1.642 5.498A2.99 2.99 0 0 0 2 8a2.99 2.99 0 0 0 1.352 2.503A2.99 2.99 0 0 0 2 13.007C2 14.663 3.358 16 5.008 16c1.665 0 3.035-1.349 3.035-3.02v-2.765a2.984 2.984 0 0 0 2.014.778h.055a2.994 2.994 0 0 0 1.642-5.496Zm-1.642.49h-.055a2.014 2.014 0 1 0 0 4.028h.055a2.014 2.014 0 1 0 0-4.028Zm-7.132 7.02c0-1.111.902-2.013 2.014-2.013h2.069v1.987c0 1.123-.924 2.04-2.055 2.04a2.026 2.026 0 0 1-2.028-2.013Zm4.083-8H4.994a2.014 2.014 0 1 1 0-4.026h2.069v4.027Z" clip-rule="evenodd"/>
+</svg>

package/docs/skill-candidates/v0.0.10/figma-generate-library/assets/icon.svg

@@ -0,0 +1,28 @@
+<svg
+  width="400"
+  height="400"
+  viewBox="0 0 400 400"
+  fill="none"
+  xmlns="http://www.w3.org/2000/svg"
+>
+  <path
+    d="M97.5 302.5C97.5 274.195 120.445 251.25 148.75 251.25H200V302.5C200 330.805 177.055 353.75 148.75 353.75C120.445 353.75 97.5 330.805 97.5 302.5Z"
+    fill="#0ACF83"
+  />
+  <path
+    d="M200 200C200 171.696 222.945 148.75 251.25 148.75C279.554 148.75 302.5 171.695 302.5 200C302.5 228.305 279.554 251.25 251.25 251.25C222.945 251.25 200 228.304 200 200Z"
+    fill="#1ABCFE"
+  />
+  <path
+    d="M97.5 200C97.5 228.305 120.445 251.25 148.75 251.25H200V148.75H148.75C120.445 148.75 97.5 171.695 97.5 200Z"
+    fill="#A259FF"
+  />
+  <path
+    d="M200 46.25V148.75H251.25C279.555 148.75 302.5 125.805 302.5 97.5C302.5 69.1954 279.555 46.25 251.25 46.25H200Z"
+    fill="#FF7262"
+  />
+  <path
+    d="M97.5 97.5C97.5 125.805 120.445 148.75 148.75 148.75H200V46.25L148.75 46.25C120.445 46.25 97.5 69.1954 97.5 97.5Z"
+    fill="#F24E1E"
+  />
+</svg>

package/docs/skill-candidates/v0.0.10/figma-generate-library/maintainers.yml

@@ -0,0 +1,3 @@
+SKILL.md: mcp_server
+references: mcp_server
+scripts: mcp_server

package/docs/skill-candidates/v0.0.10/figma-generate-library/references/code-connect-setup.md

@@ -0,0 +1,260 @@
+> Part of the [figma-generate-library skill](../SKILL.md).
+
+# Code Connect Setup Reference
+
+This reference covers all Code Connect tooling available to the figma-generate-library agent: the `add_code_connect_map` tool, `get_code_connect_map` for verification, `send_code_connect_mappings` for bulk application, variable code syntax, framework labels, and the decision of when to map per-component vs. in a final pass.
+
+---
+
+## 1. What Code Connect Does
+
+Code Connect links a Figma component node to its code implementation so that:
+
+- **Dev Mode** shows a real code snippet (from your codebase) instead of an auto-generated approximation when a developer inspects a component.
+- **MCP `get_design_context`** returns `componentName`, `source`, and a rendered snippet alongside design tokens, enabling accurate AI-assisted code generation.
+- **`search_design_system`** can return code references alongside Figma component metadata.
+
+---
+
+## 2. The Three MCP Tools
+
+### 2a. add_code_connect_map — single mapping
+
+Maps one Figma node to one code component.
+
+**Parameters:**
+
+| Parameter | Type | Required | Notes |
+|-----------|------|----------|-------|
+| `nodeId` | string | Yes (remote) / Optional (desktop) | Format `123:456`. Must be a published component or component set. |
+| `fileKey` | string | Yes (remote) | The Figma file key. |
+| `source` | string | Yes | Path in the codebase (e.g. `src/components/Button.tsx`) or a URL. |
+| `componentName` | string | Yes | The code component name (e.g. `Button`). |
+| `label` | enum | Yes | Framework label — see Section 4 for valid values. |
+| `template` | string | Optional | Executable JS template code. Providing this creates a **figmadoc** (template) mapping instead of a simple **component_browser** mapping. Requires the `pixie_mcp_enable_writing_code_connect_templates` feature flag. |
+| `templateDataJson` | string | Optional | JSON string with optional fields: `isParserless`, `imports`, `nestable`, `props`. |
+
+**Two mapping tiers:**
+
+1. **Simple mapping (component_browser):** Only `source`, `componentName`, and `label` provided. Associates the Figma component with a code path + name. Dev Mode generates a basic JSX snippet from Figma prop names. This is the default — use it first.
+
+2. **Template mapping (figmadoc):** `template` is also provided. The template is executed in a sandboxed QuickJS environment and dynamically renders the snippet based on the actual instance's property values. Use this when precise prop-level Code Connect is required by the user.
+
+**Common error codes:**
+
+| Error | Meaning | Fix |
+|-------|---------|-----|
+| `CODE_CONNECT_MAPPING_ALREADY_EXISTS` | Component is already mapped | Disconnect existing mapping in Figma UI first |
+| `CODE_CONNECT_ASSET_NOT_FOUND` | Published component not found | Ensure the component is published to the library |
+| `CODE_CONNECT_INSUFFICIENT_PERMISSIONS` | No edit access | Request edit permission on the file |
+| `CODE_CONNECT_NO_LIBRARY_FOUND` | File is not published as a library | Publish the file as a Figma library first |
+
+**Usage example:**
+
+```
+Tool: add_code_connect_map
+Args: {
+  nodeId: "123:456",
+  fileKey: "abc123",
+  source: "src/components/Button.tsx",
+  componentName: "Button",
+  label: "React"
+}
+```
+
+---
+
+### 2b. get_code_connect_map — verification
+
+Retrieves the current Code Connect mapping for a node. Use this immediately after `add_code_connect_map` to confirm the mapping was saved, and before `send_code_connect_mappings` to audit existing state.
+
+**Parameters:**
+
+| Parameter | Type | Required | Notes |
+|-----------|------|----------|-------|
+| `nodeId` | string | Optional | The node to check. Omit to get all mappings in the file. |
+| `fileKey` | string | Yes (remote) | The Figma file key. |
+| `codeConnectLabel` | string | Optional | Filter results to a specific framework label. |
+
+**Returns:** A map of `nodeId -> { componentName, source, label, snippet, snippetImports }`.
+
+**How to verify:**
+
+```
+1. Call add_code_connect_map with the node.
+2. Immediately call get_code_connect_map(nodeId, fileKey).
+3. Confirm the returned object has the expected componentName and source.
+4. If the mapping is missing, check for error codes from step 1.
+```
+
+---
+
+### 2c. send_code_connect_mappings — bulk application
+
+Applies multiple Code Connect mappings in one call. Use after `get_code_connect_suggestions` returns a batch of unmapped components, or when doing a final-pass bulk mapping at the end of Phase 4.
+
+**Parameters:**
+
+| Parameter | Type | Required | Notes |
+|-----------|------|----------|-------|
+| `nodeId` | string | Optional | Context node for design fallback if mappings array is empty. |
+| `fileKey` | string | Yes (remote) | The Figma file key. |
+| `mappings` | array | Yes | Array of mapping objects. |
+
+**Each mapping object:**
+
+| Field | Type | Required | Notes |
+|-------|------|----------|-------|
+| `nodeId` | string | Yes | The Figma node identifier. |
+| `componentName` | string | Yes | Code component name. |
+| `source` | string | Yes | Path in the codebase. |
+| `label` | enum | Yes | Framework label. |
+| `template` | string | Optional | JS template code for figmadoc mapping. |
+| `templateDataJson` | string | Optional | JSON template metadata. |
+
+**Behavior:**
+
+- All mappings are processed in parallel via POSTs to the backend.
+- If any mapping fails, errors are reported per mapping — the rest succeed.
+- On full success, `get_design_context` is called for the nodes and fresh design context is returned.
+
+**Bulk workflow:**
+
+```
+1. Collect all {nodeId, componentName, source, label} pairs.
+2. Call send_code_connect_mappings({ fileKey, mappings: [...all pairs...] }).
+3. Review reported errors and call add_code_connect_map individually for any failures.
+4. Call get_code_connect_map on a sample of nodes to spot-check.
+```
+
+---
+
+## 3. Variable Code Syntax (Token Round-Tripping)
+
+Setting code syntax on variables creates the bidirectional link between Figma tokens and the codebase token system. This is what enables Dev Mode to show `var(--color-bg-primary)` next to a design value instead of a raw hex.
+
+**The three platforms:**
+
+```javascript
+// In use_figma:
+variable.setVariableCodeSyntax('WEB', 'var(--color-bg-primary)');
+variable.setVariableCodeSyntax('ANDROID', 'Theme.colorBgPrimary');
+variable.setVariableCodeSyntax('iOS', 'Color.bgPrimary');
+```
+
+- `WEB` — used for CSS custom properties, design token JSON, and any web framework.
+- `ANDROID` — used for Jetpack Compose theme references and Android resource names.
+- `iOS` — used for SwiftUI Color extensions and UIKit color methods.
+
+**Derivation rules (in priority order):**
+
+1. **Best:** Use the exact token name from the codebase. Search the codebase for CSS custom properties (`--`), Swift color extensions, or Kotlin theme references and use those exact strings.
+2. **Good:** Derive from the Figma variable name with a consistent transformation: replace `/` and spaces with `-`, prefix with `var(--` and suffix with `)`.
+   - Example: `color/bg/primary` → `var(--color-bg-primary)`
+3. **Avoid:** Guessing or inventing names that don't exist in the codebase.
+
+**Consistency rule:** The transformation must be uniform. If you use `var(--color-bg-primary)` for one variable, use the same `var(--{path-with-hyphens})` pattern for all variables in that collection.
+
+**WEB syntax bulk example:**
+
+```javascript
+// In use_figma — set WEB code syntax on all variables in a collection
+const collections = figma.variables.getLocalVariableCollections();
+for (const coll of collections) {
+  if (coll.name !== 'Color') continue;
+  for (const varId of coll.variableIds) {
+    const v = figma.variables.getVariableById(varId);
+    if (!v) continue;
+    // Derive: "color/bg/primary" → "var(--color-bg-primary)"
+    const cssName = 'var(--' + v.name.toLowerCase().replace(/\//g, '-').replace(/\s+/g, '-') + ')';
+    v.setVariableCodeSyntax('WEB', cssName);
+  }
+}
+```
+
+---
+
+## 4. Framework Labels
+
+The following labels are valid for all Code Connect MCP operations. Use the label that matches your codebase framework.
+
+| Label | Use for |
+|-------|---------|
+| `React` | React / JSX / TSX components |
+| `Web Components` | Native Web Components, Lit, FAST |
+| `Vue` | Vue 2 and Vue 3 SFCs |
+| `Svelte` | Svelte components |
+| `Storybook` | Storybook stories with Code Connect integration |
+| `Javascript` | Plain JavaScript, framework-agnostic |
+| `Swift` | Swift / UIKit |
+| `Swift UIKit` | UIKit specifically |
+| `Objective-C UIKit` | Objective-C with UIKit |
+| `SwiftUI` | SwiftUI view components |
+| `Compose` | Jetpack Compose (Android) |
+| `Java` | Java Android components |
+| `Kotlin` | Kotlin Android (non-Compose) |
+| `Android XML Layout` | Android XML layout files |
+| `Flutter` | Flutter / Dart widgets |
+| `Markdown` | Documentation or MDX components |
+
+**HTML note:** The label `HTML` is used by the Code Connect CLI's HTML parser (for Angular, Vue, and Web Components without a framework-specific parser), but the MCP tools use `Web Components` or `Vue` directly. Check the codebase framework before selecting.
+
+---
+
+## 5. Per-Component vs. Final-Pass Strategy
+
+### Per-component (preferred for new builds)
+
+Map Code Connect immediately after creating a component, while the context is fresh (Phase 3, step 3h in the SKILL.md workflow):
+
+**Advantages:**
+- The node ID is already in hand from the creation script.
+- You know exactly which code component this Figma component corresponds to (you just designed it to match).
+- Errors surface early, before building dependent components.
+
+**When to use:** Any time you create a Figma component that has a clear 1:1 match with an existing code component.
+
+### Final pass (for bulk mapping at Phase 4)
+
+Collect all unmapped components and map them in one `send_code_connect_mappings` call:
+
+**Advantages:**
+- One bulk call instead of N individual calls.
+- Can use `get_code_connect_suggestions` to discover unmapped components automatically.
+- Better for importing existing Figma files where you didn't control creation.
+
+**When to use:** Retrofitting Code Connect onto an existing file, or when the codebase mapping requires research that is better done after all components are created.
+
+### Hybrid (recommended for large systems)
+
+- Map atoms (Button, Input, Badge, Avatar) **per-component** during Phase 3.
+- Map molecules and organisms in a **final pass** during Phase 4 after all atoms are mapped, since molecule snippets reference atom Code Connect IDs.
+
+---
+
+## 6. Verification in Dev Mode
+
+After mapping:
+
+1. Open the Figma file in the browser or desktop app.
+2. Switch to Dev Mode (the `</>` icon in the toolbar).
+3. Select a component instance (not the main component — an instance placed on a page).
+4. In the Inspect panel, the code snippet should show the Code Connect output instead of auto-generated code.
+5. If the snippet is missing or shows `[auto-generated]`, run `get_code_connect_map` via MCP to confirm the mapping exists, then check that the component is published.
+
+**Via MCP (faster during agent workflows):**
+
+```
+get_code_connect_map(nodeId: "<the component set node ID>", fileKey: "<file key>")
+```
+
+The response should include `componentName`, `source`, `label`, and a non-empty `snippet`.
+
+---
+
+## 7. Important Constraints
+
+- **Published components only:** `add_code_connect_map` requires the component to be published to a library. If the file is not yet published, the mapping will fail with `CODE_CONNECT_NO_LIBRARY_FOUND`.
+- **One mapping per label per node:** A node can have multiple mappings (one per framework label), but only one per label. Attempting to add a second React mapping to the same node returns `CODE_CONNECT_MAPPING_ALREADY_EXISTS`.
+- **Template mappings are gated:** The `template` parameter requires the `pixie_mcp_enable_writing_code_connect_templates` feature flag. Use simple mappings unless the user explicitly requests template-level Code Connect.
+- **Start simple, escalate:** Always begin with simple mappings (`source` + `componentName` + `label`). Add `template` only if the user needs precise prop-level snippet rendering.