@fprad0/skill-master-mcp 0.0.11 → 1.0.0

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

@@ -1,14 +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"
+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

@@ -1,3 +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>
+<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

@@ -1,28 +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>
+<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

@@ -1,3 +1,3 @@
-SKILL.md: mcp_server
-references: mcp_server
-scripts: mcp_server
+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

@@ -1,260 +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.
+> 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.