@pedroab0/skills 0.0.0-stage → 1.0.1

package/figma-extractor/README.md

@@ -0,0 +1,180 @@
+# Figma Extractor
+
+<p align="center">
+  <a href="https://www.figma.com/community/plugin/1691244420692136789/figma-node-json-extractor"><img src="https://img.shields.io/badge/Figma_Community-Plugin-000000?style=flat&logo=figma&logoColor=white" alt="Figma Community Plugin" /></a>
+  <a href="https://www.npmjs.com/package/@pedroab0/skills"><img src="https://img.shields.io/npm/v/@pedroab0/skills.svg?label=@pedroab0/skills" alt="npm package" /></a>
+  <a href="../LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT" /></a>
+</p>
+
+A lightweight, zero-dependency Node.js CLI tool and agent skill that extracts design node metadata, component hierarchies, design tokens, and rendered preview images from Figma via the Figma REST API into `./.specs/`.
+
+This skill serves as the **Specification Ingestion Layer** in a **Spec-Driven Development (SDD)** workflow.
+
+---
+
+## Why Replace Figma MCP?
+
+Standard Figma MCP (Model Context Protocol) servers are often too heavy for coding tasks. They flood your model with massive, unpruned design files and lack awareness of your design system.
+
+### Comparison Table
+
+| Feature | Standard Figma MCP | Figma Extractor Skill |
+| :--- | :--- | :--- |
+| **Token Usage** | Very heavy (50k to 150k+ tokens). Dumps raw vector points, animation curves, and internal metadata. | Ultra-compact (2k to 8k tokens). Strips out 90% of noise, keeping only layout and styles. |
+| **Design System** | Returns raw values (hex color codes, exact pixel sizes). | Resolves Figma Variables into semantic tokens (primary colors, spacing scale, corner radii). |
+| **Component Reuse** | Dumps every internal layer of a component, causing the AI to recreate it as generic divs. | Collapses component layers into clean props, encouraging the AI to reuse your existing components. |
+| **Visual Previews** | Requires multiple slow round-trips to find and download images. | Single step: extracts the layout and downloads a rendered image preview at the same time. |
+| **Reliability** | Requires a persistent background daemon that can crash, hang, or disconnect. | Zero background processes. Runs on-demand as a lightweight script with zero dependencies. |
+
+---
+
+## When to Still Use Figma MCP
+
+A standard MCP server is only better if:
+- You need to **write** to Figma (create layers, post comments).
+- Your AI environment completely blocks command-line tools.
+- Your organization enforces interactive browser-based OAuth logins instead of access tokens.
+
+---
+
+## How It Works in SDD
+
+The extraction happens in a simple 5-step pipeline:
+
+1. **Authentication & Link Parsing**  
+   Reads your Figma access token and automatically parses any Figma link (file, frame, or specific component).
+
+2. **Design Token Collection**  
+   Queries Figma's local variables first to build a clean dictionary of your design tokens (colors, spacing scale, border radii, and typography).
+
+3. **Targeted Retrieval**  
+   Fetches only the specific frame or component from the Figma API instead of downloading the entire canvas.
+
+4. **Smart Cleanup & Pruning**  
+   - **Removes noise**: Discards vector bezier paths, render matrices, and prototyping data.
+   - **Preserves layout**: Keeps flex direction, alignment, gap, padding, dimensions, and typography.
+   - **Maps tokens**: Pairs raw values with their corresponding design token names.
+   - **Simplifies components**: Replaces complex internal sub-layers with a clean component name and ready-to-use props.
+
+5. **Specification Delivery (`.specs/`)**  
+   Saves the compact JSON specification (`.specs/<name>.json`) and optional rendered PNG preview (`.specs/<name>.png`).
+
+---
+
+## How to Use the Skill
+
+### 1. Prerequisites: Create & Set Your Figma Token
+
+#### How to Create the Token:
+1. In Figma, click your profile avatar and select **Settings**.
+2. Select the **Security** tab and scroll to **Personal access tokens**.
+3. Click **Generate new token**, enter a description (e.g., `ai-extractor`), and ensure read access is enabled (`File content: Read`, `Variables: Read`).
+4. Copy the generated token (starts with `figd_`).
+
+#### How to Set the Token in Terminal:
+Choose one of the following terminal commands:
+
+- **Add to your project `.env` file (Recommended)**:
+  ```bash
+  echo 'FIGMA_ACCESS_TOKEN="figd_your_token_here"' >> .env
+  ```
+- **Set for current terminal session only**:
+  ```bash
+  export FIGMA_ACCESS_TOKEN="figd_your_token_here"
+  ```
+- **Persist globally across all terminal sessions (`~/.zshrc`)**:
+  ```bash
+  echo 'export FIGMA_ACCESS_TOKEN="figd_your_token_here"' >> ~/.zshrc && source ~/.zshrc
+  ```
+
+*(Optional: If behind a corporate proxy with self-signed SSL certificates, run `echo 'FIGMA_IGNORE_SSL=true' >> .env`).*
+
+### 2. Invoking via AI Coding Agent (Planning / Spec Phase)
+
+In an SDD workflow, prompt the agent during the planning phase:
+> *"Extract the design specification for this Figma frame into `.specs/`: `<FigmaURL>`"*
+
+The agent runs `fetch_figma.js`, generates the `.specs/` artifacts, and reports the extracted tokens and components without modifying any application code.
+
+### 3. Manual Command Formats
+
+You can also run the script directly from your terminal:
+
+```bash
+# Recommended: Atomic extraction (writes ./.specs/card.json - 1 Tier 1 call)
+node figma-extractor/scripts/fetch_figma.js "<FigmaURL>" --spec card
+
+# Optional: With companion preview image (writes .json & .png - 2 Tier 1 calls)
+node figma-extractor/scripts/fetch_figma.js "<FigmaURL>" --spec card -i
+
+# Atomic extraction with shallow instances (collapses component internals into props)
+node figma-extractor/scripts/fetch_figma.js "<FigmaURL>" --spec card --shallow-instances
+
+# Extract only design tokens dictionary (colors, spacing, radii)
+node figma-extractor/scripts/fetch_figma.js "<FigmaURL>" --tokens > ./.specs/tokens.json
+```
+
+---
+
+## Available Flags
+
+| 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>` | Custom destination path for saved preview image (e.g., `./.specs/card.png`). |
+| `--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. |
+| `--include-ids` | | Retain Figma internal node IDs in the returned output. |
+| `--pretty` | | Format output with readable 2-space indentation (default is compact single-line JSON). |
+| `--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`). |
+| `--no-variables` | | Skip querying local variables to speed up extraction. |
+| `--help` | `-h` | Display command usage and available flags. |
+
+---
+
+## Zero-API Companion: Figma Node JSON Extractor (Figma Plugin)
+
+<p align="center">
+  <img src="./figma-plugin/assets/icon.png" alt="Figma Node JSON Extractor" width="200" />
+</p>
+
+For developers who prefer exporting specifications directly from Figma Desktop without configuring API access tokens or consuming REST API quotas:
+
+* **Published Figma Plugin (Recommended)**: Install [**Figma Node JSON Extractor** on Figma Community](https://www.figma.com/community/plugin/1691244420692136789/figma-node-json-extractor) directly, or search for it under Figma Plugins.
+* **Manual Local Installation (Local / Offline Backup)**: In Figma Desktop, go to **Plugins** $\rightarrow$ **Development** $\rightarrow$ **Import plugin from manifest...** and select `manifest.json` from your installed skills directory:
+  * **Claude Code**: `~/.claude/skills/figma-extractor/figma-plugin/manifest.json`
+  * **Google Antigravity**: `~/.gemini/config/skills/figma-extractor/figma-plugin/manifest.json`
+  * **OpenCode**: `~/.config/opencode/skills/figma-extractor/figma-plugin/manifest.json`
+  * **Cloned Git Repo**: `<repo-root>/figma-extractor/figma-plugin/manifest.json`
+* **Export Options**: Select any frame or component, then click:
+  * **📋 Copy Node JSON**: Copies the clean AST specification to your clipboard.
+  * **💾 .json**: Downloads `<name>.json`.
+  * **🖼 .png**: Downloads `<name>.png` (2x preview).
+  * **📦 Both (.zip)**: Downloads `<name>.specs.zip` containing both files.
+
+---
+
+## Available Resources
+
+The skill includes the following resources:
+
+- **Agent Instruction Guide (`SKILL.md`)**: The core skill definition read by AI agents containing workflow triggers and operational boundaries (spec ingestion only).
+- **Core Extraction Script (`scripts/fetch_figma.js`)**: The standalone, zero-dependency Node.js script that interfaces with the Figma REST API, resolves tokens, prunes the AST, and downloads preview images.
+- **Unit Test Suite (`scripts/test_fetch_figma.js`)**: A suite of 40 automated unit tests verifying URL parsing, token formatting, component prop cleaning, rate-limit gates, and node pruning without requiring network access.
+- **Companion Figma Plugin (`figma-plugin/`)**: Zero-API desktop exporter for extracting AST and previews directly inside Figma Desktop.
+- **Reference Documentation (`README.md`)**: This guide explaining architecture, comparison, and operational flags.
+
+---
+
+## The SDD Specification Contract (`.specs/`)
+
+`figma-extractor` strictly separates **Specification** from **Implementation**:
+* **`.specs/<name>.json`**: The structural AST specification containing bounds, layout directions, paddings, gaps, resolved token names, and component variant props.
+* **`.specs/<name>.png`**: The visual raster reference rendered directly by Figma (optional).
+
+This contract is subsequently consumed during the implementation phase by human developers or specialized builder skills like [`figma-node-builder`](../figma-node-builder).

package/figma-extractor/SKILL.md

@@ -0,0 +1,199 @@
+---
+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.'
+---
+
+# Figma Extractor Skill (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/`).
+
+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.
+
+---
+
+## 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 `/Applications` for browsers**: Do not search for installed browser binaries 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.
+
+---
+
+## Built-in Rate-Limit Gate & Circuit Breaker
+
+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`. 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.
+
+---
+
+## Prerequisites
+
+A Figma Access Token (Personal Access Token or OAuth Token) is required.
+
+Configure it using either:
+1. **Environment Variable**: `export FIGMA_ACCESS_TOKEN="figd_your_token_here"` or `export FIGMA_TOKEN="..."`
+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
+```
+
+---
+
+## 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 the skill's scripts directory:
+
+```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
+```
+
+**Script Path Resolution**:
+- **Global Antigravity install**: `node ~/.gemini/config/skills/figma-extractor/scripts/fetch_figma.js "<FigmaURL>" --spec <name>`
+- **Global Claude Code install**: `node ~/.claude/skills/figma-extractor/scripts/fetch_figma.js "<FigmaURL>" --spec <name>`
+- **Project local install**: `node figma-extractor/scripts/fetch_figma.js "<FigmaURL>" --spec <name>`
+
+---
+
+## Usage & Command Formats
+
+### 1. Atomic Spec Extraction (Recommended SDD Workflow)
+
+Extract node metadata directly into `./.specs/`:
+
+```bash
+# Atomic AST extraction (1 Tier 1 call - recommended)
+node figma-extractor/scripts/fetch_figma.js "https://www.figma.com/design/:fileKey/:name?node-id=4023-474" --spec card
+
+# Optional: With rendered preview image (2 Tier 1 calls)
+node figma-extractor/scripts/fetch_figma.js "https://www.figma.com/design/:fileKey/:name?node-id=4023-474" --spec card -i
+
+# Shallow instances mode (collapses internal component layers into clean props)
+node figma-extractor/scripts/fetch_figma.js "https://www.figma.com/design/:fileKey/:name?node-id=4023-474" --spec card --shallow-instances
+```
+
+### 2. Design Tokens Dictionary Mode
+
+```bash
+# Export only the file's design token dictionary (colors, spacing, radii)
+node figma-extractor/scripts/fetch_figma.js "https://www.figma.com/design/:fileKey/:name" --tokens > ./.specs/tokens.json
+```
+
+### 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. |
+
+---
+
+## 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"
+    }
+  ]
+}
+```
+
+### 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 }
+}
+```
+
+---
+
+## 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 → Personal Access Tokens** and export `FIGMA_ACCESS_TOKEN=your_token` or update `.env`.
+- **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`.