---
name: figma
description: >
  Fetch Figma design specs for pixel-perfect implementation. Triggers - Figma URL provided,
  match the design, implement this Figma, from the mockup, design specs, pixel-perfect,
  exact spacing/typography/colors needed.
---

# Figma Design Tools

This skill ships with Figma helper scripts under `figma/scripts/`.

## Prerequisites

- Set `FIGMA_ACCESS_TOKEN` in a `.env.tools` file at the project root (see `figma/README.md`).
- Use the scripts from this skill directory (do not assume a `js/bin` folder).

## When to use this skill

Use when:

- The user provides a **Figma URL** (design / node / section link)
- The request says "match Figma" / "implement this design" / "pixel-perfect"
- You need **exact spacing/typography/colors/states** (not "close enough")

## Workflow

### When a Figma URL is provided

1. **Extract EXACT Specifications** (MANDATORY)

   Run the tools in sequence:

   ```bash
   # 1. Verify token works
   node figma/scripts/whoami.mjs --verbose

   # 2. Get layout, spacing, colors, typography
   node figma/scripts/get-design-context.mjs \
     --url "https://www.figma.com/design/..." \
     --include-images \
     --verbose

   # 3. Get node hierarchy and constraints
   node figma/scripts/get-metadata.mjs \
     --url "https://www.figma.com/design/..." \
     --verbose

   # 4. Get a visual screenshot for reference
   node figma/scripts/get-screenshot.mjs \
     --url "https://www.figma.com/design/..." \
     --format png \
     --scale 2 \
     --verbose
   ```

   **Output handling (required)**
   - If the output includes an `errors` array, it must be empty before using the data.
   - Capture a short "design spec note" before coding:
     - typography (fontSize/fontWeight/lineHeight)
     - spacing (padding/margins/gaps)
     - colors (tokens/variables or exact values)
     - border radius, shadows
     - states (hover/focus/active/disabled/empty/loading)

2. **Document ALL Measurements Before Writing Code**

   Extract and note:
   - **Typography**: `fontSize`, `fontWeight`, `lineHeight` for EVERY text element
   - **Spacing**: Exact margins, paddings, gaps from auto-layout values
   - **Colors**: Hex/RGB values — no approximations
   - **Dimensions**: Precise width/height/aspect-ratio values
   - **Border radius**: `cornerRadius` values
   - **Shadows**: `effects` array for box shadows
   - **States**: Document hover, focus, active, disabled, empty states

3. **Check Existing Patterns**

   Before implementing, check if similar components exist:

   ```bash
   # Check which Figma components are already linked to code
   node figma/scripts/get-code-connect-map.mjs \
     --file-key <FILE_KEY> \
     --verbose
   ```

4. **Implement with EXACT Values**

   - Use exact Figma values, not approximations
   - Prefer existing design tokens; if no token exists, use the exact value and leave a short comment referencing the Figma node / measurement
   - Implement ALL interactive states from the design

5. **Validate**

   Before finishing:
   - [ ] Typography matches Figma exactly (font size, weight, line height)
   - [ ] Spacing matches Figma exactly (margins, padding, gaps)
   - [ ] Colors match Figma exactly (use hex values from design)
   - [ ] All interactive states implemented (hover, focus, active, disabled)
   - [ ] Responsive behavior matches design intent

## Additional Commands

```bash
# Get design tokens (colors, spacing, typography variables)
node figma/scripts/get-variable-definitions.mjs \
  --file-key <FILE_KEY> \
  --include-styles true \
  --verbose
```

## Rules

- **NEVER approximate** — use exact values from Figma
- **ALWAYS document measurements** before writing any code
- **Check `errors` array** is empty before using response data
- **Ask for clarification** if the design is ambiguous or states are missing
- **Reference existing patterns** before creating new components