From 2bf4cec6323166c312d00541cb59967265927d0c Mon Sep 17 00:00:00 2001 From: Ashwin Mathews Date: Thu, 14 May 2026 22:21:49 -0700 Subject: [PATCH 1/2] figma skills update --- .../figma-code-connect-components/LICENSE.txt | 2 - .../agents/openai.yaml | 4 - .../references/mapping-checklist.md | 7 - .../scripts/normalize_node_id.py | 25 - .../SKILL.md | 252 +++++--- .../references/advanced-patterns.md | 0 .../references/api.md | 12 + .../LICENSE.txt | 2 - .../figma-create-design-system-rules/SKILL.md | 536 ------------------ .../agents/openai.yaml | 4 - .../references/rule-template.md | 15 - .../scripts/check_agents_md.sh | 9 - .../skills/figma-create-new-file/LICENSE.txt | 2 - .../skills/figma-create-new-file/SKILL.md | 20 +- .../figma-create-new-file/agents/openai.yaml | 7 - .../figma-create-new-file/maintainers.yml | 1 - .../skills/figma-generate-design/LICENSE.txt | 2 - .../skills/figma-generate-design/SKILL.md | 148 ++++- .../figma-generate-design/agents/openai.yaml | 4 - .../figma-generate-design/maintainers.yml | 1 - .../skills/figma-generate-diagram/SKILL.md | 111 ++++ .../references/architecture.md | 229 ++++++++ .../figma-generate-diagram/references/erd.md | 329 +++++++++++ .../references/flowchart.md | 407 +++++++++++++ .../references/gantt.md | 260 +++++++++ .../references/sequence.md | 264 +++++++++ .../references/state.md | 327 +++++++++++ .../references/workflow.md | 130 +++++ .../skills/figma-generate-library/LICENSE.txt | 2 - .../skills/figma-generate-library/SKILL.md | 21 +- .../figma-generate-library/agents/openai.yaml | 4 - .../figma-generate-library/maintainers.yml | 3 - .../references/code-connect-setup.md | 10 +- .../references/discovery-phase.md | 47 +- .../references/documentation-creation.md | 108 ++-- .../references/token-creation.md | 2 +- .../scripts/createDocumentationPage.js | 18 +- .../skills/figma-implement-design/LICENSE.txt | 2 - .../skills/figma-implement-design/SKILL.md | 259 --------- .../figma-implement-design/agents/openai.yaml | 4 - .../references/parity-checklist.md | 9 - .../scripts/compare_stub.sh | 5 - .../figma/skills/figma-use-figjam/SKILL.md | 58 ++ .../references/batch-modify.md | 300 ++++++++++ .../references/create-code-block.md | 89 +++ .../references/create-connector.md | 328 +++++++++++ .../references/create-label.md | 276 +++++++++ .../references/create-section.md | 181 ++++++ .../references/create-shape-with-text.md | 358 ++++++++++++ .../references/create-sticky.md | 287 ++++++++++ .../references/create-table.md | 345 +++++++++++ .../references/create-text.md | 466 +++++++++++++++ .../figma-use-figjam/references/edit-text.md | 362 ++++++++++++ .../references/figjam-colors.md | 187 ++++++ .../references/plan-board-content.md | 332 +++++++++++ .../references/position-figjam-nodes.md | 90 +++ .../figma/skills/figma-use-slides/SKILL.md | 138 +++++ .../references/slide-content.md | 134 +++++ .../references/slide-design.md | 121 ++++ .../references/slide-gotchas.md | 120 ++++ .../figma-use-slides/references/slide-grid.md | 86 +++ .../references/slide-lifecycle.md | 62 ++ .../references/slide-properties.md | 72 +++ plugins/figma/skills/figma-use/LICENSE.txt | 2 - plugins/figma/skills/figma-use/SKILL.md | 199 ++++++- .../figma/skills/figma-use/agents/openai.yaml | 4 - .../figma/skills/figma-use/maintainers.yml | 1 - .../figma-use/references/api-reference.md | 26 +- .../figma-use/references/common-patterns.md | 7 +- .../references/component-patterns.md | 82 +++ .../skills/figma-use/references/gotchas.md | 170 ++++-- .../figma-use/references/maintainers.yml | 12 - .../references/plugin-api-patterns.md | 27 +- .../references/plugin-api-standalone.d.ts | 135 +++++ .../references/plugin-api-standalone.index.md | 28 + .../references/text-style-patterns.md | 37 +- .../maintainers.yml | 9 - .../wwds-text-styles.md | 19 +- 78 files changed, 7479 insertions(+), 1275 deletions(-) delete mode 100644 plugins/figma/skills/figma-code-connect-components/LICENSE.txt delete mode 100644 plugins/figma/skills/figma-code-connect-components/agents/openai.yaml delete mode 100644 plugins/figma/skills/figma-code-connect-components/references/mapping-checklist.md delete mode 100755 plugins/figma/skills/figma-code-connect-components/scripts/normalize_node_id.py rename plugins/figma/skills/{figma-code-connect-components => figma-code-connect}/SKILL.md (56%) rename plugins/figma/skills/{figma-code-connect-components => figma-code-connect}/references/advanced-patterns.md (100%) rename plugins/figma/skills/{figma-code-connect-components => figma-code-connect}/references/api.md (97%) delete mode 100644 plugins/figma/skills/figma-create-design-system-rules/LICENSE.txt delete mode 100644 plugins/figma/skills/figma-create-design-system-rules/SKILL.md delete mode 100644 plugins/figma/skills/figma-create-design-system-rules/agents/openai.yaml delete mode 100644 plugins/figma/skills/figma-create-design-system-rules/references/rule-template.md delete mode 100755 plugins/figma/skills/figma-create-design-system-rules/scripts/check_agents_md.sh delete mode 100644 plugins/figma/skills/figma-create-new-file/LICENSE.txt delete mode 100644 plugins/figma/skills/figma-create-new-file/agents/openai.yaml delete mode 100644 plugins/figma/skills/figma-create-new-file/maintainers.yml delete mode 100644 plugins/figma/skills/figma-generate-design/LICENSE.txt delete mode 100644 plugins/figma/skills/figma-generate-design/agents/openai.yaml delete mode 100644 plugins/figma/skills/figma-generate-design/maintainers.yml create mode 100644 plugins/figma/skills/figma-generate-diagram/SKILL.md create mode 100644 plugins/figma/skills/figma-generate-diagram/references/architecture.md create mode 100644 plugins/figma/skills/figma-generate-diagram/references/erd.md create mode 100644 plugins/figma/skills/figma-generate-diagram/references/flowchart.md create mode 100644 plugins/figma/skills/figma-generate-diagram/references/gantt.md create mode 100644 plugins/figma/skills/figma-generate-diagram/references/sequence.md create mode 100644 plugins/figma/skills/figma-generate-diagram/references/state.md create mode 100644 plugins/figma/skills/figma-generate-diagram/references/workflow.md delete mode 100644 plugins/figma/skills/figma-generate-library/LICENSE.txt delete mode 100644 plugins/figma/skills/figma-generate-library/agents/openai.yaml delete mode 100644 plugins/figma/skills/figma-generate-library/maintainers.yml delete mode 100644 plugins/figma/skills/figma-implement-design/LICENSE.txt delete mode 100644 plugins/figma/skills/figma-implement-design/SKILL.md delete mode 100644 plugins/figma/skills/figma-implement-design/agents/openai.yaml delete mode 100644 plugins/figma/skills/figma-implement-design/references/parity-checklist.md delete mode 100755 plugins/figma/skills/figma-implement-design/scripts/compare_stub.sh create mode 100644 plugins/figma/skills/figma-use-figjam/SKILL.md create mode 100644 plugins/figma/skills/figma-use-figjam/references/batch-modify.md create mode 100644 plugins/figma/skills/figma-use-figjam/references/create-code-block.md create mode 100644 plugins/figma/skills/figma-use-figjam/references/create-connector.md create mode 100644 plugins/figma/skills/figma-use-figjam/references/create-label.md create mode 100644 plugins/figma/skills/figma-use-figjam/references/create-section.md create mode 100644 plugins/figma/skills/figma-use-figjam/references/create-shape-with-text.md create mode 100644 plugins/figma/skills/figma-use-figjam/references/create-sticky.md create mode 100644 plugins/figma/skills/figma-use-figjam/references/create-table.md create mode 100644 plugins/figma/skills/figma-use-figjam/references/create-text.md create mode 100644 plugins/figma/skills/figma-use-figjam/references/edit-text.md create mode 100644 plugins/figma/skills/figma-use-figjam/references/figjam-colors.md create mode 100644 plugins/figma/skills/figma-use-figjam/references/plan-board-content.md create mode 100644 plugins/figma/skills/figma-use-figjam/references/position-figjam-nodes.md create mode 100644 plugins/figma/skills/figma-use-slides/SKILL.md create mode 100644 plugins/figma/skills/figma-use-slides/references/slide-content.md create mode 100644 plugins/figma/skills/figma-use-slides/references/slide-design.md create mode 100644 plugins/figma/skills/figma-use-slides/references/slide-gotchas.md create mode 100644 plugins/figma/skills/figma-use-slides/references/slide-grid.md create mode 100644 plugins/figma/skills/figma-use-slides/references/slide-lifecycle.md create mode 100644 plugins/figma/skills/figma-use-slides/references/slide-properties.md delete mode 100644 plugins/figma/skills/figma-use/LICENSE.txt delete mode 100644 plugins/figma/skills/figma-use/agents/openai.yaml delete mode 100644 plugins/figma/skills/figma-use/maintainers.yml delete mode 100644 plugins/figma/skills/figma-use/references/maintainers.yml delete mode 100644 plugins/figma/skills/figma-use/references/working-with-design-systems/maintainers.yml diff --git a/plugins/figma/skills/figma-code-connect-components/LICENSE.txt b/plugins/figma/skills/figma-code-connect-components/LICENSE.txt deleted file mode 100644 index 5dcf1aa2..00000000 --- a/plugins/figma/skills/figma-code-connect-components/LICENSE.txt +++ /dev/null @@ -1,2 +0,0 @@ -Use of these Figma skills and related files ("Materials") is governed by the Figma Developer Terms (available at https://www.figma.com/legal/developer-terms/). By accessing, downloading, or using these Materials — including through automated systems or AI agents — you agree to the Figma Developer Terms. -These Materials are currently offered as a Beta feature. Figma may modify, suspend, or discontinue them at any time without notice. diff --git a/plugins/figma/skills/figma-code-connect-components/agents/openai.yaml b/plugins/figma/skills/figma-code-connect-components/agents/openai.yaml deleted file mode 100644 index 9c4f12b6..00000000 --- a/plugins/figma/skills/figma-code-connect-components/agents/openai.yaml +++ /dev/null @@ -1,4 +0,0 @@ -interface: - display_name: "Code Connect" - short_description: "Create parserless Figma Code Connect templates" - default_prompt: "Find matching local components for these Figma nodes and create Code Connect templates." diff --git a/plugins/figma/skills/figma-code-connect-components/references/mapping-checklist.md b/plugins/figma/skills/figma-code-connect-components/references/mapping-checklist.md deleted file mode 100644 index 8f4f0264..00000000 --- a/plugins/figma/skills/figma-code-connect-components/references/mapping-checklist.md +++ /dev/null @@ -1,7 +0,0 @@ -# Code Connect Mapping Checklist - -- Confirm Figma component is published -- Convert URL node-id (`-`) to tool nodeId (`:`) -- Check existing mappings first -- Compare props/variants between design and code -- Ask for confirmation when multiple matches are plausible diff --git a/plugins/figma/skills/figma-code-connect-components/scripts/normalize_node_id.py b/plugins/figma/skills/figma-code-connect-components/scripts/normalize_node_id.py deleted file mode 100755 index 31b8ef80..00000000 --- a/plugins/figma/skills/figma-code-connect-components/scripts/normalize_node_id.py +++ /dev/null @@ -1,25 +0,0 @@ -#!/usr/bin/env python3 -"""Normalize a Figma node-id between URL and tool formats.""" - -from __future__ import annotations - -import sys - - -def main() -> int: - if len(sys.argv) != 2: - print("Usage: normalize_node_id.py ", file=sys.stderr) - return 2 - node = sys.argv[1].strip() - if not node: - print("Empty node-id", file=sys.stderr) - return 1 - if ":" in node: - print(node.replace(":", "-")) - else: - print(node.replace("-", ":")) - return 0 - - -if __name__ == "__main__": - raise SystemExit(main()) diff --git a/plugins/figma/skills/figma-code-connect-components/SKILL.md b/plugins/figma/skills/figma-code-connect/SKILL.md similarity index 56% rename from plugins/figma/skills/figma-code-connect-components/SKILL.md rename to plugins/figma/skills/figma-code-connect/SKILL.md index d27f609b..2394c2ce 100644 --- a/plugins/figma/skills/figma-code-connect-components/SKILL.md +++ b/plugins/figma/skills/figma-code-connect/SKILL.md @@ -1,14 +1,16 @@ --- name: figma-code-connect -description: 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/update .figma.js files. +description: 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/update .figma.ts or .figma.js files. disable-model-invocation: false --- +# Code Connect + ## Overview -Create parserless Code Connect template files (`.figma.js`) that map Figma components to code snippets. Given a Figma URL, follow the steps below to create a template. +Create 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. -> **Note:** This project may also contain parser-based `.figma.tsx` files (using `figma.connect()`, published via CLI). This skill covers **parserless templates only** — `.figma.js` files that use the MCP tools to fetch component context from Figma. +> **Note:** This project may also contain parser-based `.figma.tsx` files (using `figma.connect()`, published via CLI). This skill covers **templates files only** — `.figma.ts` files that use the MCP tools to fetch component context from Figma. ## Prerequisites @@ -16,6 +18,14 @@ Create parserless Code Connect template files (`.figma.js`) that map Figma compo - **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. - **Organization or Enterprise plan required** — Code Connect is not available on Free or Professional plans. - **URL must include `node-id`** — the Figma URL must contain the `node-id` query parameter. +- **TypeScript types** — for editor autocomplete and type checking in `.figma.ts` files `@figma/code-connect/figma-types` must be added to `types` in `tsconfig.json`: + ```json + { + "compilerOptions": { + "types": ["@figma/code-connect/figma-types"] + } + } + ``` ## Step 1: Parse the Figma URL @@ -64,7 +74,8 @@ The response contains the Figma component's **property definitions** — note ea - **TEXT** — text content (labels, titles, placeholders) - **BOOLEAN** — toggles (show/hide icon, disabled state) - **VARIANT** — enum options (size, variant, state) -- **INSTANCE_SWAP** — swappable component slots (icon, avatar) +- **INSTANCE_SWAP** — swappable nested instances tied to a specific component (icon, avatar) +- **SLOT** — flexible content regions (freeform layout, mixed children); use `getSlot()` in templates (not the same as INSTANCE_SWAP) Save this property list — you will use it in Step 5 to write the template. @@ -84,28 +95,28 @@ Read `figma.config.json` for import path aliases — the `importPaths` section m Read the code component's source to understand its props interface — this informs how to map Figma properties to code props in Step 5. -## Step 5: Create the Parserless Template (.figma.js) +## Step 5: Create the Template File (.figma.ts) ### File location -Place the file alongside existing Code Connect templates (`.figma.tsx` or `.figma.js` files). Check `figma.config.json` `include` patterns for the correct directory. Name it `ComponentName.figma.js`. +Place the file alongside existing Code Connect templates (`.figma.tsx` or `.figma.ts` files). Check `figma.config.json` `include` patterns for the correct directory. Name it `ComponentName.figma.ts`. ### Template structure -Every parserless template follows this structure: +Every template file follows this structure: -```js +```ts // url=https://www.figma.com/file/{fileKey}/{fileName}?node-id={nodeId} // source={path to code component from Step 4} // component={code component name from Step 4} -const figma = require('figma') +import figma from 'figma' const instance = figma.selectedInstance // Extract properties from the Figma component (see property mapping below) // ... export default { - example: figma.tsx``, // Required: code snippet + example: figma.code``, // Required: code snippet imports: ['import { Component } from "..."'], // Optional: import statements id: 'component-name', // Required: unique identifier metadata: { // Optional @@ -124,17 +135,18 @@ Use the property list from Step 3 to extract values. For each Figma property typ | TEXT | `instance.getString('Name')` | Labels, titles, placeholder text | | BOOLEAN | `instance.getBoolean('Name', { true: ..., false: ... })` | Toggle visibility, conditional props | | VARIANT | `instance.getEnum('Name', { 'FigmaVal': 'codeVal' })` | Size, variant, state enums | -| INSTANCE_SWAP | `instance.getInstanceSwap('Name')` | Icon slots, swappable children | +| INSTANCE_SWAP | `instance.getInstanceSwap('Name')` | Swapped instance for a fixed component slot (then `hasCodeConnect()` / `executeTemplate()`) - do not confuse with the SLOT property below | +| SLOT | `instance.getSlot('Name')` | Freeform slot content only when the Figma property type is **SLOT** | (child layer) | `instance.findInstance('LayerName')` | Named child instances without a property | | (text layer) | `instance.findText('LayerName')` → `.textContent` | Text content from named layers | **TEXT** — get the string value directly: -```js +```ts const label = instance.getString('Label') ``` **VARIANT** — map Figma enum values to code values: -```js +```ts const variant = instance.getEnum('Variant', { 'Primary': 'primary', 'Secondary': 'secondary', @@ -148,31 +160,84 @@ const size = instance.getEnum('Size', { ``` **BOOLEAN** — simple boolean or mapped to values: -```js +```ts // Simple boolean const disabled = instance.getBoolean('Disabled') -// Mapped to code values -const hasIcon = instance.getBoolean('Has Icon', { - true: figma.tsx``, - false: undefined, +// Mapped to code values (e.g. when the code prop is an enum, not a boolean) +const size = instance.getBoolean('Show Label', { true: 'large', false: 'small' }) +``` + +**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. + +### Exhaustive variant handling + +When 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. + +```ts +// WRONG — omits 'Warning', which will render as undefined +const status = instance.getEnum('Status', { + 'Success': 'success', + 'Error': 'error', }) + +// CORRECT — every value is mapped +const status = instance.getEnum('Status', { + 'Success': 'success', + 'Error': 'error', + 'Warning': 'warning', + 'Info': 'info', +}) +``` + +When **two or more VARIANT properties combine** to produce different code output, generate exhaustive conditional branches. For example, 2 variants × 2 values = 4 branches: + +```ts +const type = instance.getEnum('Type', { 'Filled': 'filled', 'Outlined': 'outlined' }) +const status = instance.getEnum('Status', { 'Success': 'success', 'Error': 'error' }) + +let colorClass +if (type === 'filled' && status === 'success') { + colorClass = 'bg-green-500 text-white' +} else if (type === 'filled' && status === 'error') { + colorClass = 'bg-red-500 text-white' +} else if (type === 'outlined' && status === 'success') { + colorClass = 'bg-transparent border-green-500' +} else if (type === 'outlined' && status === 'error') { + colorClass = 'bg-transparent border-red-500' +} ``` +If 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. + **INSTANCE_SWAP** — access swappable component instances: -```js +```ts const icon = instance.getInstanceSwap('Icon') let iconCode -if (icon && icon.hasCodeConnect()) { +if (icon && icon.type === 'INSTANCE') { iconCode = icon.executeTemplate().example } ``` +**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. + +- **Signature:** `getSlot(propName: string): ResultSection[] | undefined` +```ts +// Figma property "Content" must be type SLOT in component properties +const content = instance.getSlot('Content') + +export default { + example: figma.code`${content}`, + // ... +} +``` + ### Interpolation in tagged templates When interpolating values in tagged templates, use the correct wrapping: - **String values** (`getString`, `getEnum`, `textContent`): wrap in quotes → `variant="${variant}"` - **Instance/section values** (`executeTemplate().example`): wrap in braces → `icon={${iconCode}}` +- **Slot sections** (`getSlot()` result — `ResultSection[] | undefined`): interpolate directly inside `` figma.code`...` `` (same shape as nested snippet sections), e.g. `` figma.code`` `` — do not treat as a plain string - **Boolean bare props**: use conditional → `${disabled ? 'disabled' : ''}` ### Finding descendant layers @@ -181,38 +246,63 @@ When you need to access children that aren't exposed as component properties: | Method | Use when | |---|---| -| `instance.getInstanceSwap('PropName')` | A component property exists for this slot | +| `instance.getInstanceSwap('PropName')` | Figma property type is **INSTANCE_SWAP** (fixed swapped instance) | +| `instance.getSlot('PropName')` | Figma property type is **SLOT** (freeform content region) | | `instance.findInstance('LayerName')` | You know the child layer name (no component property) | | `instance.findText('LayerName')` → `.textContent` | You need text content from a named text layer | | `instance.findConnectedInstance('id')` | You know the child's Code Connect `id` | | `instance.findConnectedInstances(fn)` | You need multiple connected children matching a filter | | `instance.findLayers(fn)` | You need any layers (text + instances) matching a filter | +### Nested configurable instances + +A 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. + +1. **Check whether the child already has a Code Connect template** — use `get_code_connect_suggestions` or check existing `.figma.ts` files in the project. +2. **If no template exists, create one** for the child so it renders correctly both standalone and when nested. +3. **Reference the child from the parent** using `findInstance()` or `findConnectedInstance()`, then call `executeTemplate()`. + +```ts +// Parent template — the Badge child isn't a prop, but it's configurable +const badge = instance.findInstance('Status Badge') +let badgeCode +if (badge && badge.type === 'INSTANCE') { + badgeCode = badge.executeTemplate().example +} + +export default { + example: figma.code`${badgeCode}`, + // ... +} +``` + +This 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. + ### Nested component example For multi-level nested components or metadata prop passing between templates, see [advanced-patterns.md](references/advanced-patterns.md). -```js +```ts const icon = instance.getInstanceSwap('Icon') let iconSnippet -if (icon && icon.hasCodeConnect()) { +if (icon && icon.type === 'INSTANCE') { iconSnippet = icon.executeTemplate().example } export default { - example: figma.tsx``, + example: figma.code``, // ... } ``` ### Conditional props -```js +```ts const variant = instance.getEnum('Variant', { 'Primary': 'primary', 'Secondary': 'secondary' }) const disabled = instance.getBoolean('Disabled') export default { - example: figma.tsx` + example: figma.code` ` + + // CORRECT — resolves dynamically, works for any swapped icon + const icon = instance.findInstance('Icon') + let iconCode + if (icon && icon.type === 'INSTANCE') { + iconCode = icon.executeTemplate().example + } + example: figma.code`...` ``` +8. **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. + ## Complete Worked Example Given URL: `https://figma.com/design/abc123/MyFile?node-id=42-100` @@ -355,13 +473,13 @@ Response includes properties: **Step 4:** Search codebase → find `Button` component. Read its source to confirm props: `variant`, `size`, `disabled`, `icon`, `children`. Import path: `"primitives"`. -**Step 5:** Create `src/figma/primitives/Button.figma.js`: +**Step 5:** Create `src/figma/primitives/Button.figma.ts`: -```js +```ts // url=https://figma.com/design/abc123/MyFile?node-id=42-100 // source=src/components/Button.tsx // component=Button -const figma = require('figma') +import figma from 'figma' const instance = figma.selectedInstance const label = instance.getString('Label') @@ -378,17 +496,17 @@ const disabled = instance.getBoolean('Disabled') const hasIcon = instance.getBoolean('Has Icon') const icon = hasIcon ? instance.getInstanceSwap('Icon') : null let iconCode -if (icon && icon.hasCodeConnect()) { +if (icon && icon.type === 'INSTANCE') { iconCode = icon.executeTemplate().example } export default { - example: figma.tsx` + example: figma.code` diff --git a/plugins/figma/skills/figma-code-connect-components/references/advanced-patterns.md b/plugins/figma/skills/figma-code-connect/references/advanced-patterns.md similarity index 100% rename from plugins/figma/skills/figma-code-connect-components/references/advanced-patterns.md rename to plugins/figma/skills/figma-code-connect/references/advanced-patterns.md diff --git a/plugins/figma/skills/figma-code-connect-components/references/api.md b/plugins/figma/skills/figma-code-connect/references/api.md similarity index 97% rename from plugins/figma/skills/figma-code-connect-components/references/api.md rename to plugins/figma/skills/figma-code-connect/references/api.md index 9ab37f40..fe74f311 100644 --- a/plugins/figma/skills/figma-code-connect-components/references/api.md +++ b/plugins/figma/skills/figma-code-connect/references/api.md @@ -281,6 +281,18 @@ if (icon) { } ``` +#### `getSlot(propName: string): ResultSection[] | undefined` + +Reads a Figma component property whose type is **`SLOT`** (not **INSTANCE_SWAP**). Returns a `ResultSection[]` containing a slot section (`type: 'SLOT'`). Returns `undefined` if the property is missing or invalid. Do not call `executeTemplate()` on this value — unlike `getInstanceSwap()`, it is not an `InstanceHandle`. + +```javascript +const content = instance.getSlot('Content') + +export default { + example: figma.code`${content}` +} +``` + #### `getPropertyValue(propName: string): string | boolean` Gets the raw property value without mapping. diff --git a/plugins/figma/skills/figma-create-design-system-rules/LICENSE.txt b/plugins/figma/skills/figma-create-design-system-rules/LICENSE.txt deleted file mode 100644 index 5dcf1aa2..00000000 --- a/plugins/figma/skills/figma-create-design-system-rules/LICENSE.txt +++ /dev/null @@ -1,2 +0,0 @@ -Use of these Figma skills and related files ("Materials") is governed by the Figma Developer Terms (available at https://www.figma.com/legal/developer-terms/). By accessing, downloading, or using these Materials — including through automated systems or AI agents — you agree to the Figma Developer Terms. -These Materials are currently offered as a Beta feature. Figma may modify, suspend, or discontinue them at any time without notice. diff --git a/plugins/figma/skills/figma-create-design-system-rules/SKILL.md b/plugins/figma/skills/figma-create-design-system-rules/SKILL.md deleted file mode 100644 index b4b8eea8..00000000 --- a/plugins/figma/skills/figma-create-design-system-rules/SKILL.md +++ /dev/null @@ -1,536 +0,0 @@ ---- -name: figma-create-design-system-rules -description: Generates custom design system rules for the user's codebase. Use when user says "create design system rules", "generate rules for my project", "set up design rules", "customize design system guidelines", or wants to establish project-specific conventions for Figma-to-code workflows. Requires Figma MCP server connection. -disable-model-invocation: false ---- - -# Create Design System Rules - -## Overview - -This skill helps you generate custom design system rules tailored to your project's specific needs. These rules guide AI coding agents to produce consistent, high-quality code when implementing Figma designs, ensuring that your team's conventions, component patterns, and architectural decisions are followed automatically. - -### Supported Rule Files - -| Agent | Rule File | -|-------|-----------| -| Codex CLI | `AGENTS.md` | -| Cursor | `.cursor/rules/figma-design-system.mdc` | - -## What Are Design System Rules? - -Design system rules are project-level instructions that encode the "unwritten knowledge" of your codebase - the kind of expertise that experienced developers know and would pass on to new team members: - -- Which layout primitives and components to use -- Where component files should be located -- How components should be named and structured -- What should never be hardcoded -- How to handle design tokens and styling -- Project-specific architectural patterns - -Once defined, these rules dramatically reduce repetitive prompting and ensure consistent output across all Figma implementation tasks. - -## Prerequisites - -- Figma MCP server must be connected and accessible -- Access to the project codebase for analysis -- Understanding of your team's component conventions (or willingness to establish them) - -## When to Use This Skill - -Use this skill when: - -- Starting a new project that will use Figma designs -- Onboarding an AI coding agent to an existing project with established patterns -- Standardizing Figma-to-code workflows across your team -- Updating or refining existing design system conventions -- Users explicitly request: "create design system rules", "set up Figma guidelines", "customize rules for my project" - -## Required Workflow - -**Follow these steps in order. Do not skip steps.** - -### Step 1: Run the Create Design System Rules Tool - -Call the Figma MCP server's `create_design_system_rules` tool to get the foundational prompt and template. - -**Parameters:** - -- `clientLanguages`: Comma-separated list of languages used in the project (e.g., "typescript,javascript", "python", "javascript") -- `clientFrameworks`: Framework being used (e.g., "react", "vue", "svelte", "angular", "unknown") - -This tool returns guidance and a template for creating design system rules. - -Structure your design system rules following the template format provided in the tool's response. - -### Step 2: Analyze the Codebase - -Before finalizing rules, analyze the project to understand existing patterns: - -**Component Organization:** - -- Where are UI components located? (e.g., `src/components/`, `app/ui/`, `lib/components/`) -- Is there a dedicated design system directory? -- How are components organized? (by feature, by type, flat structure) - -**Styling Approach:** - -- What CSS framework or approach is used? (Tailwind, CSS Modules, styled-components, etc.) -- Where are design tokens defined? (CSS variables, theme files, config files) -- Are there existing color, typography, or spacing tokens? - -**Component Patterns:** - -- What naming conventions are used? (PascalCase, kebab-case, prefixes) -- How are component props typically structured? -- Are there common composition patterns? - -**Architecture Decisions:** - -- How is state management handled? -- What routing system is used? -- Are there specific import patterns or path aliases? - -### Step 3: Generate Project-Specific Rules - -Based on your codebase analysis, create a comprehensive set of rules. Include: - -#### General Component Rules - -```markdown -- IMPORTANT: Always use components from `[YOUR_PATH]` when possible -- Place new UI components in `[COMPONENT_DIRECTORY]` -- Follow `[NAMING_CONVENTION]` for component names -- Components must export as `[EXPORT_PATTERN]` -``` - -#### Styling Rules - -```markdown -- Use `[CSS_FRAMEWORK/APPROACH]` for styling -- Design tokens are defined in `[TOKEN_LOCATION]` -- IMPORTANT: Never hardcode colors - always use tokens from `[TOKEN_FILE]` -- Spacing values must use the `[SPACING_SYSTEM]` scale -- Typography follows the scale defined in `[TYPOGRAPHY_LOCATION]` -``` - -#### Figma MCP Integration Rules - -```markdown -## Figma MCP Integration Rules - -These rules define how to translate Figma inputs into code for this project and must be followed for every Figma-driven change. - -### Required Flow (do not skip) - -1. Run get_design_context first to fetch the structured representation for the exact node(s) -2. If the response is too large or truncated, run get_metadata to get the high-level node map, then re-fetch only the required node(s) with get_design_context -3. Run get_screenshot for a visual reference of the node variant being implemented -4. Only after you have both get_design_context and get_screenshot, download any assets needed and start implementation -5. Translate the output (usually React + Tailwind) into this project's conventions, styles, and framework -6. Validate against Figma for 1:1 look and behavior before marking complete - -### Implementation Rules - -- Treat the Figma MCP output (React + Tailwind) as a representation of design and behavior, not as final code style -- Replace Tailwind utility classes with `[YOUR_STYLING_APPROACH]` when applicable -- Reuse existing components from `[COMPONENT_PATH]` instead of duplicating functionality -- Use the project's color system, typography scale, and spacing tokens consistently -- Respect existing routing, state management, and data-fetch patterns -- Strive for 1:1 visual parity with the Figma design -- Validate the final UI against the Figma screenshot for both look and behavior -``` - -#### Asset Handling Rules - -```markdown -## Asset Handling - -- The Figma MCP server provides an assets endpoint which can serve image and SVG assets -- IMPORTANT: If the Figma MCP server returns a localhost source for an image or SVG, use that source directly -- IMPORTANT: DO NOT import/add new icon packages - all assets should be in the Figma payload -- IMPORTANT: DO NOT use or create placeholders if a localhost source is provided -- Store downloaded assets in `[ASSET_DIRECTORY]` -``` - -#### Project-Specific Conventions - -```markdown -## Project-Specific Conventions - -- [Add any unique architectural patterns] -- [Add any special import requirements] -- [Add any testing requirements] -- [Add any accessibility standards] -- [Add any performance considerations] -``` - -### Step 4: Save Rules to the Appropriate Rule File - -Detect which AI coding agent the user is working with and save the generated rules to the corresponding file: - -| Agent | Rule File | Notes | -|-------|-----------|-------| -| Codex CLI | `AGENTS.md` in project root | Markdown format. Append as a new section if file already exists. 32 KiB combined size limit. | -| Cursor | `.cursor/rules/figma-design-system.mdc` | Markdown with YAML frontmatter (`description`, `globs`, `alwaysApply`). | - -If unsure which agent the user is working with, check for existing rule files in the project or ask the user. - -For Cursor, wrap the rules with YAML frontmatter: - -```markdown ---- -description: Rules for implementing Figma designs using the Figma MCP server. Covers component organization, styling conventions, design tokens, asset handling, and the required Figma-to-code workflow. -globs: "src/components/**" -alwaysApply: false ---- - -[Generated rules here] -``` - -Customize the `globs` pattern to match the directories where Figma-derived code will live in the project (e.g., `"src/**/*.tsx"` or `["src/components/**", "src/pages/**"]`). - -After saving, the rules will be automatically loaded by the agent and applied to all Figma implementation tasks. - -### Step 5: Validate and Iterate - -After creating rules: - -1. Test with a simple Figma component implementation -2. Verify the agent follows the rules correctly -3. Refine any rules that aren't working as expected -4. Share with team members for feedback -5. Update rules as the project evolves - -## Rule Categories and Examples - -### Essential Rules (Always Include) - -**Component Discovery:** - -```markdown -- UI components are located in `src/components/ui/` -- Feature components are in `src/components/features/` -- Layout primitives are in `src/components/layout/` -``` - -**Design Token Usage:** - -```markdown -- Colors are defined as CSS variables in `src/styles/tokens.css` -- Never hardcode hex colors - use `var(--color-*)` tokens -- Spacing uses the 4px base scale: `--space-1` (4px), `--space-2` (8px), etc. -``` - -**Styling Approach:** - -```markdown -- Use Tailwind utility classes for styling -- Custom styles go in component-level CSS modules -- Theme customization is in `tailwind.config.js` -``` - -### Recommended Rules (Highly Valuable) - -**Component Patterns:** - -```markdown -- All components must accept a `className` prop for composition -- Variant props should use union types: `variant: 'primary' | 'secondary'` -- Icon components should accept `size` and `color` props -``` - -**Import Conventions:** - -```markdown -- Use path aliases: `@/components`, `@/styles`, `@/utils` -- Group imports: React, third-party, internal, types -- No relative imports beyond parent directory -``` - -**Code Quality:** - -```markdown -- Add JSDoc comments for exported components -- Include PropTypes or TypeScript types for all props -- Extract magic numbers to named constants -``` - -### Optional Rules (Project-Specific) - -**Accessibility:** - -```markdown -- All interactive elements must have aria-labels -- Color contrast must meet WCAG AA standards -- Keyboard navigation required for all interactions -``` - -**Performance:** - -```markdown -- Lazy load images with the `Image` component from `@/components/Image` -- Use React.memo for components that receive complex props -- Icons should be SVG components, not icon fonts -``` - -**Testing:** - -```markdown -- Include unit tests for new components in `__tests__/` directory -- Use Testing Library queries (getByRole, getByLabelText) -- Test all interactive states and variants -``` - -## Examples - -### Example 1: React + Tailwind Project - -User says: "Create design system rules for my React project" - -**Actions:** - -1. Run `create_design_system_rules(clientLanguages="typescript,javascript", clientFrameworks="react")` -2. Analyze codebase structure -3. Generate rules: - -```markdown -# Figma MCP Integration Rules - -## Component Organization - -- UI components are in `src/components/ui/` -- Page components are in `src/app/` -- Use Tailwind for styling - -## Figma Implementation Flow - -1. Run get_design_context for the node -2. Run get_screenshot for visual reference -3. Map Figma colors to Tailwind colors defined in `tailwind.config.js` -4. Reuse components from `src/components/ui/` when possible -5. Validate against screenshot before completing - -## Styling Rules - -- IMPORTANT: Use Tailwind utility classes, not inline styles -- Colors are defined in `tailwind.config.js` theme.colors -- Spacing uses Tailwind's default scale -- Custom components go in `src/components/ui/` - -## Asset Rules - -- IMPORTANT: Use localhost sources from Figma MCP server directly -- Store static assets in `public/assets/` -- DO NOT install new icon libraries -``` - -4. Save to the appropriate rule file for the user's agent -5. Test with a simple button implementation - -**Result:** The agent now consistently follows the project's conventions when implementing Figma designs. - -### Example 2: Vue + Custom CSS Project - -User says: "Set up Figma rules for my Vue app" - -**Actions:** - -1. Run `create_design_system_rules(clientLanguages="typescript,javascript", clientFrameworks="vue")` -2. Discover that project uses CSS modules and a custom design token system -3. Generate rules: - -```markdown -# Figma MCP Integration Rules - -## Component Organization - -- Components are in `src/components/` -- Composables are in `src/composables/` -- Vue SFC structure: