@pedroab0/skills 0.0.0-stage → 1.0.0

package/figma-to-code/README.md

@@ -0,0 +1,160 @@
+# Figma To Code
+
+A lightweight, token-efficient skill designed for AI coding agents to turn Figma designs into clean UI code.
+
+---
+
+## 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 (Step-by-Step)
+
+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. **Visual Asset Download & Delivery**  
+   Downloads a sharp PNG preview of the frame to a local folder and delivers the cleaned data directly to the AI agent.
+
+---
+
+## 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
+Flags are **completely optional** — you do not have to specify any flags:
+- **Default (No flags needed)**: Simply share a Figma link or ask the agent to inspect a frame. The agent detects the link and runs the extractor automatically with default settings (clean, token-optimized JSON).
+- **Optional Guidance**: You can optionally guide the agent using natural language or by mentioning specific flags:
+  - *"Inspect this frame and download a preview image"* (agent uses `--image` or `-i`).
+  - *"Only extract the design tokens from this file"* (agent uses `--tokens`).
+  - *"Collapse component sub-layers into props"* (agent uses `--shallow-instances`).
+- **Tip (Guarantee Autonomous Invocation)**: To ensure the agent never skips the extractor and never estimates CSS without extracting, add this suggestion to your project's `GEMINI.md` or `AGENTS.md`:
+  ```markdown
+  ## Figma UI Development
+  Whenever a Figma link is provided or you are asked to build UI from Figma:
+  1. Use the `figma-to-code` skill to extract design tokens, component props, and preview images.
+  2. Ground all styling and component props in the extracted data rather than guessing CSS.
+  ```
+
+### 3. Manual Command Formats
+You can also run the script directly from your terminal:
+
+```bash
+# Basic JSON extraction (compact layout & styling to stdout)
+node figma-to-code/scripts/fetch_figma.js "<FigmaURL>"
+
+# JSON + automatically download a rendered image preview
+node figma-to-code/scripts/fetch_figma.js "<FigmaURL>" -i
+
+# Save preview image to a custom local path
+node figma-to-code/scripts/fetch_figma.js "<FigmaURL>" -o ./.specs/preview.png
+
+# Extract only design tokens (colors, spacing, radii)
+node figma-to-code/scripts/fetch_figma.js "<FigmaURL>" --tokens
+
+# Collapse component layers into clean props
+node figma-to-code/scripts/fetch_figma.js "<FigmaURL>" -i --shallow-instances
+```
+
+---
+
+## Available Flags
+
+| 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 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. |
+
+---
+
+## Available Resources
+
+The skill includes the following resources:
+
+- **Agent Instruction Guide (`SKILL.md`)**: The core skill definition read by AI agents (Antigravity, Claude Code, Cursor, Codex) containing workflow triggers and pair-programming guidelines.
+- **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 39 automated unit tests verifying URL parsing, token formatting, component prop cleaning, rate-limit gates, and node pruning without requiring network access.
+- **Specification Directory (`.specs/`)**: The local workspace directory where downloaded image previews are stored for multimodal visual inspection.
+- **Reference Documentation (`README.md`)**: This guide explaining architecture, MCP comparison, and operational flags.
+
+---
+
+## How AI Agents Build UI From This Data
+
+- **Use Existing Components**: When the output identifies a component name and props, the agent imports that component instead of building it from scratch.
+- **Apply Design Tokens**: When spacing or color tokens are present, the agent applies framework classes (like Tailwind) or CSS variables instead of hardcoded numbers.
+- **Match Flexbox Layout**: Layout directions, gaps, and alignments directly translate to standard CSS Flexbox or Grid properties.
+- **Resolve Icons Cleanly**: Reuses existing project icons/assets (`components/icons/`, `src/assets/`, `public/`) or installed libraries (`lucide-react`, `@heroicons/react`), preventing hallucinated SVG paths.
+- **Style Image Layers**: Applies exact dimensions, border radius, and object-fit from Figma image fills, leaving clean `<img>` tags with `TODO` markers.
+- **Cross-Check Visually**: The agent inspects the downloaded preview image to ensure the final code matches the designer's intent.

package/figma-to-code/SKILL.md

@@ -0,0 +1,211 @@
+---
+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.'
+---
+
+# Figma To Code Skill
+
+Directly convert Figma designs into clean, production-ready UI components in a single turn. 
+
+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.
+
+---
+
+## 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**: 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
+
+To extract and build UI from a Figma URL, run `fetch_figma.js` from the skill's scripts directory:
+
+```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
+```
+
+**Script Path Resolution**:
+- **Global Antigravity install**: `node ~/.gemini/config/skills/figma-to-code/scripts/fetch_figma.js "<FigmaURL>"`
+- **Global Claude Code install**: `node ~/.claude/skills/figma-to-code/scripts/fetch_figma.js "<FigmaURL>"`
+- **Project local install**: `node figma-to-code/scripts/fetch_figma.js "<FigmaURL>"`
+
+---
+
+## Usage & Command Formats
+
+### 1. Basic One-Shot Code Generation
+
+```bash
+# Standard extraction (1 Tier 1 call - recommended)
+node figma-to-code/scripts/fetch_figma.js "https://www.figma.com/design/:fileKey/:name?node-id=4023-474"
+
+# Optional: With preview image (2 Tier 1 calls)
+node figma-to-code/scripts/fetch_figma.js "https://www.figma.com/design/:fileKey/:name?node-id=4023-474" -i
+
+# Collapse internal layers of component instances into props (guides agent to reuse existing components)
+node figma-to-code/scripts/fetch_figma.js "https://www.figma.com/design/:fileKey/:name?node-id=4023-474" --shallow-instances
+```
+
+### 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. |
+
+---
+
+## 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"
+    }
+  ]
+}
+```
+
+### 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 }
+}
+```
+
+---
+
+## How to Build Components from the Extracted Data
+
+When synthesizing code from the output:
+
+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.
+
+---
+
+## 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 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.
+- **Corporate Proxy / Self-Signed SSL (`FIGMA_SSL_CERTIFICATE_ERROR`)**:
+  - Instruct the user to add `FIGMA_IGNORE_SSL=true` to `.env` or export 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.