@pedroab0/skills 1.2.0 → 1.3.0

package/bin/cli.js

@@ -72,9 +72,37 @@ ${style.bold('Examples:')}
 }
 
 // -----------------------------------------------------------------------------
-// Skill Discovery
+// Frontmatter & Skill Discovery
 // -----------------------------------------------------------------------------
 
+function parseFrontmatterField(content, field) {
+  const fm = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!fm) return '';
+  const lines = fm[1].split(/\r?\n/);
+  const line = lines.find((l) => l.startsWith(`${field}:`));
+  if (!line) return '';
+  const raw = line.slice(field.length + 1).trim();
+  if (raw.startsWith("'") && raw.endsWith("'")) {
+    return raw.slice(1, -1).replace(/''/g, "'");
+  }
+  if (raw.startsWith('"') && raw.endsWith('"')) {
+    try {
+      return JSON.parse(raw);
+    } catch (_) {
+      return raw.slice(1, -1);
+    }
+  }
+  return raw;
+}
+
+function rewriteRelativeLinksForCursor(body, skill) {
+  return body.replace(/\]\((?!https?:|#|\/)([^)\s#]+\.md)(#[^)]*)?\)/g, (m, rel, hash = '') => {
+    return fs.existsSync(path.join(skill.path, rel))
+      ? `](../skills/${skill.name}/${rel}${hash || ''})`
+      : m;
+  });
+}
+
 function getAvailableSkills() {
   const skills = [];
   try {
@@ -87,10 +115,7 @@ function getAvailableSkills() {
           let description = '';
           try {
             const content = fs.readFileSync(skillMdPath, 'utf8');
-            const match = content.match(/description:\s*['"]?([^'"\n\r]+)['"]?/);
-            if (match) {
-              description = match[1].trim();
-            }
+            description = parseFrontmatterField(content, 'description');
           } catch (_) {}
           skills.push({
             name: entry.name,
@@ -543,11 +568,14 @@ function installSkill(skill, destDir, useSymlink = false, isCursor = false) {
     fs.cpSync(skill.path, cursorSkillsDir, { recursive: true, filter: copyFilter });
 
     const rawSkillMd = fs.readFileSync(path.join(skill.path, 'SKILL.md'), 'utf8');
-    const skillBody = rawSkillMd.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n*/, '');
+    const skillBody = rewriteRelativeLinksForCursor(
+      rawSkillMd.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n*/, ''),
+      skill,
+    );
     const ruleFile = path.join(destDir, `${skill.name}.mdc`);
     const ruleContent = `---
-description: ${skill.description}
-globs: *
+description: ${JSON.stringify(skill.description)}
+alwaysApply: false
 ---
 
 ${skillBody}`;
@@ -880,6 +908,8 @@ if (require.main === module) {
 
 module.exports = {
   selectPrompt,
+  parseFrontmatterField,
+  rewriteRelativeLinksForCursor,
   getAvailableSkills,
   getAgentConfigs,
   checkFigmaToken,

package/figma-extractor/README.md

@@ -129,6 +129,7 @@ node figma-extractor/scripts/fetch_figma.js "<FigmaURL>" --tokens --spec tokens
 | `--spec <name>` | | **Atomic SDD mode**: Saves `./.specs/<name>.json` (add `-i` to also download preview PNG). |
 | `--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 spec/preview 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. |
@@ -137,7 +138,7 @@ node figma-extractor/scripts/fetch_figma.js "<FigmaURL>" --tokens --spec tokens
 | `--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-extractor/REFERENCE.md

@@ -0,0 +1,111 @@
+# Figma Extractor 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 |
+| :--- | :--- | :--- |
+| `--spec <name>` | | Save `./.specs/<name>.json` (and `<name>.png` with `-i`). Reuses an existing spec with 0 API calls. |
+| `--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 the existing local spec/preview and re-fetch 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-extractor/SKILL.md

@@ -1,201 +1,77 @@
 ---
 name: figma-extractor
-description: 'Extract compact JSON node hierarchies, design tokens, component instance props, and automated preview images from Figma using the Figma REST API. Trigger this skill during the planning or specification phase whenever a Figma link is provided or when the user asks to inspect, extract, or sync design specifications and tokens from Figma into .specs/. This skill strictly produces specification artifacts and does not modify application code.'
+description: 'Extracts Figma frames and components into compact JSON spec files (.specs/*.json) with resolved design tokens, normalized component instance props, and optional preview images, using the Figma REST API. Use when the user shares a figma.com link and wants to inspect, extract, document, or plan a design before implementation, or asks to sync Figma variables and design tokens. Produces specification artifacts only and never edits application code. For immediate one-shot code generation from a Figma link, use figma-to-code instead.'
 ---
 
-# Figma Extractor Skill (SDD Spec Ingest)
+# Figma Extractor (SDD Spec Ingest)
 
-Extract design node metadata, component hierarchies, design tokens/variables, and rendered preview images directly from Figma via the Figma REST API into structured specification artifacts (`.specs/`).
+Writes Figma designs to `.specs/<name>.json` (and optionally `.specs/<name>.png`) so a later implementation step can build from a fixed specification. A **spec** is the pruned Figma node tree with resolved tokens and component props.
 
-This skill serves as the **Specification Ingestion Layer** in a **Spec-Driven Development (SDD)** workflow. It is **Design-System Aware**, high-performance, token-efficient, and has zero external dependencies.
+Requires Node.js >= 16.7. The scripts have zero dependencies (no `npm install`).
 
----
-
-## Operational Boundary: Spec Ingestion Only
-
-* **Specification Artifacts Only**: This skill strictly outputs machine-readable design specifications (`.specs/<name>.json`) and visual references (`.specs/<name>.png`).
-* **Zero Application Code Changes**: Do **NOT** create, edit, or modify application source code (`.tsx`, `.vue`, `.html`, `.css`, etc.) while executing this skill.
-* **Hand-off to Implementation**: Once specifications are generated in `./.specs/`, present a summary of the extracted tokens, components, and layout bounds. The implementation phase is handled separately by the developer or a downstream builder skill (such as `figma-node-builder`).
-
----
-
-## Strict Guardrails: No Browser Scraping / Automation
-
-> [!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.
-
----
+## Boundaries
 
-## Built-in Rate-Limit Gate & Circuit Breaker
+- Output only `.specs/` artifacts. **Never create or edit application code** (`.tsx`, `.vue`, `.html`, `.css`, ...) while using this skill.
+- **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.
 
-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.
+## Workflow
 
-### 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
+```
+Extraction Progress:
+- [ ] 1. Run the extraction (once)
+- [ ] 2. Verify the result
+- [ ] 3. Hand off a summary
 ```
 
----
-
-## 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**: Running `--spec <name>` 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.
-> 3. **Reuse existing specs**: If `.specs/<name>.json` exists, reuse it with **0 API calls**.
-
----
-
-## Agent Execution Instructions
-
-To extract a Figma frame or component as a specification artifact, run `fetch_figma.js` from this skill's `scripts/` directory:
+**1. Run the extraction** (1 Tier 1 API call):
 
 ```bash
-# Recommended: Atomic extraction (writes ./.specs/<name>.json - 1 Tier 1 call)
 node "<skill-dir>/scripts/fetch_figma.js" "<FigmaURL>" --spec <name>
-
-# Optional: With companion preview image (writes .json and .png - 2 Tier 1 calls)
-node "<skill-dir>/scripts/fetch_figma.js" "<FigmaURL>" --spec <name> -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-extractor.mdc`)**: `<skill-dir>` is the sibling `.cursor/skills/figma-extractor` directory (replace `rules/figma-extractor.mdc` with `skills/figma-extractor`).
+If `.specs/<name>.json` already exists, the script reuses it with 0 API calls. Pass `--force` only when the user explicitly asks to refresh the spec.
 
----
+**2. Verify the result**
 
-## Usage & Command Formats
+- Success: stdout shows `✔ Saved Figma specification` or `✔ Reusing local Figma specification`.
+- Failure: stderr contains a JSON error payload. Follow [Errors](#errors). Do not retry.
 
-### 1. Atomic Spec Extraction (Recommended SDD Workflow)
+**3. Hand off**: report the spec path and size, the root frame, the main component instances, and the design tokens found. Implementation is handled separately by the developer or by the `figma-node-builder` skill.
 
-Extract node metadata directly into `./.specs/`:
+## Common variants
 
-```bash
-# Atomic AST extraction (1 Tier 1 call - recommended)
-node "<skill-dir>/scripts/fetch_figma.js" "https://www.figma.com/design/:fileKey/:name?node-id=4023-474" --spec card
+| Need | Command suffix |
+| :--- | :--- |
+| Preview PNG (only if the user asks; +1 Tier 1 call) | `--spec <name> -i` |
+| Design tokens dictionary only | `--tokens --spec tokens` |
+| Collapse instance internals into props | `--spec <name> --shallow-instances` |
+| Top-level overview of a large frame | `--spec <name> --depth 2` |
 
-# Optional: With rendered preview image (2 Tier 1 calls)
-node "<skill-dir>/scripts/fetch_figma.js" "https://www.figma.com/design/:fileKey/:name?node-id=4023-474" --spec card -i
+All CLI flags, the output spec schema, token setup per OS, and proxy options: see [REFERENCE.md](REFERENCE.md) (located at `<skill-dir>/REFERENCE.md`).
 
-# Shallow instances mode (collapses internal component layers into clean props)
-node "<skill-dir>/scripts/fetch_figma.js" "https://www.figma.com/design/:fileKey/:name?node-id=4023-474" --spec card --shallow-instances
-```
+## Resolving `<skill-dir>`
 
-### 2. Design Tokens Dictionary Mode
+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):
 
-```bash
-# Export only the file's design token dictionary (colors, spacing, radii) into ./.specs/tokens.json
-node "<skill-dir>/scripts/fetch_figma.js" "https://www.figma.com/design/:fileKey/:name" --tokens --spec tokens
-```
-
-### 3. CLI Flags Reference
-
-| Flag | Shorthand | Description |
-| :--- | :--- | :--- |
-| `--spec <name>` | | **Atomic SDD mode**: Saves `./.specs/<name>.json` (add `-i` to also download preview PNG). |
-| `--image`, `--download-image` | `-i` | Download and save rendered preview image from Figma (Tier 1 call; optional). |
-| `--image-path <path>` | `-o <path>` | Destination path for saved preview image (e.g. `./.specs/preview.png`). |
-| `--tokens`, `--variables` | | Output only the design token dictionary (colors, spacing, radii). |
-| `--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. |
-
----
+- **Standard skills (`SKILL.md`)**: the parent directory of this `SKILL.md` file.
+- **Cursor rule (`.cursor/rules/figma-extractor.mdc`)**: the sibling `.cursor/skills/figma-extractor` directory.
 
-## Output Spec Structure
-
-### 1. Resolved Design Tokens
-When a layer uses Figma variables (design tokens), the extractor attaches semantic token names alongside computed fallback 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"
-    }
-  ]
-}
-```
+## Quota rules (Zero-Hammer Protocol)
 
-### 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 }
-}
-```
+The script enforces a local rate gate and a persistent circuit breaker, but the agent must also follow these rules:
 
----
+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 spec 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. Prefer reusing existing specs.
 
-## Error Handling & Troubleshooting
+## Errors
 
-- **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 → 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.
-- **Rate Limited (`FIGMA_RATE_LIMIT_EXCEEDED` / `FIGMA_CIRCUIT_BREAKER_ACTIVE`)**:
-  - Figma REST API has per-minute and monthly rate limits on Starter plans. If quota is exhausted or circuit breaker trips, inform the user they can export the specification directly via the companion **Figma Node JSON Extractor** desktop plugin (available on [Figma Community](https://www.figma.com/community/plugin/1691244420692136789/figma-node-json-extractor)) into `./.specs/<name>.json`.
+| 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 into `.specs/<name>.json`. |

package/figma-extractor/scripts/fetch_figma.js

@@ -1402,6 +1402,7 @@ Options:
   --spec <name>                Atomically save ./.specs/<name>.json (add -i to also download preview PNG)
   --image, -i                  Download rendered preview image from Figma (Tier 1 call)
   --image-path, -o <path>      Target path for saved preview image (implies --image)
+  --force, -f                  Ignore existing local spec/preview and re-fetch from Figma
   --tokens, --variables        Export only the design token dictionary (colors, spacing, radii)
   --shallow-instances          Collapse internal layers of component instances into props
   --include-tokens             Include complete tokens dictionary in node output

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. |

package/figma-to-code/scripts/fetch_figma.js

@@ -1382,6 +1382,7 @@ Usage:
 Options:
   --image, -i                  Download rendered preview image from Figma (Tier 1 call; optional)
   --image-path, -o <path>      Target path for saved preview image (implies --image)
+  --force, -f                  Ignore existing local preview image and re-fetch from Figma
   --tokens, --variables        Export only the design token dictionary (colors, spacing, radii)
   --shallow-instances          Collapse internal layers of component instances into props
   --include-tokens             Include complete tokens dictionary in node output

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pedroab0/skills",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Curated collection of modular, production-ready skills for AI coding agents (Claude Code, Cursor, Kiro, OpenCode, Antigravity)",
   "bin": {
     "skills": "bin/cli.js",
@@ -11,7 +11,7 @@
     "node": ">=16.7.0"
   },
   "scripts": {
-    "test": "node figma-extractor/scripts/test_fetch_figma.js && node figma-to-code/scripts/test_fetch_figma.js && node figma-node-builder/scripts/test_inspect_spec.js && node test/test_cli.js",
+    "test": "node figma-extractor/scripts/test_fetch_figma.js && node figma-to-code/scripts/test_fetch_figma.js && node figma-node-builder/scripts/test_inspect_spec.js && node test/test_cli.js && node test/test_skills.js",
     "install-skills": "node ./bin/cli.js"
   },
   "repository": {