[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7CGVZ4YBENDKSFF4CFJE850":3,"skill-same:01M7CGVZ4YBENDKSFF4CFJE850":55},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":14,"repositoryHtmlUrl":27,"repositoryHomepageUrl":6,"ownerHtmlUrl":28,"ownerBlogUrl":29,"ownerDescription":6,"updatedAt":30,"install":31,"resources":44},"01M7CGVZ4YBENDKSFF4CFJE850","figma-code-connect",null,"Creates and maintains Figma Code Connect template files that map Figma components to code snippets. Use when the user mentions Code Connect, Figma component mapping, design-to-code translation, or asks to create\u002Fupdate .figma.ts or .figma.js files.","rossboyd\u002Fquickque","rossboyd","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F3195729?v=4","01M7CG99NTNRFV0TWTZX9JY9CQ","rbyd","01M7CG99PH4WEP5P45VTBNPDB0",0,"MIT","https:\u002F\u002Fgithub.com\u002Frossboyd\u002Fquickque\u002Fblob\u002Fmain\u002F.codex\u002F.tmp\u002Fplugins\u002Fplugins\u002Ffigma\u002Fskills\u002Ffigma-code-connect\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: figma-code-connect\ndescription: Creates and maintains Figma Code Connect template files that map Figma components to code snippets. Use when the user mentions Code Connect, Figma component mapping, design-to-code translation, or asks to create\u002Fupdate .figma.ts or .figma.js files.\ndisable-model-invocation: false\n---\n\n# Code Connect\n\n## Overview\n\nCreate Code Connect template files (`.figma.ts`) that map Figma components to code snippets. Given a Figma URL, follow the steps below to create a template.\n\n> **You write `.figma.ts` template files ONLY — never `.figma.tsx`.** This skill produces *parserless templates*: a `.figma.ts` file whose default export uses a `` figma.code`...` `` tagged template. Do **NOT** write a `.figma.tsx` file and do **NOT** use `figma.connect()` — that is the separate **parser-based** Code Connect format (published a different way) and is the **wrong artifact** for this skill; output written as `.figma.tsx` is rejected outright. If a `.figma.tsx` already exists for a component, leave it untouched and add your `.figma.ts` template alongside it. A capable model may be tempted to reach for the more familiar `.figma.tsx` \u002F `figma.connect()` pattern from memory — resist it; here the correct output is **always** `.figma.ts` + `figma.code`.\n\n## Prerequisites\n\n- **Figma MCP server must be connected** — verify that Figma MCP tools (e.g., `get_code_connect_suggestions`) are available before proceeding. If not, guide the user to enable the Figma MCP server and restart their MCP client.\n- **Components must be published** — Code Connect only works with components published to a Figma team library. If a component is not published, inform the user and stop.\n- **Organization or Enterprise plan required** — Code Connect is not available on Free or Professional plans.\n- **URL must include `node-id`** — the Figma URL must contain the `node-id` query parameter.\n- **TypeScript types** — for editor autocomplete and type checking in `.figma.ts` files `@figma\u002Fcode-connect\u002Ffigma-types` must be added to `types` in `tsconfig.json`:\n  ```json\n  {\n    \"compilerOptions\": {\n      \"types\": [\"@figma\u002Fcode-connect\u002Ffigma-types\"]\n    }\n  }\n  ```\n\n## Step 1: Parse the Figma URL\n\nExtract `fileKey` and `nodeId` from the URL:\n\n| URL Format | fileKey | nodeId |\n|---|---|---|\n| `figma.com\u002Fdesign\u002F:fileKey\u002F:name?node-id=X-Y` | `:fileKey` | `X-Y` → `X:Y` |\n| `figma.com\u002Ffile\u002F:fileKey\u002F:name?node-id=X-Y` | `:fileKey` | `X-Y` → `X:Y` |\n| `figma.com\u002Fdesign\u002F:fileKey\u002Fbranch\u002F:branchKey\u002F:name` | use `:branchKey` | from `node-id` param |\n\nAlways convert `nodeId` hyphens to colons: `1234-5678` → `1234:5678`.\n\n**Worked example:**\n\nGiven: `https:\u002F\u002Fwww.figma.com\u002Fdesign\u002FQiEF6w564ggoW8ftcLvdcu\u002FMyDesignSystem?node-id=4185-3778`\n- `fileKey` = `QiEF6w564ggoW8ftcLvdcu`\n- `nodeId` = `4185-3778` → `4185:3778`\n\n## Step 2: Discover Unmapped Components\n\nThe user may provide a URL pointing to a frame, instance, or variant — not necessarily a component set or standalone component. Call the MCP tool `get_code_connect_suggestions` with:\n- `fileKey` — from Step 1\n- `nodeId` — from Step 1 (colons format)\n- `excludeMappingPrompt` — `true` (returns a lightweight list of unmapped components)\n\nThis tool identifies published components in the selection that don't yet have Code Connect mappings.\n\n**Handle the response:**\n\n- **\"No published components found in this selection\"** — the node contains no published components. Inform the user they need to publish the component to a team library in Figma first, then stop.\n- **\"All component instances in this selection are already connected to code via Code Connect\"** — everything is already mapped. Inform the user and stop.\n- **Normal response with component list** — extract the `mainComponentNodeId` for each returned component. Use these resolved node IDs (not the original from the URL) for all subsequent steps. If multiple components are returned (e.g. the user selected a frame containing several different component instances), repeat Steps 3–6 for each one.\n\n## Step 3: Fetch Component Properties\n\nCall the MCP tool `get_context_for_code_connect` with:\n- `fileKey` — from Step 1\n- `nodeId` — the resolved `mainComponentNodeId` from Step 2\n- `clientFrameworks` — determine from `figma.config.json` `parser` field (e.g. `\"react\"` → `[\"react\"]`)\n- `clientLanguages` — infer from project file extensions (e.g. TypeScript project → `[\"typescript\"]`, JavaScript → `[\"javascript\"]`)\n\nFor multiple components, call the tool once per node ID.\n\nThe response contains the Figma component's **property definitions** — note each property's name and type:\n- **TEXT** — text content (labels, titles, placeholders)\n- **BOOLEAN** — toggles (show\u002Fhide icon, disabled state)\n- **VARIANT** — enum options (size, variant, state)\n- **INSTANCE_SWAP** — swappable nested instances tied to a specific component (icon, avatar)\n- **SLOT** — flexible content regions (freeform layout, mixed children); use `getSlot()` in templates (not the same as INSTANCE_SWAP)\n\nSave this property list — you will use it in Step 5 to write the template.\n\n## Step 4: Identify the Code Component\n\nIf the user did not specify which code component to connect:\n\n1. Check `figma.config.json` for `paths` and `importPaths` to find where components live\n2. Search the codebase for a component matching the Figma component name. Check common directories (`src\u002Fcomponents\u002F`, `components\u002F`, `lib\u002Fui\u002F`, `app\u002Fcomponents\u002F`) if `figma.config.json` doesn't specify paths\n3. Read candidate files and compare their props interface against the Figma properties from Step 3 — look for matching variant types, size options, boolean flags, and slot props\n4. If multiple candidates match, pick the one with the closest prop-interface match and explain your reasoning to the user\n5. If no match is found, show the 2 closest candidates and ask the user to confirm or provide the correct path\n\n**Confirm with the user** before proceeding to Step 5. Present the match: which code component you found, where it lives, and why it matches (prop correspondence, naming, purpose).\n\nRead `figma.config.json` for import path aliases — the `importPaths` section maps glob patterns to import specifiers, and the `paths` section maps those specifiers to directories.\n\nRead the code component's source to understand its props interface — this informs how to map Figma properties to code props in Step 5.\n\n## Step 5: Create the Template File (.figma.ts)\n\n### File location\n\nPlace the file alongside existing Code Connect files. Check `figma.config.json` `include` patterns for the correct directory. **Name it `ComponentName.figma.ts` — never `ComponentName.figma.tsx`.** The `.figma.tsx` extension is the parser-based format; do not create one or modify an existing one.\n\n### Template structure\n\nEvery template file follows this structure:\n\n```ts\n\u002F\u002F url=https:\u002F\u002Fwww.figma.com\u002Ffile\u002F{fileKey}\u002F{fileName}?node-id={nodeId}\n\u002F\u002F source={path to code component from Step 4}\n\u002F\u002F component={code component name from Step 4}\nimport figma from 'figma'\nconst instance = figma.selectedInstance\n\n\u002F\u002F Extract properties from the Figma component (see property mapping below)\n\u002F\u002F ...\n\nexport default {\n  example: figma.code`\u003CComponent ... \u002F>`,       \u002F\u002F Required: code snippet\n  imports: ['import { Component } from \"...\"'], \u002F\u002F Optional: import statements\n  id: 'component-name',                         \u002F\u002F Required: unique identifier\n  metadata: {                                    \u002F\u002F Optional\n    nestable: true,                              \u002F\u002F true = inline in parent, false = show as pill\n    props: {}                                    \u002F\u002F data accessible to parent templates\n  }\n}\n```\n\n### Property mapping\n\nUse the property list from Step 3 to extract values. For each Figma property type, use the corresponding method:\n\n| Figma Property Type | Template Method | When to Use |\n|---|---|---|\n| TEXT | `instance.getString('Name')` | Labels, titles, placeholder text |\n| BOOLEAN | `instance.getBoolean('Name', { true: ..., false: ... })` | Toggle visibility, conditional props |\n| VARIANT | `instance.getEnum('Name', { 'FigmaVal': 'codeVal' })` | Size, variant, state enums |\n| INSTANCE_SWAP | `instance.getInstanceSwap('Name')` | Swapped instance for a fixed component slot (then `hasCodeConnect()` \u002F `executeTemplate()`) - do not confuse with the SLOT property below |\n| SLOT | `instance.getSlot('Name')` | Freeform slot content only when the Figma property type is **SLOT** \n| (child layer) | `instance.findInstance('LayerName')` | Named child instances without a property |\n| (text layer) | `instance.findText('LayerName')` → `.textContent` | Text content from named layers |\n\n**TEXT** — get the string value directly:\n```ts\nconst label = instance.getString('Label')\n```\n\n**VARIANT** — map Figma enum values to code values:\n```ts\nconst variant = instance.getEnum('Variant', {\n  'Primary': 'primary',\n  'Secondary': 'secondary',\n})\n\nconst size = instance.getEnum('Size', {\n  'Small': 'sm',\n  'Medium': 'md',\n  'Large': 'lg',\n})\n```\n\n**BOOLEAN** — simple boolean or mapped to values:\n```ts\n\u002F\u002F Simple boolean\nconst disabled = instance.getBoolean('Disabled')\n\n\u002F\u002F Mapped to code values (e.g. when the code prop is an enum, not a boolean)\nconst size = instance.getBoolean('Show Label', { true: 'large', false: 'small' })\n```\n\n**Map Figma properties to code props where there's a valid correspondence.** Figma properties and code props don't always line up 1:1 — some Figma properties map directly (by name, or via the API methods above), others have no code equivalent. Where a mapping exists, use it; where none fits, omit the Figma property rather than invent a code prop. Never emit an attribute whose name doesn't appear in the code component's `Props` interface.\n\n### Exhaustive variant handling\n\nWhen a VARIANT property has multiple possible values, the `getEnum` mapping **must list every value** returned by `get_context_for_code_connect`. Don't omit values — an unmapped value silently returns `undefined`, producing broken output.\n\n```ts\n\u002F\u002F WRONG — omits 'Warning', which will render as undefined\nconst status = instance.getEnum('Status', {\n  'Success': 'success',\n  'Error': 'error',\n})\n\n\u002F\u002F CORRECT — every value is mapped\nconst status = instance.getEnum('Status', {\n  'Success': 'success',\n  'Error': 'error',\n  'Warning': 'warning',\n  'Info': 'info',\n})\n```\n\nWhen **two or more VARIANT properties combine** to produce different code output, generate exhaustive conditional branches. For example, 2 variants × 2 values = 4 branches:\n\n```ts\nconst type = instance.getEnum('Type', { 'Filled': 'filled', 'Outlined': 'outlined' })\nconst status = instance.getEnum('Status', { 'Success': 'success', 'Error': 'error' })\n\nlet colorClass\nif (type === 'filled' && status === 'success') {\n  colorClass = 'bg-green-500 text-white'\n} else if (type === 'filled' && status === 'error') {\n  colorClass = 'bg-red-500 text-white'\n} else if (type === 'outlined' && status === 'success') {\n  colorClass = 'bg-transparent border-green-500'\n} else if (type === 'outlined' && status === 'error') {\n  colorClass = 'bg-transparent border-red-500'\n}\n```\n\nIf the combinations produce **repetitive** output (e.g., `Size` doesn't change the snippet structure — it's just passed through as a prop), a single `getEnum` mapping per variant is sufficient — no need for cross-product branches.\n\n**INSTANCE_SWAP** — access swappable component instances:\n```ts\nconst icon = instance.getInstanceSwap('Icon')\nlet iconCode\nif (icon && icon.type === 'INSTANCE') {\n  iconCode = icon.executeTemplate().example\n}\n```\n\n**SLOT** — `getSlot(propName)` is only valid when the Figma component property reported in Step 3 has type **`SLOT`**. Do not use `getSlot()` for **INSTANCE_SWAP** properties (those use `getInstanceSwap()`). Slots are explicit “content regions” in the component definition, not generic nested instances.\n\n- **Signature:** `getSlot(propName: string): ResultSection[] | undefined`\n```ts\n\u002F\u002F Figma property \"Content\" must be type SLOT in component properties\nconst content = instance.getSlot('Content')\n\nexport default {\n  example: figma.code`\u003CCard>${content}\u003C\u002FCard>`,\n  \u002F\u002F ...\n}\n```\n\n### Interpolation in tagged templates\n\nWhen interpolating values in tagged templates, use the correct wrapping:\n- **String values** (`getString`, `getEnum`, `textContent`): wrap in quotes → `variant=\"${variant}\"`\n- **Instance\u002Fsection values** (`executeTemplate().example`): wrap in braces → `icon={${iconCode}}`\n- **Slot sections** (`getSlot()` result — `ResultSection[] | undefined`): interpolate directly inside `` figma.code`...` `` (same shape as nested snippet sections), e.g. `` figma.code`\u003CSelect>${content}\u003C\u002FSelect>` `` — do not treat as a plain string\n- **Boolean bare props**: use conditional → `${disabled ? 'disabled' : ''}`\n\n### Finding descendant layers\n\nWhen you need to access children that aren't exposed as component properties:\n\n| Method | Use when |\n|---|---|\n| `instance.getInstanceSwap('PropName')` | Figma property type is **INSTANCE_SWAP** (fixed swapped instance) |\n| `instance.getSlot('PropName')` | Figma property type is **SLOT** (freeform content region) |\n| `instance.findInstance('LayerName')` | You know the child layer name (no component property) |\n| `instance.findText('LayerName')` → `.textContent` | You need text content from a named text layer |\n| `instance.findConnectedInstance('id')` | You know the child's Code Connect `id` |\n| `instance.findConnectedInstances(fn)` | You need multiple connected children matching a filter |\n| `instance.findLayers(fn)` | You need any layers (text + instances) matching a filter |\n\n### Nested configurable instances\n\nA component may contain child instances that are **not exposed as component properties** (no INSTANCE_SWAP) but are still **independently configurable** — they have their own variants, properties, or swap slots. These must be resolved dynamically, not hardcoded.\n\n1. **Check whether the child already has a Code Connect template** — use `get_code_connect_suggestions` or check existing `.figma.ts` files in the project.\n2. **If no template exists, create one** for the child so it renders correctly both standalone and when nested.\n3. **Reference the child from the parent** using `findInstance()` or `findConnectedInstance()`, then call `executeTemplate()`.\n\n```ts\n\u002F\u002F Parent template — the Badge child isn't a prop, but it's configurable\nconst badge = instance.findInstance('Status Badge')\nlet badgeCode\nif (badge && badge.type === 'INSTANCE') {\n  badgeCode = badge.executeTemplate().example\n}\n\nexport default {\n  example: figma.code`\u003CCard>${badgeCode}\u003C\u002FCard>`,\n  \u002F\u002F ...\n}\n```\n\nThis applies to icons, badges, labels, and any other nested instance that is configurable by itself — always connect them and render dynamically, never hardcode their content.\n\n### Nested component example\n\nFor multi-level nested components or metadata prop passing between templates, see [advanced-patterns.md](references\u002Fadvanced-patterns.md).\n\n```ts\nconst icon = instance.getInstanceSwap('Icon')\nlet iconSnippet\nif (icon && icon.type === 'INSTANCE') {\n  iconSnippet = icon.executeTemplate().example\n}\n\nexport default {\n  example: figma.code`\u003CButton ${iconSnippet ? figma.code`icon={${iconSnippet}}` : ''}>${label}\u003C\u002FButton>`,\n  \u002F\u002F ...\n}\n```\n\n### Conditional props\n\n```ts\nconst variant = instance.getEnum('Variant', { 'Primary': 'primary', 'Secondary': 'secondary' })\nconst disabled = instance.getBoolean('Disabled')\n\nexport default {\n  example: figma.code`\n    \u003CButton\n      variant=\"${variant}\"\n      ${disabled ? 'disabled' : ''}\n    >\n      ${label}\n    \u003C\u002FButton>\n  `,\n  \u002F\u002F ...\n}\n```\n\n## Step 6: Validate\n\nRead back the `.figma.ts` file and review it against the following:\n\n- **Correct file type & format (check this FIRST)** — the file is `ComponentName.figma.ts` (NOT `.figma.tsx`), and its default export is a parserless template using a `` figma.code`...` `` tagged template. It must NOT use `figma.connect()` (the parser-based format). If you wrote `.figma.tsx` or `figma.connect()`, discard it and rewrite as a `.figma.ts` `figma.code` template.\n- **Property coverage** — every Figma property from Step 3 should be accounted for in the template. Flag any that are missing and ask the user if they were intentionally omitted.\n- **Valid, correctly typed code** — all emitted code must be valid and correctly typed against the code component's `Props` interface. Never make up component properties — if a Figma property has no corresponding code prop, omit it rather than invent one.\n- **No hardcoded children** — verify that every INSTANCE_SWAP property and child component slot uses the dynamic APIs (`getInstanceSwap()`, `findInstance()`, `findConnectedInstance()`, etc.) with `executeTemplate()`. No slot should contain hardcoded component content.\n- **Rules and Pitfalls** — check for the common mistakes listed below (string concatenation of template results, unnecessary `hasCodeConnect()` guards, missing `type === 'INSTANCE'` checks, etc.)\n- **Interpolation wrapping** — strings (`getString`, `getEnum`, `textContent`) wrapped in quotes, instance\u002Fsection values (`executeTemplate().example`) wrapped in braces, slot sections (`getSlot`) interpolated as snippet sections inside `` figma.code`...` ``, booleans using conditionals\n\nIf anything looks uncertain, consult [api.md](references\u002Fapi.md) for API details and [advanced-patterns.md](references\u002Fadvanced-patterns.md) for complex nesting.\n\n## Inline Quick Reference\n\n### `instance.*` Methods\n\n| Method | Signature | Returns |\n|---|---|---|\n| `getString` | `(propName: string)` | `string` |\n| `getBoolean` | `(propName: string, mapping?: { true: any, false: any })` | `boolean \\| any` |\n| `getEnum` | `(propName: string, mapping: { [figmaVal]: codeVal })` | `any` |\n| `getInstanceSwap` | `(propName: string)` | `InstanceHandle \\| null` |\n| `getSlot` | `(propName: string)` | `ResultSection[] \\| undefined` |\n| `getPropertyValue` | `(propName: string)` | `string \\| boolean` |\n| `findInstance` | `(layerName: string, opts?: SelectorOptions)` | `InstanceHandle \\| ErrorHandle` |\n| `findText` | `(layerName: string, opts?: SelectorOptions)` | `TextHandle \\| ErrorHandle` |\n| `findConnectedInstance` | `(codeConnectId: string, opts?: SelectorOptions)` | `InstanceHandle \\| ErrorHandle` |\n| `findConnectedInstances` | `(selector: (node) => boolean, opts?: SelectorOptions)` | `InstanceHandle[]` |\n| `findLayers` | `(selector: (node) => boolean, opts?: SelectorOptions)` | `(InstanceHandle \\| TextHandle)[]` |\n\n### InstanceHandle Methods\n\n| Method | Returns |\n|---|---|\n| `hasCodeConnect()` | `boolean` |\n| `executeTemplate()` | `{ example: ResultSection[], metadata: Metadata }` |\n| `codeConnectId()` | `string \\| null` |\n\n### TextHandle Properties\n\n| Property | Type |\n|---|---|\n| `.textContent` | `string` |\n| `.name` | `string` |\n\n### SelectorOptions\n\n```ts\n{ path?: string[], traverseInstances?: boolean }\n```\n\n- `traverseInstances: true` — required when the target lives inside another nested instance. Without it, `findInstance`\u002F`findText` only search the current instance's own layers and stop at nested instance boundaries.\n- `path: string[]` — disambiguates when multiple descendants share the same layer name. Lists parent layer names that must appear on the path to the target.\n\n**Examples:**\n\n```ts\n\u002F\u002F Layer hierarchy:\n\u002F\u002F   A > C (instance) > \"mychild\"\n\u002F\u002F \"mychild\" sits inside nested instance C, so plain findInstance returns ErrorHandle.\ninstance.findInstance('mychild', { traverseInstances: true })\n\n\u002F\u002F Layer hierarchy:\n\u002F\u002F   A > C (instance) > \"mychild\"\n\u002F\u002F   A > D (instance) > \"mychild\"\n\u002F\u002F Two \"mychild\" layers exist — use path to pick the one under C.\ninstance.findInstance('mychild', { traverseInstances: true, path: ['C'] })\n```\n\n**When to reach into a nested instance from a parent template:** only when the parent code component (from Step 4) takes the nested layer as a prop value itself (e.g. `\u003CC show={\u003CB \u002F>} \u002F>` — A forwards B into C). If the parent just composes C and C renders B internally, resolve C with `executeTemplate()` and let C's own template handle B — don't duplicate B's rendering at the parent level.\n\n### Export Structure\n\n```ts\nexport default {\n  example: figma.code`...`,                      \u002F\u002F Required: ResultSection[]\n  id: 'component-name',                         \u002F\u002F Required: string\n  imports: ['import { X } from \"...\"'],          \u002F\u002F Optional: string[]\n  metadata: { nestable: true, props: {} }        \u002F\u002F Optional\n}\n```\n\n## Rules and Pitfalls\n\n1. **Never string-concatenate template results.** `executeTemplate().example` is a `ResultSection[]` object, not a string. Using `+` or `.join()` produces `[object Object]`. Always interpolate inside tagged templates: `` figma.code`${snippet1}${snippet2}` ``\n\n2. **Do not use `hasCodeConnect()` guards.** Call `executeTemplate()` directly on any instance after a `type === 'INSTANCE'` check. The runtime handles instances without Code Connect automatically.\n\n   ```ts\n   \u002F\u002F WRONG — hasCodeConnect() gate drops non-CC instances\n   if (icon && icon.type === 'INSTANCE' && icon.hasCodeConnect()) {\n     iconCode = icon.executeTemplate().example\n   }\n\n   \u002F\u002F CORRECT — let the runtime handle all instances\n   if (icon && icon.type === 'INSTANCE') {\n     iconCode = icon.executeTemplate().example\n   }\n   ```\n\n3. **Check `type === 'INSTANCE'` before calling `executeTemplate()`.** `findInstance()`, `findConnectedInstance()`, and `findText()` return an `ErrorHandle` (truthy, but not a real node) on failure — not `null`. Always add a type check to avoid crashes: `if (child && child.type === 'INSTANCE') { ... }`\n\n4. **Prefer `getInstanceSwap()` over `findInstance()`** when a component property exists for the slot. `findInstance('Star Icon')` breaks when the icon is swapped to a different name; `getInstanceSwap('Icon')` always works regardless of which instance is in the slot.\n\n5. **Use `getSlot()` only when the Figma property type is `SLOT`.** For **INSTANCE_SWAP** props, use `getInstanceSwap()` (returns an `InstanceHandle`). `getSlot()` returns structured slot sections, not instances — never call `executeTemplate()` on its return value.\n\n6. **Property names are case-sensitive** and must exactly match what `get_context_for_code_connect` returns.\n\n7. **Handle multiple template arrays correctly.** When iterating over children, set each result in a separate variable and interpolate them individually — do not use `.map().join()`:\n   ```ts\n   \u002F\u002F Wrong:\n   items.map(n => n.executeTemplate().example).join('\\n')\n\n   \u002F\u002F Correct — use separate variables:\n   const child1 = items[0]?.executeTemplate().example\n   const child2 = items[1]?.executeTemplate().example\n   export default { example: figma.code`${child1}${child2}` }\n   ```\n\n7. **Never hardcode slot or children content.** Always resolve child instances dynamically — use `getInstanceSwap()` for INSTANCE_SWAP properties, `findInstance()`\u002F`findConnectedInstance()` for direct children — and render them via `executeTemplate()`. Never construct JSX from a layer name (e.g., `\u003CStarIcon \u002F>`) or guess import paths. If an instance has no Code Connect, omit it — do not add a hardcoded fallback.\n\n   ```ts\n   \u002F\u002F WRONG — hardcodes the icon from its layer name\n   example: figma.code`\u003CButton icon={\u003CStarIcon \u002F>}>Submit\u003C\u002FButton>`\n\n   \u002F\u002F CORRECT — resolves dynamically, works for any swapped icon\n   const icon = instance.findInstance('Icon')\n   let iconCode\n   if (icon && icon.type === 'INSTANCE') {\n     iconCode = icon.executeTemplate().example\n   }\n   example: figma.code`\u003CButton${iconCode ? figma.code` icon={${iconCode}}` : ''}>...\u003C\u002FButton>`\n   ```\n\n8. **Attempt to represent every Figma property via a code prop.** The code component's `Props` interface (from Step 4) is the authoritative list of attribute names. For each Figma property, figure out the right way to represent it using the API methods from Step 5 — direct name match, value transformation, or whatever fits. If no code prop fits at all, omit it — don't invent a prop name.\n\n## Complete Worked Example\n\nGiven URL: `https:\u002F\u002Ffigma.com\u002Fdesign\u002Fabc123\u002FMyFile?node-id=42-100`\n\n**Step 1:** Parse the URL.\n- `fileKey` = `abc123`\n- `nodeId` = `42-100` → `42:100`\n\n**Step 2:** Call `get_code_connect_suggestions` with `fileKey: \"abc123\"`, `nodeId: \"42:100\"`, `excludeMappingPrompt: true`.\nResponse returns one component with `mainComponentNodeId: \"42:100\"`. If the response were empty, stop and inform the user. If multiple components were returned, repeat Steps 3–6 for each.\n\n**Step 3:** Call `get_context_for_code_connect` with `fileKey: \"abc123\"`, `nodeId: \"42:100\"` (from Step 2), `clientFrameworks: [\"react\"]`, `clientLanguages: [\"typescript\"]`.\n\nResponse includes properties:\n- Label (TEXT)\n- Variant (VARIANT): Primary, Secondary\n- Size (VARIANT): Small, Medium, Large\n- Disabled (BOOLEAN)\n- Has Icon (BOOLEAN)\n- Icon (INSTANCE_SWAP)\n\n**Step 4:** Search codebase → find `Button` component. Read its source to confirm props: `variant`, `size`, `disabled`, `icon`, `children`. Import path: `\"primitives\"`.\n\n**Step 5:** Create `src\u002Ffigma\u002Fprimitives\u002FButton.figma.ts`:\n\n```ts\n\u002F\u002F url=https:\u002F\u002Ffigma.com\u002Fdesign\u002Fabc123\u002FMyFile?node-id=42-100\n\u002F\u002F source=src\u002Fcomponents\u002FButton.tsx\n\u002F\u002F component=Button\nimport figma from 'figma'\nconst instance = figma.selectedInstance\n\nconst label = instance.getString('Label')\nconst variant = instance.getEnum('Variant', {\n  'Primary': 'primary',\n  'Secondary': 'secondary',\n})\nconst size = instance.getEnum('Size', {\n  'Small': 'sm',\n  'Medium': 'md',\n  'Large': 'lg',\n})\nconst disabled = instance.getBoolean('Disabled')\nconst hasIcon = instance.getBoolean('Has Icon')\nconst icon = hasIcon ? instance.getInstanceSwap('Icon') : null\nlet iconCode\nif (icon && icon.type === 'INSTANCE') {\n  iconCode = icon.executeTemplate().example\n}\n\nexport default {\n  example: figma.code`\n    \u003CButton\n      variant=\"${variant}\"\n      size=\"${size}\"\n      ${disabled ? 'disabled' : ''}\n      ${iconCode ? figma.code`icon={${iconCode}}` : ''}\n    >\n      ${label}\n    \u003C\u002FButton>\n  `,\n  imports: ['import { Button } from \"primitives\"'],\n  id: 'button',\n  metadata: { nestable: true }\n}\n```\n\n**Step 6:** Read back file to verify syntax.\n\n## Additional Reference\n\nFor advanced patterns (multi-level nested components, `findConnectedInstances` filtering, metadata prop passing between parent\u002Fchild templates):\n\n- [api.md](references\u002Fapi.md) — Full Code Connect API reference\n- [advanced-patterns.md](references\u002Fadvanced-patterns.md) — Advanced nesting, metadata props, and descendant patterns\n","# Code Connect\n\n## Overview\n\nCreate Code Connect template files (`.figma.ts`) that map Figma components to code snippets. Given a Figma URL, follow the steps below to create a template.\n\n> **You write `.figma.ts` template files ONLY — never `.figma.tsx`.** This skill produces *parserless templates*: a `.figma.ts` file whose default export uses a `` figma.code`...` `` tagged template. Do **NOT** write a `.figma.tsx` file and do **NOT** use `figma.connect()` — that is the separate **parser-based** Code Connect format (published a different way) and is the **wrong artifact** for this skill; output written as `.figma.tsx` is rejected outright. If a `.figma.tsx` already exists for a component, leave it untouched and add your `.figma.ts` template alongside it. A capable model may be tempted to reach for the more familiar `.figma.tsx` \u002F `figma.connect()` pattern from memory — resist it; here the correct output is **always** `.figma.ts` + `figma.code`.\n\n## Prerequisites\n\n- **Figma MCP server must be connected** — verify that Figma MCP tools (e.g., `get_code_connect_suggestions`) are available before proceeding. If not, guide the user to enable the Figma MCP server and restart their MCP client.\n- **Components must be published** — Code Connect only works with components published to a Figma team library. If a component is not published, inform the user and stop.\n- **Organization or Enterprise plan required** — Code Connect is not available on Free or Professional plans.\n- **URL must include `node-id`** — the Figma URL must contain the `node-id` query parameter.\n- **TypeScript types** — for editor autocomplete and type checking in `.figma.ts` files `@figma\u002Fcode-connect\u002Ffigma-types` must be added to `types` in `tsconfig.json`:\n  ```json\n  {\n    \"compilerOptions\": {\n      \"types\": [\"@figma\u002Fcode-connect\u002Ffigma-types\"]\n    }\n  }\n  ```\n\n## Step 1: Parse the Figma URL\n\nExtract `fileKey` and `nodeId` from the URL:\n\n| URL Format | fileKey | nodeId |\n|---|---|---|\n| `figma.com\u002Fdesign\u002F:fileKey\u002F:name?node-id=X-Y` | `:fileKey` | `X-Y` → `X:Y` |\n| `figma.com\u002Ffile\u002F:fileKey\u002F:name?node-id=X-Y` | `:fileKey` | `X-Y` → `X:Y` |\n| `figma.com\u002Fdesign\u002F:fileKey\u002Fbranch\u002F:branchKey\u002F:name` | use `:branchKey` | from `node-id` param |\n\nAlways convert `nodeId` hyphens to colons: `1234-5678` → `1234:5678`.\n\n**Worked example:**\n\nGiven: `https:\u002F\u002Fwww.figma.com\u002Fdesign\u002FQiEF6w564ggoW8ftcLvdcu\u002FMyDesignSystem?node-id=4185-3778`\n- `fileKey` = `QiEF6w564ggoW8ftcLvdcu`\n- `nodeId` = `4185-3778` → `4185:3778`\n\n## Step 2: Discover Unmapped Components\n\nThe user may provide a URL pointing to a frame, instance, or variant — not necessarily a component set or standalone component. Call the MCP tool `get_code_connect_suggestions` with:\n- `fileKey` — from Step 1\n- `nodeId` — from Step 1 (colons format)\n- `excludeMappingPrompt` — `true` (returns a lightweight list of unmapped components)\n\nThis tool identifies published components in the selection that don't yet have Code Connect mappings.\n\n**Handle the response:**\n\n- **\"No published components found in this selection\"** — the node contains no published components. Inform the user they need to publish the component to a team library in Figma first, then stop.\n- **\"All component instances in this selection are already connected to code via Code Connect\"** — everything is already mapped. Inform the user and stop.\n- **Normal response with component list** — extract the `mainComponentNodeId` for each returned component. Use these resolved node IDs (not the original from the URL) for all subsequent steps. If multiple components are returned (e.g. the user selected a frame containing several different component instances), repeat Steps 3–6 for each one.\n\n## Step 3: Fetch Component Properties\n\nCall the MCP tool `get_context_for_code_connect` with:\n- `fileKey` — from Step 1\n- `nodeId` — the resolved `mainComponentNodeId` from Step 2\n- `clientFrameworks` — determine from `figma.config.json` `parser` field (e.g. `\"react\"` → `[\"react\"]`)\n- `clientLanguages` — infer from project file extensions (e.g. TypeScript project → `[\"typescript\"]`, JavaScript → `[\"javascript\"]`)\n\nFor multiple components, call the tool once per node ID.\n\nThe response contains the Figma component's **property definitions** — note each property's name and type:\n- **TEXT** — text content (labels, titles, placeholders)\n- **BOOLEAN** — toggles (show\u002Fhide icon, disabled state)\n- **VARIANT** — enum options (size, variant, state)\n- **INSTANCE_SWAP** — swappable nested instances tied to a specific component (icon, avatar)\n- **SLOT** — flexible content regions (freeform layout, mixed children); use `getSlot()` in templates (not the same as INSTANCE_SWAP)\n\nSave this property list — you will use it in Step 5 to write the template.\n\n## Step 4: Identify the Code Component\n\nIf the user did not specify which code component to connect:\n\n1. Check `figma.config.json` for `paths` and `importPaths` to find where components live\n2. Search the codebase for a component matching the Figma component name. Check common directories (`src\u002Fcomponents\u002F`, `components\u002F`, `lib\u002Fui\u002F`, `app\u002Fcomponents\u002F`) if `figma.config.json` doesn't specify paths\n3. Read candidate files and compare their props interface against the Figma properties from Step 3 — look for matching variant types, size options, boolean flags, and slot props\n4. If multiple candidates match, pick the one with the closest prop-interface match and explain your reasoning to the user\n5. If no match is found, show the 2 closest candidates and ask the user to confirm or provide the correct path\n\n**Confirm with the user** before proceeding to Step 5. Present the match: which code component you found, where it lives, and why it matches (prop correspondence, naming, purpose).\n\nRead `figma.config.json` for import path aliases — the `importPaths` section maps glob patterns to import specifiers, and the `paths` section maps those specifiers to directories.\n\nRead the code component's source to understand its props interface — this informs how to map Figma properties to code props in Step 5.\n\n## Step 5: Create the Template File (.figma.ts)\n\n### File location\n\nPlace the file alongside existing Code Connect files. Check `figma.config.json` `include` patterns for the correct directory. **Name it `ComponentName.figma.ts` — never `ComponentName.figma.tsx`.** The `.figma.tsx` extension is the parser-based format; do not create one or modify an existing one.\n\n### Template structure\n\nEvery template file follows this structure:\n\n```ts\n\u002F\u002F url=https:\u002F\u002Fwww.figma.com\u002Ffile\u002F{fileKey}\u002F{fileName}?node-id={nodeId}\n\u002F\u002F source={path to code component from Step 4}\n\u002F\u002F component={code component name from Step 4}\nimport figma from 'figma'\nconst instance = figma.selectedInstance\n\n\u002F\u002F Extract properties from the Figma component (see property mapping below)\n\u002F\u002F ...\n\nexport default {\n  example: figma.code`\u003CComponent ... \u002F>`,       \u002F\u002F Required: code snippet\n  imports: ['import { Component } from \"...\"'], \u002F\u002F Optional: import statements\n  id: 'component-name',                         \u002F\u002F Required: unique identifier\n  metadata: {                                    \u002F\u002F Optional\n    nestable: true,                              \u002F\u002F true = inline in parent, false = show as pill\n    props: {}                                    \u002F\u002F data accessible to parent templates\n  }\n}\n```\n\n### Property mapping\n\nUse the property list from Step 3 to extract values. For each Figma property type, use the corresponding method:\n\n| Figma Property Type | Template Method | When to Use |\n|---|---|---|\n| TEXT | `instance.getString('Name')` | Labels, titles, placeholder text |\n| BOOLEAN | `instance.getBoolean('Name', { true: ..., false: ... })` | Toggle visibility, conditional props |\n| VARIANT | `instance.getEnum('Name', { 'FigmaVal': 'codeVal' })` | Size, variant, state enums |\n| INSTANCE_SWAP | `instance.getInstanceSwap('Name')` | Swapped instance for a fixed component slot (then `hasCodeConnect()` \u002F `executeTemplate()`) - do not confuse with the SLOT property below |\n| SLOT | `instance.getSlot('Name')` | Freeform slot content only when the Figma property type is **SLOT** \n| (child layer) | `instance.findInstance('LayerName')` | Named child instances without a property |\n| (text layer) | `instance.findText('LayerName')` → `.textContent` | Text content from named layers |\n\n**TEXT** — get the string value directly:\n```ts\nconst label = instance.getString('Label')\n```\n\n**VARIANT** — map Figma enum values to code values:\n```ts\nconst variant = instance.getEnum('Variant', {\n  'Primary': 'primary',\n  'Secondary': 'secondary',\n})\n\nconst size = instance.getEnum('Size', {\n  'Small': 'sm',\n  'Medium': 'md',\n  'Large': 'lg',\n})\n```\n\n**BOOLEAN** — simple boolean or mapped to values:\n```ts\n\u002F\u002F Simple boolean\nconst disabled = instance.getBoolean('Disabled')\n\n\u002F\u002F Mapped to code values (e.g. when the code prop is an enum, not a boolean)\nconst size = instance.getBoolean('Show Label', { true: 'large', false: 'small' })\n```\n\n**Map Figma properties to code props where there's a valid correspondence.** Figma properties and code props don't always line up 1:1 — some Figma properties map directly (by name, or via the API methods above), others have no code equivalent. Where a mapping exists, use it; where none fits, omit the Figma property rather than invent a code prop. Never emit an attribute whose name doesn't appear in the code component's `Props` interface.\n\n### Exhaustive variant handling\n\nWhen a VARIANT property has multiple possible values, the `getEnum` mapping **must list every value** returned by `get_context_for_code_connect`. Don't omit values — an unmapped value silently returns `undefined`, producing broken output.\n\n```ts\n\u002F\u002F WRONG — omits 'Warning', which will render as undefined\nconst status = instance.getEnum('Status', {\n  'Success': 'success',\n  'Error': 'error',\n})\n\n\u002F\u002F CORRECT — every value is mapped\nconst status = instance.getEnum('Status', {\n  'Success': 'success',\n  'Error': 'error',\n  'Warning': 'warning',\n  'Info': 'info',\n})\n```\n\nWhen **two or more VARIANT properties combine** to produce different code output, generate exhaustive conditional branches. For example, 2 variants × 2 values = 4 branches:\n\n```ts\nconst type = instance.getEnum('Type', { 'Filled': 'filled', 'Outlined': 'outlined' })\nconst status = instance.getEnum('Status', { 'Success': 'success', 'Error': 'error' })\n\nlet colorClass\nif (type === 'filled' && status === 'success') {\n  colorClass = 'bg-green-500 text-white'\n} else if (type === 'filled' && status === 'error') {\n  colorClass = 'bg-red-500 text-white'\n} else if (type === 'outlined' && status === 'success') {\n  colorClass = 'bg-transparent border-green-500'\n} else if (type === 'outlined' && status === 'error') {\n  colorClass = 'bg-transparent border-red-500'\n}\n```\n\nIf the combinations produce **repetitive** output (e.g., `Size` doesn't change the snippet structure — it's just passed through as a prop), a single `getEnum` mapping per variant is sufficient — no need for cross-product branches.\n\n**INSTANCE_SWAP** — access swappable component instances:\n```ts\nconst icon = instance.getInstanceSwap('Icon')\nlet iconCode\nif (icon && icon.type === 'INSTANCE') {\n  iconCode = icon.executeTemplate().example\n}\n```\n\n**SLOT** — `getSlot(propName)` is only valid when the Figma component property reported in Step 3 has type **`SLOT`**. Do not use `getSlot()` for **INSTANCE_SWAP** properties (those use `getInstanceSwap()`). Slots are explicit “content regions” in the component definition, not generic nested instances.\n\n- **Signature:** `getSlot(propName: string): ResultSection[] | undefined`\n```ts\n\u002F\u002F Figma property \"Content\" must be type SLOT in component properties\nconst content = instance.getSlot('Content')\n\nexport default {\n  example: figma.code`\u003CCard>${content}\u003C\u002FCard>`,\n  \u002F\u002F ...\n}\n```\n\n### Interpolation in tagged templates\n\nWhen interpolating values in tagged templates, use the correct wrapping:\n- **String values** (`getString`, `getEnum`, `textContent`): wrap in quotes → `variant=\"${variant}\"`\n- **Instance\u002Fsection values** (`executeTemplate().example`): wrap in braces → `icon={${iconCode}}`\n- **Slot sections** (`getSlot()` result — `ResultSection[] | undefined`): interpolate directly inside `` figma.code`...` `` (same shape as nested snippet sections), e.g. `` figma.code`\u003CSelect>${content}\u003C\u002FSelect>` `` — do not treat as a plain string\n- **Boolean bare props**: use conditional → `${disabled ? 'disabled' : ''}`\n\n### Finding descendant layers\n\nWhen you need to access children that aren't exposed as component properties:\n\n| Method | Use when |\n|---|---|\n| `instance.getInstanceSwap('PropName')` | Figma property type is **INSTANCE_SWAP** (fixed swapped instance) |\n| `instance.getSlot('PropName')` | Figma property type is **SLOT** (freeform content region) |\n| `instance.findInstance('LayerName')` | You know the child layer name (no component property) |\n| `instance.findText('LayerName')` → `.textContent` | You need text content from a named text layer |\n| `instance.findConnectedInstance('id')` | You know the child's Code Connect `id` |\n| `instance.findConnectedInstances(fn)` | You need multiple connected children matching a filter |\n| `instance.findLayers(fn)` | You need any layers (text + instances) matching a filter |\n\n### Nested configurable instances\n\nA component may contain child instances that are **not exposed as component properties** (no INSTANCE_SWAP) but are still **independently configurable** — they have their own variants, properties, or swap slots. These must be resolved dynamically, not hardcoded.\n\n1. **Check whether the child already has a Code Connect template** — use `get_code_connect_suggestions` or check existing `.figma.ts` files in the project.\n2. **If no template exists, create one** for the child so it renders correctly both standalone and when nested.\n3. **Reference the child from the parent** using `findInstance()` or `findConnectedInstance()`, then call `executeTemplate()`.\n\n```ts\n\u002F\u002F Parent template — the Badge child isn't a prop, but it's configurable\nconst badge = instance.findInstance('Status Badge')\nlet badgeCode\nif (badge && badge.type === 'INSTANCE') {\n  badgeCode = badge.executeTemplate().example\n}\n\nexport default {\n  example: figma.code`\u003CCard>${badgeCode}\u003C\u002FCard>`,\n  \u002F\u002F ...\n}\n```\n\nThis applies to icons, badges, labels, and any other nested instance that is configurable by itself — always connect them and render dynamically, never hardcode their content.\n\n### Nested component example\n\nFor multi-level nested components or metadata prop passing between templates, see [advanced-patterns.md](references\u002Fadvanced-patterns.md).\n\n```ts\nconst icon = instance.getInstanceSwap('Icon')\nlet iconSnippet\nif (icon && icon.type === 'INSTANCE') {\n  iconSnippet = icon.executeTemplate().example\n}\n\nexport default {\n  example: figma.code`\u003CButton ${iconSnippet ? figma.code`icon={${iconSnippet}}` : ''}>${label}\u003C\u002FButton>`,\n  \u002F\u002F ...\n}\n```\n\n### Conditional props\n\n```ts\nconst variant = instance.getEnum('Variant', { 'Primary': 'primary', 'Secondary': 'secondary' })\nconst disabled = instance.getBoolean('Disabled')\n\nexport default {\n  example: figma.code`\n    \u003CButton\n      variant=\"${variant}\"\n      ${disabled ? 'disabled' : ''}\n    >\n      ${label}\n    \u003C\u002FButton>\n  `,\n  \u002F\u002F ...\n}\n```\n\n## Step 6: Validate\n\nRead back the `.figma.ts` file and review it against the following:\n\n- **Correct file type & format (check this FIRST)** — the file is `ComponentName.figma.ts` (NOT `.figma.tsx`), and its default export is a parserless template using a `` figma.code`...` `` tagged template. It must NOT use `figma.connect()` (the parser-based format). If you wrote `.figma.tsx` or `figma.connect()`, discard it and rewrite as a `.figma.ts` `figma.code` template.\n- **Property coverage** — every Figma property from Step 3 should be accounted for in the template. Flag any that are missing and ask the user if they were intentionally omitted.\n- **Valid, correctly typed code** — all emitted code must be valid and correctly typed against the code component's `Props` interface. Never make up component properties — if a Figma property has no corresponding code prop, omit it rather than invent one.\n- **No hardcoded children** — verify that every INSTANCE_SWAP property and child component slot uses the dynamic APIs (`getInstanceSwap()`, `findInstance()`, `findConnectedInstance()`, etc.) with `executeTemplate()`. No slot should contain hardcoded component content.\n- **Rules and Pitfalls** — check for the common mistakes listed below (string concatenation of template results, unnecessary `hasCodeConnect()` guards, missing `type === 'INSTANCE'` checks, etc.)\n- **Interpolation wrapping** — strings (`getString`, `getEnum`, `textContent`) wrapped in quotes, instance\u002Fsection values (`executeTemplate().example`) wrapped in braces, slot sections (`getSlot`) interpolated as snippet sections inside `` figma.code`...` ``, booleans using conditionals\n\nIf anything looks uncertain, consult [api.md](references\u002Fapi.md) for API details and [advanced-patterns.md](references\u002Fadvanced-patterns.md) for complex nesting.\n\n## Inline Quick Reference\n\n### `instance.*` Methods\n\n| Method | Signature | Returns |\n|---|---|---|\n| `getString` | `(propName: string)` | `string` |\n| `getBoolean` | `(propName: string, mapping?: { true: any, false: any })` | `boolean \\| any` |\n| `getEnum` | `(propName: string, mapping: { [figmaVal]: codeVal })` | `any` |\n| `getInstanceSwap` | `(propName: string)` | `InstanceHandle \\| null` |\n| `getSlot` | `(propName: string)` | `ResultSection[] \\| undefined` |\n| `getPropertyValue` | `(propName: string)` | `string \\| boolean` |\n| `findInstance` | `(layerName: string, opts?: SelectorOptions)` | `InstanceHandle \\| ErrorHandle` |\n| `findText` | `(layerName: string, opts?: SelectorOptions)` | `TextHandle \\| ErrorHandle` |\n| `findConnectedInstance` | `(codeConnectId: string, opts?: SelectorOptions)` | `InstanceHandle \\| ErrorHandle` |\n| `findConnectedInstances` | `(selector: (node) => boolean, opts?: SelectorOptions)` | `InstanceHandle[]` |\n| `findLayers` | `(selector: (node) => boolean, opts?: SelectorOptions)` | `(InstanceHandle \\| TextHandle)[]` |\n\n### InstanceHandle Methods\n\n| Method | Returns |\n|---|---|\n| `hasCodeConnect()` | `boolean` |\n| `executeTemplate()` | `{ example: ResultSection[], metadata: Metadata }` |\n| `codeConnectId()` | `string \\| null` |\n\n### TextHandle Properties\n\n| Property | Type |\n|---|---|\n| `.textContent` | `string` |\n| `.name` | `string` |\n\n### SelectorOptions\n\n```ts\n{ path?: string[], traverseInstances?: boolean }\n```\n\n- `traverseInstances: true` — required when the target lives inside another nested instance. Without it, `findInstance`\u002F`findText` only search the current instance's own layers and stop at nested instance boundaries.\n- `path: string[]` — disambiguates when multiple descendants share the same layer name. Lists parent layer names that must appear on the path to the target.\n\n**Examples:**\n\n```ts\n\u002F\u002F Layer hierarchy:\n\u002F\u002F   A > C (instance) > \"mychild\"\n\u002F\u002F \"mychild\" sits inside nested instance C, so plain findInstance returns ErrorHandle.\ninstance.findInstance('mychild', { traverseInstances: true })\n\n\u002F\u002F Layer hierarchy:\n\u002F\u002F   A > C (instance) > \"mychild\"\n\u002F\u002F   A > D (instance) > \"mychild\"\n\u002F\u002F Two \"mychild\" layers exist — use path to pick the one under C.\ninstance.findInstance('mychild', { traverseInstances: true, path: ['C'] })\n```\n\n**When to reach into a nested instance from a parent template:** only when the parent code component (from Step 4) takes the nested layer as a prop value itself (e.g. `\u003CC show={\u003CB \u002F>} \u002F>` — A forwards B into C). If the parent just composes C and C renders B internally, resolve C with `executeTemplate()` and let C's own template handle B — don't duplicate B's rendering at the parent level.\n\n### Export Structure\n\n```ts\nexport default {\n  example: figma.code`...`,                      \u002F\u002F Required: ResultSection[]\n  id: 'component-name',                         \u002F\u002F Required: string\n  imports: ['import { X } from \"...\"'],          \u002F\u002F Optional: string[]\n  metadata: { nestable: true, props: {} }        \u002F\u002F Optional\n}\n```\n\n## Rules and Pitfalls\n\n1. **Never string-concatenate template results.** `executeTemplate().example` is a `ResultSection[]` object, not a string. Using `+` or `.join()` produces `[object Object]`. Always interpolate inside tagged templates: `` figma.code`${snippet1}${snippet2}` ``\n\n2. **Do not use `hasCodeConnect()` guards.** Call `executeTemplate()` directly on any instance after a `type === 'INSTANCE'` check. The runtime handles instances without Code Connect automatically.\n\n   ```ts\n   \u002F\u002F WRONG — hasCodeConnect() gate drops non-CC instances\n   if (icon && icon.type === 'INSTANCE' && icon.hasCodeConnect()) {\n     iconCode = icon.executeTemplate().example\n   }\n\n   \u002F\u002F CORRECT — let the runtime handle all instances\n   if (icon && icon.type === 'INSTANCE') {\n     iconCode = icon.executeTemplate().example\n   }\n   ```\n\n3. **Check `type === 'INSTANCE'` before calling `executeTemplate()`.** `findInstance()`, `findConnectedInstance()`, and `findText()` return an `ErrorHandle` (truthy, but not a real node) on failure — not `null`. Always add a type check to avoid crashes: `if (child && child.type === 'INSTANCE') { ... }`\n\n4. **Prefer `getInstanceSwap()` over `findInstance()`** when a component property exists for the slot. `findInstance('Star Icon')` breaks when the icon is swapped to a different name; `getInstanceSwap('Icon')` always works regardless of which instance is in the slot.\n\n5. **Use `getSlot()` only when the Figma property type is `SLOT`.** For **INSTANCE_SWAP** props, use `getInstanceSwap()` (returns an `InstanceHandle`). `getSlot()` returns structured slot sections, not instances — never call `executeTemplate()` on its return value.\n\n6. **Property names are case-sensitive** and must exactly match what `get_context_for_code_connect` returns.\n\n7. **Handle multiple template arrays correctly.** When iterating over children, set each result in a separate variable and interpolate them individually — do not use `.map().join()`:\n   ```ts\n   \u002F\u002F Wrong:\n   items.map(n => n.executeTemplate().example).join('\\n')\n\n   \u002F\u002F Correct — use separate variables:\n   const child1 = items[0]?.executeTemplate().example\n   const child2 = items[1]?.executeTemplate().example\n   export default { example: figma.code`${child1}${child2}` }\n   ```\n\n7. **Never hardcode slot or children content.** Always resolve child instances dynamically — use `getInstanceSwap()` for INSTANCE_SWAP properties, `findInstance()`\u002F`findConnectedInstance()` for direct children — and render them via `executeTemplate()`. Never construct JSX from a layer name (e.g., `\u003CStarIcon \u002F>`) or guess import paths. If an instance has no Code Connect, omit it — do not add a hardcoded fallback.\n\n   ```ts\n   \u002F\u002F WRONG — hardcodes the icon from its layer name\n   example: figma.code`\u003CButton icon={\u003CStarIcon \u002F>}>Submit\u003C\u002FButton>`\n\n   \u002F\u002F CORRECT — resolves dynamically, works for any swapped icon\n   const icon = instance.findInstance('Icon')\n   let iconCode\n   if (icon && icon.type === 'INSTANCE') {\n     iconCode = icon.executeTemplate().example\n   }\n   example: figma.code`\u003CButton${iconCode ? figma.code` icon={${iconCode}}` : ''}>...\u003C\u002FButton>`\n   ```\n\n8. **Attempt to represent every Figma property via a code prop.** The code component's `Props` interface (from Step 4) is the authoritative list of attribute names. For each Figma property, figure out the right way to represent it using the API methods from Step 5 — direct name match, value transformation, or whatever fits. If no code prop fits at all, omit it — don't invent a prop name.\n\n## Complete Worked Example\n\nGiven URL: `https:\u002F\u002Ffigma.com\u002Fdesign\u002Fabc123\u002FMyFile?node-id=42-100`\n\n**Step 1:** Parse the URL.\n- `fileKey` = `abc123`\n- `nodeId` = `42-100` → `42:100`\n\n**Step 2:** Call `get_code_connect_suggestions` with `fileKey: \"abc123\"`, `nodeId: \"42:100\"`, `excludeMappingPrompt: true`.\nResponse returns one component with `mainComponentNodeId: \"42:100\"`. If the response were empty, stop and inform the user. If multiple components were returned, repeat Steps 3–6 for each.\n\n**Step 3:** Call `get_context_for_code_connect` with `fileKey: \"abc123\"`, `nodeId: \"42:100\"` (from Step 2), `clientFrameworks: [\"react\"]`, `clientLanguages: [\"typescript\"]`.\n\nResponse includes properties:\n- Label (TEXT)\n- Variant (VARIANT): Primary, Secondary\n- Size (VARIANT): Small, Medium, Large\n- Disabled (BOOLEAN)\n- Has Icon (BOOLEAN)\n- Icon (INSTANCE_SWAP)\n\n**Step 4:** Search codebase → find `Button` component. Read its source to confirm props: `variant`, `size`, `disabled`, `icon`, `children`. Import path: `\"primitives\"`.\n\n**Step 5:** Create `src\u002Ffigma\u002Fprimitives\u002FButton.figma.ts`:\n\n```ts\n\u002F\u002F url=https:\u002F\u002Ffigma.com\u002Fdesign\u002Fabc123\u002FMyFile?node-id=42-100\n\u002F\u002F source=src\u002Fcomponents\u002FButton.tsx\n\u002F\u002F component=Button\nimport figma from 'figma'\nconst instance = figma.selectedInstance\n\nconst label = instance.getString('Label')\nconst variant = instance.getEnum('Variant', {\n  'Primary': 'primary',\n  'Secondary': 'secondary',\n})\nconst size = instance.getEnum('Size', {\n  'Small': 'sm',\n  'Medium': 'md',\n  'Large': 'lg',\n})\nconst disabled = instance.getBoolean('Disabled')\nconst hasIcon = instance.getBoolean('Has Icon')\nconst icon = hasIcon ? instance.getInstanceSwap('Icon') : null\nlet iconCode\nif (icon && icon.type === 'INSTANCE') {\n  iconCode = icon.executeTemplate().example\n}\n\nexport default {\n  example: figma.code`\n    \u003CButton\n      variant=\"${variant}\"\n      size=\"${size}\"\n      ${disabled ? 'disabled' : ''}\n      ${iconCode ? figma.code`icon={${iconCode}}` : ''}\n    >\n      ${label}\n    \u003C\u002FButton>\n  `,\n  imports: ['import { Button } from \"primitives\"'],\n  id: 'button',\n  metadata: { nestable: true }\n}\n```\n\n**Step 6:** Read back file to verify syntax.\n\n## Additional Reference\n\nFor advanced patterns (multi-level nested components, `findConnectedInstances` filtering, metadata prop passing between parent\u002Fchild templates):\n\n- [api.md](references\u002Fapi.md) — Full Code Connect API reference\n- [advanced-patterns.md](references\u002Fadvanced-patterns.md) — Advanced nesting, metadata props, and descendant patterns\n",{"name":5,"description":7,"disable-model-invocation":20},"main","907b1d897cc6743f7f133f8ea2021e1331b0b020",".codex\u002F.tmp\u002Fplugins\u002Fplugins\u002Ffigma\u002Fskills\u002Ffigma-code-connect","https:\u002F\u002Fgithub.com\u002Frossboyd\u002Fquickque","https:\u002F\u002Fgithub.com\u002Frossboyd","www.bigideasgroup.co.uk","2026-09-22 02:03:50",{"source":8,"skillName":5,"commands":32,"prompt":42,"zipAvailable":43},[33,36,39],{"tool":34,"command":35},"npx","npx skills add rossboyd\u002Fquickque --skill figma-code-connect",{"tool":37,"command":38},"bunx","bunx skills add rossboyd\u002Fquickque --skill figma-code-connect",{"tool":40,"command":41},"pnpm","pnpm dlx skills add rossboyd\u002Fquickque --skill figma-code-connect","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Frossboyd\u002Fquickque\u002Fblob\u002Fmain\u002F.codex\u002F.tmp\u002Fplugins\u002Fplugins\u002Ffigma\u002Fskills\u002Ffigma-code-connect\u002FSKILL.md",true,[45,51],{"path":46,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":49,"sourceHtmlUrl":50},"references\u002Fadvanced-patterns.md","REFERENCE","参考文档",10069,"https:\u002F\u002Fgithub.com\u002Frossboyd\u002Fquickque\u002Fblob\u002Fmain\u002F.codex\u002F.tmp\u002Fplugins\u002Fplugins\u002Ffigma\u002Fskills\u002Ffigma-code-connect\u002Freferences\u002Fadvanced-patterns.md",{"path":52,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":53,"sourceHtmlUrl":54},"references\u002Fapi.md",23396,"https:\u002F\u002Fgithub.com\u002Frossboyd\u002Fquickque\u002Fblob\u002Fmain\u002F.codex\u002F.tmp\u002Fplugins\u002Fplugins\u002Ffigma\u002Fskills\u002Ffigma-code-connect\u002Freferences\u002Fapi.md",[56,65,73,80,87,95],{"skillNo":57,"name":58,"nameZh":6,"description":59,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":60,"licenseFileUrl":61,"sourceHtmlUrl":62,"categories":63,"keywords":64,"publishedAt":19},"01M7CJSS21K09H3ZQZMPFR4ZAG","skill-installer","Install Codex skills into $CODEX_HOME\u002Fskills from a curated list or a GitHub repo path. Use when a user asks to list installable skills, install a curated skill, or install a skill from another repo (including private repos).","Apache-2.0","https:\u002F\u002Fgithub.com\u002Frossboyd\u002Fquickque\u002Fblob\u002Fmain\u002F.codex\u002Fskills\u002F.system\u002Fskill-installer\u002FLICENSE.txt","https:\u002F\u002Fgithub.com\u002Frossboyd\u002Fquickque\u002Fblob\u002Fmain\u002F.codex\u002Fskills\u002F.system\u002Fskill-installer\u002FSKILL.md",[],[],{"skillNo":66,"name":67,"nameZh":6,"description":68,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":60,"licenseFileUrl":69,"sourceHtmlUrl":70,"categories":71,"keywords":72,"publishedAt":19},"01M7CJSM1F4E7RBXCS3C18EFBY","skill-creator","Create or update a Codex skill with appropriately scoped instructions and any needed supporting resources.","https:\u002F\u002Fgithub.com\u002Frossboyd\u002Fquickque\u002Fblob\u002Fmain\u002F.codex\u002Fskills\u002F.system\u002Fskill-creator\u002Flicense.txt","https:\u002F\u002Fgithub.com\u002Frossboyd\u002Fquickque\u002Fblob\u002Fmain\u002F.codex\u002Fskills\u002F.system\u002Fskill-creator\u002FSKILL.md",[],[],{"skillNo":74,"name":75,"nameZh":6,"description":76,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":77,"categories":78,"keywords":79,"publishedAt":19},"01M7CJSGF2PJM504Q6TZCNT27C","review-agent","Perform a read-only, defect-first review of a specified code change and return every actionable finding. Use when another agent delegates review of uncommitted changes, a base-branch diff, a commit, or custom review instructions.","https:\u002F\u002Fgithub.com\u002Frossboyd\u002Fquickque\u002Fblob\u002Fmain\u002F.codex\u002Fskills\u002F.system\u002Freview-agent\u002FSKILL.md",[],[],{"skillNo":81,"name":82,"nameZh":6,"description":83,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":84,"categories":85,"keywords":86,"publishedAt":19},"01M7CJSBQTPFEQYZF4VWS7QZ3N","plugin-creator","Create and scaffold plugin directories for Codex with a required `.codex-plugin\u002Fplugin.json`, optional plugin folders\u002Ffiles, valid manifest defaults, and personal-marketplace entries by default. Use when Codex needs to create a new personal plugin, add optional plugin structure, generate or update marketplace entries for plugin ordering and availability metadata, or update an existing local plugin during development with the CLI-driven cachebuster and reinstall flow.","https:\u002F\u002Fgithub.com\u002Frossboyd\u002Fquickque\u002Fblob\u002Fmain\u002F.codex\u002Fskills\u002F.system\u002Fplugin-creator\u002FSKILL.md",[],[],{"skillNo":88,"name":89,"nameZh":6,"description":90,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":60,"licenseFileUrl":91,"sourceHtmlUrl":92,"categories":93,"keywords":94,"publishedAt":19},"01M7CJS5BHJZKA16353PVZGC50","openai-docs","Use for Codex models\u002Fpricing, scheduled tasks, skills, settings, setup, troubleshooting, customization, automations, and self-knowledge—including 'you,' 'your,' 'this app,' or 'this coding agent' when they refer to Codex—and for OpenAI APIs\u002Fproducts and ChatGPT Work. Also use for model choice\u002Fmigration, prompting, SDKs, Responses, Realtime, agents, evals, and Chat\u002FWork\u002FCodex comparisons. Do not use for generic app\u002Fsoftware tasks that merely mention Codex.","https:\u002F\u002Fgithub.com\u002Frossboyd\u002Fquickque\u002Fblob\u002Fmain\u002F.codex\u002Fskills\u002F.system\u002Fopenai-docs\u002FLICENSE.txt","https:\u002F\u002Fgithub.com\u002Frossboyd\u002Fquickque\u002Fblob\u002Fmain\u002F.codex\u002Fskills\u002F.system\u002Fopenai-docs\u002FSKILL.md",[],[],{"skillNo":96,"name":97,"nameZh":6,"description":98,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":60,"licenseFileUrl":99,"sourceHtmlUrl":100,"categories":101,"keywords":102,"publishedAt":19},"01M7CJRY1FC048P3RF4YQZ6J8B","imagegen","Generate or edit raster images when the task benefits from AI-created bitmap visuals such as photos, illustrations, textures, sprites, mockups, or transparent-background cutouts. Use when Codex should create a brand-new image, transform an existing image, or derive visual variants from references, and the output should be a bitmap asset rather than repo-native code or vector. Do not use when the task is better handled by editing existing SVG\u002Fvector\u002Fcode-native assets, extending an established icon or logo system, or building the visual directly in HTML\u002FCSS\u002Fcanvas.","https:\u002F\u002Fgithub.com\u002Frossboyd\u002Fquickque\u002Fblob\u002Fmain\u002F.codex\u002Fskills\u002F.system\u002Fimagegen\u002FLICENSE.txt","https:\u002F\u002Fgithub.com\u002Frossboyd\u002Fquickque\u002Fblob\u002Fmain\u002F.codex\u002Fskills\u002F.system\u002Fimagegen\u002FSKILL.md",[],[]]