kata-mcp-figma-extract

---
name: kata-mcp-figma-extract
description: "Extract design tokens and specs from Figma via MCP. Extraction of design tokens (colors, spacing, typography) and component specifications from a Figma file via MCP server"
---

# Kata: Extract design tokens and specs from Figma via MCP

> **Prefix:** `kata-` | **Type:** Repeatable Skill | **Scope:** Extraction of design tokens (colors, spacing, typography) and component specifications from a Figma file via MCP server

## Workflow

```
Progress:
- [ ] 1. Verify MCP preconditions and directives
- [ ] 2. Identify file and scope
- [ ] 3. Extract design tokens (if requested)
- [ ] 4. Extract component specs (if requested)
- [ ] 5. Generate output files
- [ ] 6. Report result
```

### Step 1: Verify MCP preconditions and directives

1. Consult `.ahrena/.directives` per `lex-directives`.
2. Verify that `figma` is listed in `mcp.servers` (per `lex-mcp`). If not, inform the user and stop.
3. Confirm that the `FIGMA_API_KEY` environment variable is defined. If not, inform the user which variable to configure and stop.
4. Consult `codex-mcp-figma` to identify the correct tools and parameters.

### Step 2: Identify file and scope

1. Confirm the File ID with the user (request if not provided).
2. If specific Node IDs are provided, verify they exist in the file via `get_node`.
3. Define the destination directory: `docs/design/` by default, or the value provided by the user. Create the directory if it does not exist.

### Step 3: Extract design tokens (if requested)

1. Call `get_local_variables(file_key="{FILE_ID}")` to get all file variables.
2. Organize variables by type: `COLOR`, `FLOAT`, `STRING`, `BOOLEAN`.
3. For `COLOR` type variables: convert `r/g/b/a` values (0–1) to hexadecimal (`#RRGGBB` or `#RRGGBBAA`).
4. Map variable names to token structure (e.g., `Color/Primary/500` → `color.primary.500`): replace `/` with `.` and convert to kebab-case.
5. Generate the JSON token object in this format:
   ```json
   {
     "color": { "primary": { "500": { "value": "#3380FF", "type": "color" } } },
     "spacing": { "4": { "value": "16", "type": "spacing" } }
   }
   ```

### Step 4: Extract component specs (if requested)

1. If specific Node IDs were provided: call `get_node` for each one.
2. If not provided: call `get_file_components(file_key="{FILE_ID}")` to list all components.
3. For each relevant component, extract:
   - Name, description (if available)
   - Dimensions (width, height)
   - Variant properties (if it's a component set: call `get_component_set`)
   - Applied styles (typography, color, effects)
4. Structure specs in Markdown with sections per component.

### Step 5: Generate output files

1. **Tokens:** save the generated JSON to `{destination}/tokens.json`.
2. **Specs:** save the specification Markdown to `{destination}/components.md`.
3. Add metadata header to generated files:
   ```
   <!-- Auto-generated by kata-mcp-figma-extract -->
   <!-- Figma file: {FILE_ID} | Date: {ISO-DATE} -->
   ```

### Step 6: Report result

1. Present summary: tokens extracted by type (colors, spacing, typography), components documented.
2. List generated files with their relative paths.
3. In case of partial failure, indicate which extractions failed and why.

## Outputs

| Output | Format | Destination |
|--------|--------|-------------|
| Design tokens | JSON (nested structure by type) | `docs/design/tokens.json` |
| Component specs | Markdown | `docs/design/components.md` |
| Extraction report | Structured text (tokens by type, components documented) | Response to user |

## Restrictions

- **Use MCP only:** never use the Figma REST API directly; always use MCP server tools (per `lex-mcp`).
- **No hardcoded credentials:** authentication exclusively via `FIGMA_API_KEY` environment variable.
- **Read-only:** this Kata is read-only; never use write tools in Figma.
- **Explicit destination:** always confirm the destination directory with the user before overwriting existing files.