figma-code-connect

---
name: figma-code-connect
description: Generate a Figma Code Connect file (*.figma.tsx) for a design system component
license: MIT
---

## Overview

Generate a `<ComponentName>.figma.tsx` file that connects a React component to its Figma design using the `@figma/code-connect` library.

## Arguments

The user must provide:
1. **Component name** — e.g., `Switch`, `Button`, `Avatar`

The user may optionally provide:
- **Figma URL** — the Figma node URL for the component (from Figma dev mode)
- Figma variant properties and their values
- Which props map to which Figma properties
- Nested component props (e.g., Label, Description sub-layers)

## Figma Design System File

- **File key:** `fsSZONXpVvtrDsCgtu01Jb`
- **URL pattern:** `https://www.figma.com/design/fsSZONXpVvtrDsCgtu01Jb/Synerise-Design-System?node-id=<nodeId>&m=dev`

## Workflow

### Step 1 — Locate the component

Find the component source files:

```
packages/components/<component-name>/src/<ComponentName>.tsx
packages/components/<component-name>/src/<ComponentName>.types.ts
packages/components/<component-name>/src/index.ts
```

Read these files to understand:
- The component's props interface (from `.types.ts`)
- Named exports and default export (from `index.ts` and the main component file)
- What the component renders and how props affect it

### Step 2 — Get Figma structure via MCP

If the Figma MCP server is available (tools like `mcp__figma__get_design_context` exist), use it to get the component details:

1. **If the user provided a Figma URL**, extract `fileKey` and `nodeId` from it.
2. **If no URL was provided**, search for the component using the Figma REST API:
   ```
   curl -s -H "X-Figma-Token: <token>" "https://api.figma.com/v1/files/fsSZONXpVvtrDsCgtu01Jb/component_sets" \
     | python3 -c "import sys,json; [print(json.dumps({...})) for cs in json.load(sys.stdin)['meta']['component_sets'] if '<name>' in cs['name'].lower()]"
   ```
3. **Call `mcp__figma__get_design_context`** with the `nodeId` and `fileKey` to get design context, screenshots, and code suggestions.
4. **If MCP suggests Code Connect mappings** (via `get_code_connect_suggestions`), follow the flow to map sub-components (like Button) and then use the returned design context.

**If the MCP server is NOT available**, fall back to:
- The Figma REST API via curl to get component_sets, component properties, and layer structure
- Ask the user for variant properties and values

### Key Figma properties to extract

From the component set's `componentPropertyDefinitions`:
- **VARIANT** properties — these become `variant: {}` keys in `figma.connect()`
- **BOOLEAN** properties — map with `figma.boolean('PropName', { true: ..., false: ... })`
- **TEXT** properties — map with `figma.string('PropName')` (note: Figma text props often have `✏️` emoji prefix)
- **INSTANCE_SWAP** properties — map with `figma.instance('LayerName')`

From the layer tree (depth exploration):
- Nested instances with their own properties (e.g., Button inside ActionArea)
- Text layers with `componentPropertyReferences` pointing to text properties
- Hidden layers controlled by boolean properties via `refs.visible`

### Step 3 — Generate the Code Connect file

Create `packages/components/<component-name>/src/<ComponentName>.figma.tsx` following these conventions:

#### File structure

```tsx
import figma from '@figma/code-connect';

import ComponentName from './ComponentName';
// Import any additional named exports needed (e.g., RawSwitch, ButtonGroup)

const FIGMA_URL = 'https://www.figma.com/design/fsSZONXpVvtrDsCgtu01Jb/Synerise-Design-System?node-id=<nodeId>&m=dev';

// If there are reusable prop mappings shared across variants, define them as shared objects:
const baseProps = {
  label: figma.boolean('Show Header', {
    true: figma.string('✏️Header Text'),
    false: undefined,
  }),
};

// One figma.connect() call per variant combination that produces meaningfully different code
figma.connect(ComponentName, FIGMA_URL, {
  variant: { State: 'Default' },
  props: baseProps,
  example: (props) => <ComponentName {...mapped props} />,
});
```

#### Figma API mapping reference

Use these `figma.*` helpers to map Figma properties to React props:

| Figma property type | Helper | Example |
|---|---|---|
| String | `figma.string('PropName')` | `figma.string('Text')` |
| Boolean | `figma.boolean('PropName')` | `figma.boolean('Has Icon')` |
| Boolean → conditional | `figma.boolean('PropName', { true: value, false: undefined })` | Show/hide a prop based on Figma toggle |
| Enum → string | `figma.enum('PropName', { 'FigmaValue': 'react-value' })` | `figma.enum('Size', { 'Small': 'S', 'Medium': 'M' })` |
| Enum → boolean | `figma.enum('PropName', { 'Value': true })` | Used when a Figma enum maps to a boolean prop |
| Instance (slot) | `figma.instance('LayerName')` | `figma.instance('Icon')` |
| Children (auto slot) | `figma.children('LayerName')` | `figma.children('*')` for all children |
| Nested props | `figma.nestedProps('LayerName', { ... })` | Access sub-component properties |
| Class name | `figma.className([...])` | Combine into className prop |

#### Key rules

1. **One `figma.connect()` per distinct code output.** If two variant combos produce the same JSX, merge them. If they produce different JSX (different props, different components), keep them separate.
2. **Variant keys and values must match Figma exactly** — they are case-sensitive and may contain spaces.
3. **Use `figma.nestedProps`** when a Figma sub-layer (like `Label` or `Description`) has its own properties you need to access.
4. **Import the actual component** — the `example` must produce valid, copy-pasteable JSX that a developer would actually write.
5. **Boolean props** — if a Figma variant like `State: Selected` maps to a boolean React prop like `checked`, set it directly in the example: `<Switch checked />`.
6. **Disabled state** — if a Figma variant like `State: Disabled` maps to a `disabled` prop, set it directly. For components that pass disabled via sub-props (like `buttonProps`), use the correct nesting.
7. **Shared prop objects** — extract repeated prop configurations into shared const objects (e.g., `baseProps`) to avoid duplication across variant `figma.connect()` calls.
8. **Figma text property names** often have emoji prefixes like `✏️` — include these exactly as they appear in Figma.

### Step 4 — Register Code Connect mappings via MCP

If the MCP server is available and `mcp__figma__send_code_connect_mappings` is accessible:
1. After generating the file, use `get_code_connect_suggestions` to check if sub-components (like Button) need mapping
2. Search the codebase for matching components
3. Present matches to the user for approval
4. Call `send_code_connect_mappings` with the approved mappings

### Step 5 — Validate

After generating the file:
1. Verify the import paths are correct by checking what's exported from the component's `index.ts`
2. Ensure all variant property names and values match what Figma returns (from MCP or REST API)
3. Check that the generated JSX examples are valid and match how the component is actually used (based on its props interface)

### Step 6 — Report

Output:
- The path of the generated file
- A summary of how many `figma.connect()` calls were created and what variant combinations they cover
- Any assumptions made that the user should verify against their Figma file
- Whether Code Connect mappings were sent to Figma for sub-components