# Figma Shared Reference

This document is stack-agnostic, since it is shared by `figma-react`, `figma-react-native`, and `figma-material-hu` (no web-only or mobile-only UI framework rules in this file — stack specifics live in each sub-skill).

## Scope: layout first

- Implement **layout, structure, and styling** from the design.
- Do not add business logic, translations, or API wiring unless asked.
- Use **placeholder content** when real data or copy is not provided.

---

## Map selection to Code Connect

Use this section when the user asks to map a Figma selection to Code Connect.

- Use the **exact** component and path the user gives. Do not substitute
- Convert `node-id` from URL format to MCP format (`13-1711` -> `13:1711`).
- Set `source` and `componentName` based on the target component.

---

## Implement design from Figma

Use this section when the user asks to implement a design from Figma.

### 0. Token-efficient flow

- **Resolve structure first**: call `get_metadata(fileKey, nodeId)` to inspect tree and node ids.
- **Resolve mappings once**: call `get_code_connect_map` once per relevant file and reuse results. Note: An empty map means no one has linked that Figma node to code yet (Code Connect is opt-in per node); it does not mean the check was skipped.
- **Design context only where needed**: call `get_design_context(fileKey, nodeId, …)` for the root, then for specific children only when required.
- **`disableCodeConnect` on `get_design_context` (implementation runs)**: For **implementing** a frame into code, pass **`disableCodeConnect: true`** on `get_design_context` so the MCP returns layout, structure, and reference code instead of an interactive **"connect components"** prompt. Automated agents cannot complete in-Figma connection steps; without this, responses may stall or omit the implementation reference. Mappings still come from `get_code_connect_map` (above)—this flag only affects what `get_design_context` returns, not whether you respect Code Connect in code.
- **If the MCP still returns a connect prompt or no usable reference**: Retry the same node with `disableCodeConnect: true` if it was omitted. If the response is still a prompt or unusable, fall back to **`get_metadata`** + **`get_screenshot`** (and the code-connect map you already fetched), then implement layout and components from structure, tokens, and visuals per §2 and §3.
- **Repeated component instances**: resolve per-instance size/variant from metadata/design context; do not default all repeated instances to the same value.
- **Screenshot only when necessary**: use `get_screenshot` if layout/styling is ambiguous.

### 1. Always use the same design source

- Parse `fileKey` and `nodeId` from the same URL provided by the user.
- Do not switch frames/files unless explicitly asked.

### 2. Respect Code Connect first

- If a node has Code Connect mapping, use that mapped component.
- If mapping is missing, search the target stack design system before falling back to primitives.
- Use primitives only as a last resort and note the limitation.

### 3. Foundations and tokens

- Foundations file:
  `https://www.figma.com/design/JZaQqFSAyJBX6RC1aBVKTp/Foundations`
- ALWAYS use design tokens for color, spacing, and elevation.
- If no exact token exists, use the closest token and note the mismatch.

### 3.1 Spacing and layout

- Map Figma spacing labels (e.g. `Spacing/2x`) to the target stack spacing token system.
- Replicate Auto Layout details: padding, gap, direction, alignment.
- If large fixed values are explicitly defined in design, fixed pixel values are acceptable.

### 3.2 Size, scale, and variants

- Apply size/variant per element and per instance.
- Do not assume identical variants for repeated components unless design confirms it.
- If design context cannot provide per-instance values, apply a sensible hierarchy and explicitly ask for confirmation.

### 4. Ambiguity handling

If component choice is ambiguous:

1. Warn and present options.
2. Ask the user whether to proceed with best guess, skip, or stop.
3. Do not silently assume.
