@pedroab0/skills 1.1.0 → 1.3.0

package/figma-node-builder/SKILL.md

@@ -1,112 +1,101 @@
 ---
 name: figma-node-builder
-description: 'Build production-ready UI components by synthesizing extracted Figma node hierarchies (.specs/*.json) and companion preview images (.specs/*.png). Trigger this skill in Spec-Driven Development (SDD) workflows when the user asks to implement, build, or code UI components from an existing Figma spec, node AST, or specification file.'
+description: 'Builds production-ready UI components from previously extracted Figma spec files (.specs/*.json) and optional preview images (.specs/*.png), reusing the host project components, design tokens, and icon library. Works offline with no Figma API calls. Use when the user asks to implement, build, or code a component or screen from an existing .specs file, or approves implementation after a figma-extractor run.'
 ---
 
-# Figma Node Builder Skill (SDD Implementation Layer)
+# Figma Node Builder (SDD Implementation Layer)
 
-Build production-grade, design-system-grounded UI components directly from extracted Figma Node trees (`.specs/<name>.json`) and visual reference images (`.specs/<name>.png`).
+Builds UI code from an extracted **spec** (`.specs/<name>.json`, the pruned Figma node tree with resolved tokens and component props) and its optional preview image (`.specs/<name>.png`). Works entirely offline: no Figma API calls or tokens.
 
-This skill serves as the **Implementation Layer** in a **Spec-Driven Development (SDD)** workflow. It works entirely offline and locally from the extracted specification contract—no Figma API calls or tokens required.
+Requires Node.js >= 16.7 for the inspector script (zero dependencies, no `npm install`).
 
----
+## Workflow
 
-## When to Trigger This Skill
+Copy this checklist and track your progress:
 
-Trigger this skill whenever:
-* The user references an existing specification file (e.g., *"Build the component from `.specs/card.json`"*).
-* An extraction step by `figma-extractor` or the **Figma Node JSON Extractor** plugin has completed, and the user approves the implementation (e.g., *"Proceed"*, *"Build it"*, *"Implement the UI"*).
-* The user asks to turn a local Figma node AST (`.specs/<name>.json`) into React, Vue, Svelte, or HTML/CSS code.
+```
+Implementation Progress:
+- [ ] Phase 1: Discover the host project (stack, UI primitives, tokens, icons)
+- [ ] Phase 2: Inspect the spec and map it to the codebase
+- [ ] Phase 3: Build the component following the build rules
+- [ ] Phase 4: Validate and fix
+```
 
----
+### Phase 1: Discover the host project
+
+Before writing code, ground the implementation in the existing project:
+
+1. **Framework and styling**: check `package.json` for React, Vue, Svelte, Angular, Next.js, Tailwind CSS, styled-components, or plain CSS.
+2. **UI primitives**: inspect `components/ui/`, `src/components/`, or design system libraries (shadcn/ui, Radix, MUI) for reusable components (`Button`, `Input`, `Card`, `Badge`).
+3. **Design tokens**: inspect `tailwind.config.*`, `theme.css`, or `globals.css` for color, spacing, and radius scales.
+4. **Icons**: check `package.json` for icon packages (`lucide-react`, `@heroicons/react`, `phosphor-react`) and local icon folders (`components/icons/`, `src/assets/`, `public/`).
+
+### Phase 2: Inspect the spec and map it to the codebase
 
-## The 4-Phase Implementation Protocol
+Run the inspector instead of reading the raw JSON into context (resolve `<skill-dir>` as described below):
 
-```mermaid
-flowchart TD
-    A["Phase 1: Codebase Discovery<br/>(Framework & Existing Primitives)"] --> B["Phase 2: Gap Analysis<br/>(Match Tokens & Props)"]
-    B --> C["Phase 3: Grounded Synthesis<br/>(No Hallucinated CSS)"]
-    C --> D["Phase 4: Visual Verification<br/>(Check vs .specs/*.png)"]
+```bash
+node "<skill-dir>/scripts/inspect_spec.js" .specs/<name>.json --markdown
 ```
 
-### Phase 1: Codebase Discovery
-Before writing any code, inspect the host project to ground your implementation:
-1. **Framework & Styling**: Check `package.json` for React, Vue, Svelte, Next.js, Tailwind CSS, styled-components, or plain CSS.
-2. **Existing UI Primitives**: Inspect `components/ui/`, `src/components/`, or design system libraries (e.g., shadcn/ui, Radix, MUI) to identify reusable components (`Button`, `Input`, `Card`, `Badge`).
-3. **Design Token System**: Inspect `tailwind.config.js`, `theme.css`, or `globals.css` to see how colors and spacing scales are configured.
-4. **Icons & Assets Discovery**: Check `package.json` for installed icon packages (e.g. `lucide-react`, `@heroicons/react`, `phosphor-react`) and check if local icon folders exist (`components/icons/`, `src/assets/`, `public/`).
-
-### Phase 2: Gap Analysis & Token Mapping
-Analyze the input JSON spec (`.specs/<name>.json`).
-
-> **Tip**: Instead of reading the entire raw JSON AST into your context window, run the companion **Spec Inspector CLI** from this skill's directory (`<skill-dir>` is the folder containing this `SKILL.md` file; if loaded from `.cursor/rules/figma-node-builder.mdc`, use `.cursor/skills/figma-node-builder`):
-> ```bash
-> # Compact terminal summary (always quote the script path for Windows/macOS/Linux compatibility):
-> node "<skill-dir>/scripts/inspect_spec.js" .specs/<name>.json
->
-> # Output Markdown directly for your implementation plan:
-> node "<skill-dir>/scripts/inspect_spec.js" .specs/<name>.json --markdown
-> ```
-
-* **Component Instances**: For each node with `type: "INSTANCE"`, match `component.name` against existing codebase components. Extract its `props` (e.g., `{ variant: "outline", size: "lg", hasIcon: true }`).
-* **Design Tokens**: For every `token` property (e.g., `colors/brand/primary`, `spacing/md`, `radii/lg`), map to the project's CSS variables (`var(--color-brand-primary)`) or Tailwind classes (`bg-brand-primary`, `p-4`, `rounded-lg`).
-* **Gaps**: Identify any sub-components that do not exist yet in the codebase and plan to scaffold them.
-
-### Phase 3: Grounded Code Synthesis
-Generate component code strictly adhering to the node specification and adapting syntax to the host project's detected stack (e.g., React, Vue, Svelte, Angular, or HTML/CSS):
-
-1. **Reusing Existing Components (Anti-Div Soup Rule)**:
-   - When an `INSTANCE` node matches an existing component, **import and render it directly** (example in JSX — adapt to your framework):
-     ```tsx
-     // Correct:
-     <Button variant="primary" size="large" hasIcon>Confirm Order</Button>
-
-     // Forbidden (do not rebuild existing primitives from raw divs):
-     <div className="flex bg-blue-500 rounded p-2 text-white">Confirm Order</div>
-     ```
-2. **Layout & Flexbox Translation**:
-   - `layoutMode: "HORIZONTAL"` $\rightarrow$ Flex row (`display: flex; flex-direction: row;` or `flex flex-row`).
-   - `layoutMode: "VERTICAL"` $\rightarrow$ Flex column (`display: flex; flex-direction: column;` or `flex flex-col`).
-   - `itemSpacing` $\rightarrow$ CSS `gap` (map to `itemSpacingToken` if available).
-   - `padding` $\rightarrow$ CSS `padding` (map to `paddingToken` if available).
-   - `primaryAxisAlignItems` / `counterAxisAlignItems` $\rightarrow$ `justify-*` and `items-*`.
-3. **Typography & Colors**:
-   - Never guess hex colors. If `token` is present, use the semantic token. If not, use the fallback `color` hex string.
-   - Map font sizes, font weights, and line heights to existing design tokens or typography classes.
-4. **Icon & Vector Resolution Hierarchy**:
-   When encountering a `VECTOR` node or icon instance:
-   - **Normalize Node Name**: Strip common prefixes (`icon/`, `ic_`, `ico-`) and clean the name (e.g., `icon/search` $\rightarrow$ `search` / `Search`).
-   - **Step 1 (Targeted Local Assets/Components)**: Look for matching files in `components/icons/`, `src/assets/`, or `public/` (e.g., `<SearchIcon />`, `/icons/search.svg`). Avoid recursive searches outside these targeted paths.
-   - **Step 2 (Installed Icon Library)**: If not found locally, import from the icon library detected in `package.json` (e.g., `import { Search } from 'lucide-react'`).
-   - **Step 3 (Semantic Fallback - Never Hallucinate Raw Béziers)**: If not found, render an accessible placeholder (`<span className="w-4 h-4 inline-flex items-center justify-center text-muted-foreground" aria-hidden="true" />`) with a `TODO: Missing icon 'search'` comment. Never hallucinate raw SVG `<path d="...">` coordinates.
-5. **Image Layer Handling (`fills: [{ type: "IMAGE" }]`)**:
-   - Focus exclusively on applying the exact styling from the Figma spec: dimensions (`width`, `height`), border radius (`rounded-*`), and scale mode (`scaleMode: "FILL"` $\rightarrow$ `object-cover`, `"FIT"` $\rightarrow$ `object-contain`).
-   - Do **NOT** attempt to resolve, fetch, or hallucinate image files or external URLs (never invent Unsplash or third-party links).
-   - Render a standard `<img>` tag with `src=""` and a concise `TODO` comment specifying the target image:
-     ```tsx
-     {/* TODO: Add image source for 'User Avatar' (48x48) */}
-     <img src="" alt="User Avatar" className="w-12 h-12 rounded-full object-cover" />
-     ```
-
-### Phase 4: Visual Cross-Check & Verification
-* **Optional Companion Image**: If the companion preview image (`.specs/<name>.png`) exists, inspect it to cross-check visual styling and icons.
-* **AST-Only Synthesis**: If `.specs/<name>.png` was omitted (to conserve Tier 1 API calls), rely strictly on the exact metrics, flexbox rules, hex colors, and font styles in `.specs/<name>.json`.
-* If a dev server or browser preview is active, verify that the rendered DOM matches the specification.
+Use `--json` instead of `--markdown` for a structured summary (or `--help` / `-h` for CLI options). Then:
 
----
+- **Component instances**: match each `INSTANCE` `component.name` against existing codebase components and note its `props`.
+- **Design tokens**: map each `token` (`colors/brand/primary`, `spacing/md`, `radii/lg`) to the project CSS variables or Tailwind classes.
+- **Gaps**: list sub-components and tokens that do not exist yet and must be created.
+
+Read specific parts of the raw spec only when the inspector summary is not enough.
+
+### Phase 3: Build the component
+
+Follow the [Build rules](#build-rules), adapting syntax to the stack detected in Phase 1.
+
+### Phase 4: Validate and fix
+
+1. Run the project's existing checks: `typecheck` or `lint` scripts from `package.json`, or `npx tsc --noEmit` when TypeScript is already installed. Never install new dependencies to do this.
+2. If checks fail in the files you created or changed, fix them and run the checks again. Repeat until they pass.
+3. Report pre-existing failures in other files instead of fixing them.
+4. If `.specs/<name>.png` exists, compare it visually with the result. If it does not exist, rely strictly on the metrics in the spec.
+
+## Build rules
 
-## Input Spec Reference (Figma Node AST)
+1. **Reuse existing components (no div soup)**: when an `INSTANCE` matches an existing component, import and render it with the spec props. Never rebuild existing primitives from raw elements.
+   ```tsx
+   // Correct
+   <Button variant="primary" size="large" hasIcon>Confirm Order</Button>
+   // Forbidden
+   <div className="flex bg-blue-500 rounded p-2 text-white">Confirm Order</div>
+   ```
+2. **Layout**: `layoutMode: "HORIZONTAL"` → flex row; `"VERTICAL"` → flex column; `itemSpacing` → `gap`; `padding` → padding; `primaryAxisAlignItems` / `counterAxisAlignItems` → `justify-*` / `items-*`. Prefer the matching `*Token` when present.
+3. **Colors and typography**: never guess values. Use the semantic `token` when present, otherwise the exact hex `color`. Map font size, weight, and line height to existing typography tokens or classes.
+4. **Icons and vectors** (`VECTOR` nodes, `isSvg: true`, or icon instances): normalize the name by stripping `icon/`, `ic_`, `ico-` (`icon/search` → `search`), then resolve in order:
+   1. Local assets or components in `components/icons/`, `src/assets/`, or `public/` only (no repo-wide searches).
+   2. The icon library installed in `package.json` (e.g. `import { Search } from 'lucide-react'`).
+   3. An accessible placeholder with a `TODO: Missing icon 'search'` comment. Never invent raw SVG `<path d="...">` coordinates.
+5. **Image fills** (`fills: [{ type: "IMAGE" }]`): apply only the spec styling (size, radius, `scaleMode: "FILL"` → `object-cover`, `"FIT"` → `object-contain`). Never fetch or invent image URLs:
+   ```tsx
+   {/* TODO: Add image source for 'User Avatar' (48x48) */}
+   <img src="" alt="User Avatar" className="w-12 h-12 rounded-full object-cover" />
+   ```
 
-The input `.specs/<name>.json` file contains a pruned AST of Figma nodes:
+## Spec field reference
 
-| Field | Meaning | Code Mapping |
+| Field | Meaning | Code mapping |
 | :--- | :--- | :--- |
-| `type` | Node type (`FRAME`, `INSTANCE`, `TEXT`, `VECTOR`) | Container (`div` / `section`), Component import, Typography tag (`h1`-`p`), or Icon component/placeholder (see Icon Resolution Hierarchy). |
-| `layoutMode` | Auto-layout direction (`HORIZONTAL`, `VERTICAL`) | `flex flex-row` or `flex flex-col`. |
-| `itemSpacing` / `itemSpacingToken` | Gap between child items | `gap-*` class or `gap: Xpx`. |
-| `padding` / `paddingToken` | Object with `top`, `right`, `bottom`, `left` | `p-*`, `px-*`, `py-*` classes or `padding: ...`. |
-| `cornerRadius` / `cornerRadiusToken` | Border radius | `rounded-*` class or `border-radius: Xpx`. |
-| `component.name` | Master component name for an `INSTANCE` | Import name (e.g. `import { Button } from '@/components/ui/button'`). |
-| `props` | Normalized component variant and boolean properties | JSX/template props: `<Component {...props} />`. |
-| `bounds` | Render dimensions (`width`, `height`) | Sizing constraints (`w-*`, `h-*`, `max-w-*`). |
-| `fills` | Fill layers (`SOLID`, `IMAGE`, gradients) | Background color (`bg-*`), gradient, or styled `<img>` tag for `IMAGE` fills (see Image Layer Handling). |
+| `type` | `FRAME`, `INSTANCE`, `TEXT`, `VECTOR` | Container, component import, typography tag, or icon (rule 4). |
+| `layoutMode` | `HORIZONTAL` / `VERTICAL` auto-layout | `flex flex-row` / `flex flex-col`. |
+| `itemSpacing` / `itemSpacingToken` | Gap between children | `gap-*` or `gap: Xpx`. |
+| `padding` / `paddingToken` | `{ top, right, bottom, left }` | `p-*`, `px-*`, `py-*` or `padding`. |
+| `cornerRadius` / `cornerRadiusToken` | Border radius | `rounded-*` or `border-radius`. |
+| `component.name` | Master component of an `INSTANCE` | Import name (`import { Button } from '@/components/ui/button'`). |
+| `props` | Normalized variant and boolean props | Component props (`<Component {...props} />`). |
+| `bounds` | `{ width, height }` | Sizing (`w-*`, `h-*`, `max-w-*`). |
+| `fills` | `SOLID`, `IMAGE`, gradients | Background, gradient, or `<img>` (rule 5). |
+| `characters` / `typography` | Text content and font metrics | Text node with mapped typography classes. |
+
+## Resolving `<skill-dir>`
+
+Substitute `<skill-dir>` with the directory where this skill is installed, keeping the double quotes around the script path (Windows/macOS/Linux):
+
+- **Standard skills (`SKILL.md`)**: the parent directory of this `SKILL.md` file.
+- **Cursor rule (`.cursor/rules/figma-node-builder.mdc`)**: the sibling `.cursor/skills/figma-node-builder` directory.

package/figma-to-code/README.md

@@ -130,6 +130,7 @@ node figma-to-code/scripts/fetch_figma.js "<FigmaURL>" -i --shallow-instances
 | :--- | :--- | :--- |
 | `--image`, `--download-image` | `-i` | Download and save rendered preview image from Figma (Tier 1 call; optional). |
 | `--image-path <path>` | `-o <path>` | Custom destination path for saved preview image (e.g., `./.specs/card.png`). |
+| `--force`, `--fresh` | `-f` | Ignore existing local preview image and re-fetch freshly from Figma. |
 | `--tokens`, `--variables` | | Export only the file's design token dictionary (colors, spacing, radii). |
 | `--shallow-instances` | | Collapse internal layers of component instances into clean props. |
 | `--include-tokens` | | Bundle complete design tokens dictionary alongside the node tree. |
@@ -138,7 +139,7 @@ node figma-to-code/scripts/fetch_figma.js "<FigmaURL>" -i --shallow-instances
 | `--raw` | | Return full unpruned Figma API response without filtering. |
 | `--depth <number>` | | Limit node tree traversal depth (e.g., `--depth 2` for top-level layout only). |
 | `--scale <1\|2\|3\|4>` | | Multiplier for rendered image resolution (default: `2`). |
-| `--format <png\|svg\|jpg>` | | Image format for downloaded preview (default: `png`). |
+| `--format <png\|svg\|jpg\|pdf>` | | Image format for downloaded preview (default: `png`). |
 | `--no-variables` | | Skip querying local variables to speed up extraction. |
 | `--help` | `-h` | Display command usage and available flags. |
 

package/figma-to-code/REFERENCE.md

@@ -0,0 +1,110 @@
+# Figma To Code Reference
+
+## Contents
+
+- Token setup
+- Corporate proxy and SSL
+- CLI flags
+- Output spec schema
+- Rate-limit gate internals
+
+## Token setup
+
+A Figma Personal Access Token (or OAuth token) is required. The user creates one in **Figma Settings → Personal Access Tokens**. The script reads `FIGMA_ACCESS_TOKEN` (or `FIGMA_TOKEN`) from the environment, from `.env` / `.env.local` in the working directory, from `~/.env`, and from shell profiles.
+
+| Platform | Command for the user |
+| :--- | :--- |
+| macOS / Linux | `export FIGMA_ACCESS_TOKEN="figd_your_token_here"` in `~/.zshrc` or `~/.bashrc` |
+| Windows (PowerShell) | `[Environment]::SetEnvironmentVariable("FIGMA_ACCESS_TOKEN", "figd_your_token_here", "User")` |
+| Any (workspace) | `FIGMA_ACCESS_TOKEN=figd_your_token_here` in `.env` |
+
+## Corporate proxy and SSL
+
+Behind a corporate proxy with self-signed certificates, the script fails with `FIGMA_SSL_CERTIFICATE_ERROR`. The user can disable certificate verification for Figma requests:
+
+```env
+FIGMA_IGNORE_SSL=true
+```
+
+## CLI flags
+
+```bash
+node "<skill-dir>/scripts/fetch_figma.js" <FigmaURL> [options]
+node "<skill-dir>/scripts/fetch_figma.js" <fileKey> [nodeId] [options]
+```
+
+| Flag | Shorthand | Description |
+| :--- | :--- | :--- |
+| `--image`, `--download-image` | `-i` | Download the rendered preview image (+1 Tier 1 call). |
+| `--image-path <path>`, `--output <path>` | `-o <path>` | Destination path for the preview image (implies `--image`). |
+| `--force`, `--fresh` | `-f` | Ignore an existing local preview image and re-fetch it from Figma. |
+| `--tokens`, `--variables` | | Output only the design token dictionary (colors, spacing, radii). |
+| `--shallow-instances` | | Collapse internal layers of component instances into props. |
+| `--include-tokens` | | Include the full design token dictionary alongside the node tree. |
+| `--include-ids` | | Keep internal Figma node IDs on each node. |
+| `--pretty` | | Pretty-print JSON with 2-space indentation (default is compact). |
+| `--raw` | | Return the full, unpruned Figma API response. Large; avoid unless debugging. |
+| `--depth <number>` | | Limit node tree traversal depth (e.g. `--depth 2` for an overview). |
+| `--scale <1\|2\|3\|4>` | | Preview render scale (default: `2`). |
+| `--format <png\|svg\|jpg\|pdf>` | | Preview image format (default: `png`). |
+| `--no-variables` | | Skip querying `/variables/local`. |
+| `--help` | `-h` | Show the help message. |
+
+## Output spec schema
+
+Each node keeps only properties that differ from Figma defaults. Hidden layers are dropped. Pure vector groups collapse into a single `VECTOR` node with `isSvg: true`.
+
+| Field | Meaning |
+| :--- | :--- |
+| `name`, `type` | Layer name and node type (`FRAME`, `INSTANCE`, `TEXT`, `VECTOR`, ...). |
+| `bounds` | `{ width, height }` render dimensions. |
+| `layoutMode`, `layoutWrap`, `primaryAxisAlignItems`, `counterAxisAlignItems` | Auto-layout direction and alignment. |
+| `layoutGrow`, `layoutAlign`, `minWidth`, `maxWidth`, `minHeight`, `maxHeight` | Child sizing constraints. |
+| `padding` / `paddingToken`, `itemSpacing` / `itemSpacingToken` | Spacing values and bound tokens. |
+| `cornerRadius` / `cornerRadiusToken`, `cornerRadii` | Uniform or per-corner radius. |
+| `fills`, `strokes`, `effects`, `opacity` | Paints (hex `color` + optional `token`), borders, shadows/blurs. |
+| `characters`, `typography` | Text content and `fontFamily`, `fontSize`, `fontWeight`, `lineHeightPx`, `letterSpacing`, `textAlignHorizontal`, `textAlignVertical`. |
+| `component`, `props` | Master component `name`/`variant` and normalized instance props. |
+| `children` | Child nodes. |
+| `image` | Present when `-i` was used: preview `path`, or `error`. |
+
+### Resolved design tokens
+
+When a layer is bound to Figma variables, the semantic token name is attached next to the computed fallback value:
+
+```json
+{
+  "name": "Card Container",
+  "type": "FRAME",
+  "layoutMode": "VERTICAL",
+  "padding": { "top": 16, "right": 16, "bottom": 16, "left": 16 },
+  "paddingToken": "spacing/md",
+  "itemSpacing": 12,
+  "itemSpacingToken": "spacing/sm",
+  "cornerRadius": 8,
+  "cornerRadiusToken": "radii/lg",
+  "fills": [{ "type": "SOLID", "color": "#1877F2", "token": "colors/brand/primary" }]
+}
+```
+
+### Normalized component instances
+
+Figma property hashes (`Label#12:3`) become clean props linked to the master component:
+
+```json
+{
+  "name": "Submit Button",
+  "type": "INSTANCE",
+  "component": { "name": "Button", "variant": "Variant=Primary, Size=Large" },
+  "props": { "variant": "Primary", "size": "Large", "hasIcon": true, "label": "Confirm Order" },
+  "bounds": { "width": 140, "height": 44 }
+}
+```
+
+## Rate-limit gate internals
+
+The script protects the file quota automatically. No agent action is needed beyond the Zero-Hammer rules in `SKILL.md`.
+
+- **Sliding window**: at most 5 requests per minute per file key (Figma throttles at roughly 10/min).
+- **Pacing**: at least 2.5 s between consecutive requests.
+- **Circuit breaker**: after an HTTP 429, the lockout end time is stored in `~/.figma_ratelimit.json`. Later calls to that file key fail immediately with `FIGMA_CIRCUIT_BREAKER_ACTIVE` and send no network traffic, so the lockout is not extended.

package/figma-to-code/SKILL.md

@@ -1,213 +1,82 @@
 ---
 name: figma-to-code
-description: 'Directly convert Figma designs into clean, production-ready UI code in a single turn using the Figma REST API. Trigger this skill whenever the user provides a Figma link and asks to generate, code, build, or implement UI components directly without an intermediate specification review.'
+description: 'Converts a Figma frame or component directly into production-ready UI code in a single pass, fetching a compact design-token-aware node tree from the Figma REST API and reusing the host project components and styles. Use when the user shares a figma.com link and explicitly asks to build, code, or implement it right away, without an intermediate spec review step. Supports React, Vue, Svelte, Angular, and plain HTML/CSS.'
 ---
 
-# Figma To Code Skill
+# Figma To Code
 
-Directly convert Figma designs into clean, production-ready UI components in a single turn. 
+Fetches a compact, design-token-aware node tree for a Figma frame and immediately builds the component in the host project, reusing its existing components and styles.
 
-This skill connects to the Figma REST API, extracts a compact design-system-aware AST, resolves variables into semantic design tokens, and immediately generates the target component code grounded in your project's existing design system and components.
+Requires Node.js >= 16.7. The scripts have zero dependencies (no `npm install`).
 
----
-
-## Strict Guardrails: No Browser Scraping / Automation
+## Boundaries
 
-> [!CAUTION]
-> **NEVER use browser tools (Playwright, Puppeteer, Chrome DevTools, `browser_navigate`, `read_browser_page`) on Figma URLs.**
->
-> 1. **Figma Canvas is WebGL/Wasm**: Figma renders design canvas elements inside an HTML5 `<canvas>` via WebAssembly. There are NO inspectable HTML DOM elements for frames, layers, texts, or styles. Browser automation cannot extract Figma nodes or properties.
-> 2. **Never search for local browser binaries**: Do not search OS application directories (e.g., `/Applications`, `Program Files`, `/usr/bin`) or run browser automation scripts.
-> 3. **API Errors Are Final**: If `fetch_figma.js` returns an API error (e.g., 401 Unauthorized, 403 Forbidden, or 429 Rate Limited), **report the error directly to the user**. Guide them to check their `FIGMA_ACCESS_TOKEN`, permissions, or wait out rate limits. Do NOT attempt browser scraping fallbacks.
-
----
+- **Never open Figma URLs with browser tools** (Playwright, Puppeteer, Chrome DevTools). The Figma canvas is WebGL, so there is no DOM to read. Do not search for local browser binaries.
+- **API errors are final**: report them to the user. Never fall back to scraping.
+- If the user only wants to inspect, document, or plan the design, stop and suggest the `figma-extractor` skill instead.
 
-## Built-in Rate-Limit Gate & Circuit Breaker
+## Workflow
 
-To protect your Figma file quota and prevent lockout penalties, `fetch_figma.js` enforces an automatic safety gate:
-* **Max 5 requests per minute** per file key (sliding window limit).
-* **2.5s inter-request pacing** between consecutive requests.
-* **Persistent Circuit Breaker**: If Figma returns HTTP 429, the script records the lockout time locally in `.figma_ratelimit.json` inside the user's home directory. All future calls to that file key are **immediately blocked with zero network traffic**, preventing Figma from extending the lockout penalty.
-
-### Agent Behavioral Rules (Zero-Hammer Protocol)
-1. **Single-Shot Execution**: Run `fetch_figma.js` **once** per target frame or component.
-2. **Never Retry on Failure**: If `fetch_figma.js` returns an error, **DO NOT retry in a loop**. Report the error directly to the user.
-3. **Handling `FIGMA_CIRCUIT_BREAKER_ACTIVE`**: If the circuit breaker trips, inform the user that the file key is on cooldown, and suggest duplicating the file in Figma Drafts (Right-click $\rightarrow$ **Duplicate**) to get a fresh URL.
-
----
+Copy this checklist and track your progress:
 
-## Prerequisites
-
-A Figma Access Token (Personal Access Token or OAuth Token) is required.
-
-Configure it using either:
-1. **Environment Variable**:
-   - **macOS / Linux**: `export FIGMA_ACCESS_TOKEN="figd_your_token_here"` (or `FIGMA_TOKEN`)
-   - **Windows (PowerShell)**: `[Environment]::SetEnvironmentVariable("FIGMA_ACCESS_TOKEN", "figd_your_token_here", "User")` or `$env:FIGMA_ACCESS_TOKEN="figd_your_token_here"` in `$PROFILE`
-2. **Workspace `.env` File**:
-   ```env
-   FIGMA_ACCESS_TOKEN=figd_your_token_here
-   ```
-
-### Corporate Proxy & SSL Certificates
-If you are behind a corporate proxy or firewall with self-signed SSL certificates, enable SSL verification bypass:
-```env
-FIGMA_IGNORE_SSL=true
+```
+Build Progress:
+- [ ] 1. Discover the host project (stack, UI primitives, tokens, icons)
+- [ ] 2. Fetch the node tree (once)
+- [ ] 3. Build the component following the build rules
+- [ ] 4. Validate and fix
 ```
 
-## Tier 1 Quota Conservation: AST-Only by Default
-
-> [!IMPORTANT]
-> **Figma Starter plans enforce a strict limit of 20 Tier 1 requests/month.**
-> Both `GET /v1/files/:key/nodes` and `GET /v1/images/:key` count as Tier 1 endpoints.
->
-> 1. **Default to AST-only extraction**: Extracting AST without `-i` consumes **only 1 Tier 1 call**. The JSON AST contains 100% of layout rules (flexbox, padding, gap), dimensions, hex colors, corner radii, and text content needed for code generation.
-> 2. **DO NOT pass `-i` / `--image` by default**: Only add `-i` if the user explicitly requests downloading a visual preview screenshot.
-
----
-
-## Agent Execution Instructions
+**1. Discover the host project**: check `package.json` (framework, styling, icon library), reusable components in `components/ui/` or `src/components/`, and theme files (`tailwind.config.*`, `theme.css`, `globals.css`).
 
-To extract and build UI from a Figma URL, run `fetch_figma.js` from this skill's `scripts/` directory:
+**2. Fetch the node tree** (1 Tier 1 API call; JSON is printed to stdout):
 
 ```bash
-# Recommended: Extract compact AST (1 Tier 1 call)
 node "<skill-dir>/scripts/fetch_figma.js" "<FigmaURL>"
-
-# Optional: With companion preview image (2 Tier 1 calls)
-node "<skill-dir>/scripts/fetch_figma.js" "<FigmaURL>" -i
 ```
 
-**Resolving `<skill-dir>` (Agent-Agnostic)**:
-Substitute `<skill-dir>` with the directory where this skill is installed — **never guess another agent's folder** (always keep double quotes around the script path for Windows/macOS/Linux compatibility):
-- **Standard Skills (`SKILL.md`)**: `<skill-dir>` is the exact parent directory of this `SKILL.md` file.
-- **Cursor Rule (`.cursor/rules/figma-to-code.mdc`)**: `<skill-dir>` is the sibling `.cursor/skills/figma-to-code` directory (replace `rules/figma-to-code.mdc` with `skills/figma-to-code`).
+For large frames, add `--shallow-instances` (collapses instance internals into props) or `--depth 2`. All flags, the output schema, token setup per OS, and proxy options: see [REFERENCE.md](REFERENCE.md) (located at `<skill-dir>/REFERENCE.md`).
 
----
-
-## Usage & Command Formats
+**3. Build**: follow the [Build rules](#build-rules), adapting syntax to the detected stack.
 
-### 1. Basic One-Shot Code Generation
+**4. Validate and fix**
 
-```bash
-# Standard extraction (1 Tier 1 call - recommended)
-node "<skill-dir>/scripts/fetch_figma.js" "https://www.figma.com/design/:fileKey/:name?node-id=4023-474"
+1. Run the project's existing checks: `typecheck` or `lint` scripts from `package.json`, or `npx tsc --noEmit` when TypeScript is already installed. Never install new dependencies to do this.
+2. If checks fail in the files you created or changed, fix them and run the checks again. Repeat until they pass.
+3. Report pre-existing failures in other files instead of fixing them.
+4. If a preview image was downloaded (`image.path` in the output), compare it visually with the result.
 
-# Optional: With preview image (2 Tier 1 calls)
-node "<skill-dir>/scripts/fetch_figma.js" "https://www.figma.com/design/:fileKey/:name?node-id=4023-474" -i
+## Build rules
 
-# Collapse internal layers of component instances into props (guides agent to reuse existing components)
-node "<skill-dir>/scripts/fetch_figma.js" "https://www.figma.com/design/:fileKey/:name?node-id=4023-474" --shallow-instances
-```
+1. **Reuse existing components (no div soup)**: when an `INSTANCE` matches an existing component, import and render it with the spec props (`<Button variant="primary" size="large" hasIcon>Confirm Order</Button>`). Never rebuild existing primitives from raw elements.
+2. **Layout**: `layoutMode: "HORIZONTAL"` → flex row; `"VERTICAL"` → flex column; `itemSpacing` → `gap`; `padding` → padding; `primaryAxisAlignItems` / `counterAxisAlignItems` → `justify-*` / `items-*`. Prefer the matching `*Token` when present.
+3. **Colors and typography**: never guess values. Use the semantic `token` when present (mapped to the project CSS variable or Tailwind class), otherwise the exact hex `color`. Map font size, weight, and line height to existing typography tokens or classes.
+4. **Icons and vectors** (`VECTOR` nodes, `isSvg: true`, or icon instances): normalize the name by stripping `icon/`, `ic_`, `ico-` (`icon/search` → `search`), then resolve in order:
+   1. Local assets or components in `components/icons/`, `src/assets/`, or `public/` only (no repo-wide searches).
+   2. The icon library installed in `package.json` (e.g. `import { Search } from 'lucide-react'`).
+   3. An accessible placeholder with a `TODO: Missing icon 'search'` comment. Never invent raw SVG `<path d="...">` coordinates.
+5. **Image fills** (`fills: [{ type: "IMAGE" }]`): apply only the spec styling (size, radius, `scaleMode: "FILL"` → `object-cover`, `"FIT"` → `object-contain`). Never fetch or invent image URLs. Render `<img src="" alt="...">` with a `TODO` comment naming the layer and its size.
 
-### 2. CLI Flags Reference
-
-| Flag | Shorthand | Description |
-| :--- | :--- | :--- |
-| `--image`, `--download-image` | `-i` | Download and save rendered preview image from Figma (Tier 1 call; optional). |
-| `--image-path <path>` | `-o <path>` | Custom local file path to save preview image (implies `--image`). |
-| `--tokens`, `--variables` | | Output only the design token dictionary (colors, spacing, radii) for theme setup. |
-| `--shallow-instances` | | Collapse internal sub-layers of component instances into clean props. |
-| `--pretty` | | Pretty-print JSON with 2-space indentation (default is compact single-line JSON). |
-| `--include-tokens` | | Include full design tokens dictionary alongside node AST. |
-| `--include-ids` | | Retain internal Figma node IDs on each node in the tree. |
-| `--raw` | | Return full, unpruned raw Figma API AST. |
-| `--depth <number>` | | Limit node tree traversal depth (e.g. `--depth 2` for top-level overview). |
-| `--scale <1\|2\|3\|4>` | | Render resolution multiplier for preview images (default: `2`). |
-| `--format <png\|svg\|jpg>` | | Rendered image file format (default: `png`). |
-| `--no-variables` | | Skip querying `/variables/local`. |
-| `--help` | `-h` | Show help message. |
+## Resolving `<skill-dir>`
 
----
+Substitute `<skill-dir>` with the directory where this skill is installed. Never guess another agent's folder, and keep the double quotes around the script path (Windows/macOS/Linux):
 
-## Output Structure & Design-System Awareness
-
-### 1. Resolved Design Tokens
-When a layer uses Figma variables (design tokens), the extractor attaches semantic token names alongside the computed values:
-
-```json
-{
-  "name": "Card Container",
-  "type": "FRAME",
-  "layoutMode": "VERTICAL",
-  "padding": { "top": 16, "right": 16, "bottom": 16, "left": 16 },
-  "paddingToken": "spacing/md",
-  "itemSpacing": 12,
-  "itemSpacingToken": "spacing/sm",
-  "cornerRadius": 8,
-  "cornerRadiusToken": "radii/lg",
-  "fills": [
-    {
-      "type": "SOLID",
-      "color": "#1877F2",
-      "token": "colors/brand/primary"
-    }
-  ]
-}
-```
+- **Standard skills (`SKILL.md`)**: the parent directory of this `SKILL.md` file.
+- **Cursor rule (`.cursor/rules/figma-to-code.mdc`)**: the sibling `.cursor/skills/figma-to-code` directory.
 
-### 2. Normalized Component Instances & Props
-When an `INSTANCE` node is present, internal property hashes are converted into clean JavaScript props and linked to the master component name:
-
-```json
-{
-  "name": "Submit Button",
-  "type": "INSTANCE",
-  "component": {
-    "name": "Button",
-    "variant": "Variant=Primary, Size=Large"
-  },
-  "props": {
-    "variant": "Primary",
-    "size": "Large",
-    "hasIcon": true,
-    "label": "Confirm Order"
-  },
-  "bounds": { "width": 140, "height": 44 }
-}
-```
+## Quota rules (Zero-Hammer Protocol)
 
----
+The script enforces a local rate gate and a persistent circuit breaker, but the agent must also follow these rules:
 
-## How to Build Components from the Extracted Data
-
-When synthesizing code from the output (always adapting syntax, attributes, and styling conventions to the project's detected stack — e.g., React, Vue, Svelte, Angular, or plain HTML/CSS):
-
-1. **Using Existing UI Components**:
-   - For `INSTANCE` nodes with resolved `component.name` and `props`:
-     - Check if your codebase already has this component (e.g. `<Button />`, `<Input />`, `<Modal />`).
-     - Directly render: `<Button variant="primary" size="large" hasIcon>Confirm Order</Button>` instead of building raw HTML divs.
-2. **Applying Semantic Design Tokens**:
-   - When a `token` is present (e.g., `colors/brand/primary`, `spacing/md`):
-     - Map to your project's Tailwind class (`bg-brand-primary`, `p-md`, `rounded-lg`) or CSS variable (`var(--color-brand-primary)`).
-     - Avoid hardcoding hex colors or pixel values when tokens are available.
-3. **Layout & Flexbox**:
-   - `HORIZONTAL` $\rightarrow$ `flex flex-row` (`display: flex; flex-direction: row;`).
-   - `VERTICAL` $\rightarrow$ `flex flex-col` (`display: flex; flex-direction: column;`).
-   - `itemSpacing` $\rightarrow$ CSS `gap`.
-   - `primaryAxisAlignItems` & `counterAxisAlignItems` $\rightarrow$ `justify-*` and `items-*`.
-4. **Icon & Vector Resolution Hierarchy**:
-   - For `VECTOR` nodes or icon instances, normalize the name (strip prefixes `icon/`, `ic_`, `ico-`).
-   - **Step 1 (Targeted Local Assets/Components)**: Look for matching files in `components/icons/`, `src/assets/`, or `public/` (e.g. `<SearchIcon />`, `/icons/search.svg`). Avoid unbounded repo searches.
-   - **Step 2 (Installed Icon Library)**: If not found, import from packages in `package.json` (e.g., `lucide-react`, `@heroicons/react`).
-   - **Step 3 (Semantic Fallback)**: If not found, render an accessible placeholder (`<span className="..." aria-hidden="true" />`) with a `TODO: Missing icon 'name'` comment. Never hallucinate raw SVG `<path d="...">` coordinates.
-5. **Image Layer Handling (`fills: [{ type: "IMAGE" }]`)**:
-   - Focus exclusively on applying the exact styling from the Figma spec: dimensions (`width`, `height`), border radius (`rounded-*`), and scale mode (`scaleMode: "FILL"` $\rightarrow$ `object-cover`, `"FIT"` $\rightarrow$ `object-contain`).
-   - Do **NOT** attempt to resolve, fetch, or hallucinate image files or external URLs (never invent Unsplash or third-party links).
-   - Render a standard `<img>` tag with `src=""` and a concise `TODO` comment specifying the target image layer.
-6. **Visual Verification**:
-   - Inspect the downloaded preview image (`output.image.path`) to ensure pixel-perfect fidelity.
+1. Run `fetch_figma.js` **once** per target frame or component. **Never retry in a loop.**
+2. **Do not pass `-i`** unless the user explicitly requests a preview image. The JSON already contains layout, dimensions, colors, radii, typography, and text.
+3. Figma Starter plans and View seats have very small monthly Tier 1 quotas, so every call matters.
 
----
+## Errors
 
-## Error Handling & Troubleshooting
-
-- **Token Expired / Missing (`FIGMA_TOKEN_EXPIRED_OR_INVALID` / `isTokenExpiredOrInvalid`)**:
-  - Alert the user that their Figma access token is missing, invalid, or expired.
-  - Instruct the user to create a token in **Figma Settings $\rightarrow$ Personal Access Tokens** and configure `FIGMA_ACCESS_TOKEN` in their environment or workspace `.env` file.
-- **Node Not Found**:
-  - Alert the user that the node ID could not be found in the specified file.
-- **Corporate Proxy / Self-Signed SSL (`FIGMA_SSL_CERTIFICATE_ERROR`)**:
-  - Instruct the user to add `FIGMA_IGNORE_SSL=true` to `.env` or set it in their environment.
-- **Rate Limited (`FIGMA_RATE_LIMIT_EXCEEDED` / `FIGMA_CIRCUIT_BREAKER_ACTIVE`)**:
-  - Figma REST API has strict per-minute and monthly rate limits. If rate limited or the circuit breaker trips, report the cooldown to the user and suggest duplicating the file in Figma Drafts to get a fresh URL.
+| Error code | Action |
+| :--- | :--- |
+| `FIGMA_ACCESS_TOKEN is not set` / `FIGMA_TOKEN_EXPIRED_OR_INVALID` | Tell the user the token is missing, invalid, or expired. They create one in **Figma Settings → Personal Access Tokens** and set `FIGMA_ACCESS_TOKEN` (setup per OS in REFERENCE.md). |
+| Node not found | Report that the `node-id` does not exist in the file. |
+| `FIGMA_SSL_CERTIFICATE_ERROR` | Corporate proxy or self-signed certificate: suggest `FIGMA_IGNORE_SSL=true` in `.env`. |
+| `FIGMA_RATE_LIMIT_EXCEEDED` / `FIGMA_CIRCUIT_BREAKER_ACTIVE` | Report the cooldown. Suggest duplicating the file in Figma Drafts (Right-click → **Duplicate**) for a fresh URL, or exporting the selection with the companion [Figma Node JSON Extractor](https://www.figma.com/community/plugin/1691244420692136789/figma-node-json-extractor) plugin and building from that JSON. |