Add use-figma skill with Figma API tool scripts

Includes 6 Node.js scripts for extracting design specs from Figma (layout, typography, colors, screenshots, tokens, code connect map). README explains API token setup.
2026-03-03 16:55:22 +01:00
parent 093fdef71a
commit c5bf4b57e4
8 changed files with 2574 additions and 0 deletions
@@ -0,0 +1,45 @@
+# use-figma
+
+Figma design tools for extracting specs and implementing pixel-perfect designs.
+
+## Setup
+
+### 1. Get a Figma API token
+
+1. Go to [Figma Account Settings](https://www.figma.com/developers/api#access-tokens)
+2. Generate a new **Personal Access Token**
+3. Required scopes: `file_read`
+4. Optional scopes: `file_variables:read` (needed for `get-variable-definitions`)
+
+### 2. Configure the token
+
+Create a `.env.tools` file in your project root:
+
+```
+FIGMA_ACCESS_TOKEN=your_token_here
+```
+
+Make sure `.env.tools` is in your `.gitignore` — never commit tokens.
+
+### 3. Verify it works
+
+```bash
+node use-figma/scripts/whoami.mjs --verbose
+```
+
+You should see your Figma user info if the token is valid.
+
+## Available Scripts
+
+| Script | Description |
+|---|---|
+| `whoami.mjs` | Verify API token authentication |
+| `get-design-context.mjs` | Extract layout, spacing, colors, typography |
+| `get-metadata.mjs` | Get node hierarchy and constraints |
+| `get-screenshot.mjs` | Generate visual screenshots from designs |
+| `get-code-connect-map.mjs` | Check which components are linked to code |
+| `get-variable-definitions.mjs` | Extract design tokens (colors, spacing, typography) |
+
+## Usage
+
+See `SKILL.md` for the full workflow on how these tools are used together.
@@ -0,0 +1,119 @@
+---
+name: use-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 `use-figma/scripts/`.
+
+## Prerequisites
+
+- Set `FIGMA_ACCESS_TOKEN` in a `.env.tools` file at the project root (see `use-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 use-figma/scripts/whoami.mjs --verbose
+
+   # 2. Get layout, spacing, colors, typography
+   node use-figma/scripts/get-design-context.mjs \
+     --url "https://www.figma.com/design/..." \
+     --include-images \
+     --verbose
+
+   # 3. Get node hierarchy and constraints
+   node use-figma/scripts/get-metadata.mjs \
+     --url "https://www.figma.com/design/..." \
+     --verbose
+
+   # 4. Get a visual screenshot for reference
+   node use-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 use-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 use-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