@pedroab0/skills 1.0.1 → 1.2.0

package/figma-node-builder/SKILL.md

@@ -39,14 +39,13 @@ Before writing any code, inspect the host project to ground your implementation:
 ### 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** to get a compact summary:
+> **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
-> # Global Antigravity install:
-> node ~/.gemini/config/skills/figma-node-builder/scripts/inspect_spec.js .specs/<name>.json
-> # Or project local install:
-> node figma-node-builder/scripts/inspect_spec.js .specs/<name>.json
+> # 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
+> 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 }`).
@@ -54,10 +53,10 @@ Analyze the input JSON spec (`.specs/<name>.json`).
 * **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:
+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**:
+   - 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>

package/figma-node-builder/scripts/inspect_spec.js

@@ -28,9 +28,21 @@ const style = {
 };
 
 // -----------------------------------------------------------------------------
-// Path Resolution
+// Path & Encoding Resolution
 // -----------------------------------------------------------------------------
 
+function decodeTextBuffer(buf) {
+  if (!Buffer.isBuffer(buf)) {
+    const str = String(buf || '');
+    return str.charCodeAt(0) === 0xfeff ? str.slice(1) : str;
+  }
+  if (buf.length >= 2 && buf[0] === 0xff && buf[1] === 0xfe) {
+    return buf.toString('utf16le', 2);
+  }
+  const str = buf.toString('utf8');
+  return str.charCodeAt(0) === 0xfeff ? str.slice(1) : str;
+}
+
 function resolveSpecPath(inputPath) {
   if (!inputPath || typeof inputPath !== 'string') {
     throw new Error('Please specify a specification file (e.g. .specs/card.json or card)');
@@ -480,7 +492,7 @@ function main() {
 
   try {
     const resolvedPath = resolveSpecPath(positional[0]);
-    const rawContent = fs.readFileSync(resolvedPath, 'utf8');
+    const rawContent = decodeTextBuffer(fs.readFileSync(resolvedPath));
     const parsedData = JSON.parse(rawContent);
 
     const inspection = inspectSpec(parsedData, resolvedPath);
@@ -507,6 +519,7 @@ if (require.main === module) {
 }
 
 module.exports = {
+  decodeTextBuffer,
   resolveSpecPath,
   inspectSpec,
   formatTerminalReport,

package/figma-to-code/README.md

@@ -74,10 +74,16 @@ Choose one of the following terminal commands:
   ```bash
   export FIGMA_ACCESS_TOKEN="figd_your_token_here"
   ```
-- **Persist globally across all terminal sessions (`~/.zshrc`)**:
+- **Persist globally on macOS / Linux (`~/.zshrc`)**:
   ```bash
   echo 'export FIGMA_ACCESS_TOKEN="figd_your_token_here"' >> ~/.zshrc && source ~/.zshrc
   ```
+- **Persist globally on Windows (PowerShell)**:
+  ```powershell
+  [Environment]::SetEnvironmentVariable("FIGMA_ACCESS_TOKEN", "figd_your_token_here", "User")
+  # Or inside your PowerShell profile ($PROFILE):
+  # $env:FIGMA_ACCESS_TOKEN="figd_your_token_here"
+  ```
 
 *(Optional: If behind a corporate proxy with self-signed SSL certificates, run `echo 'FIGMA_IGNORE_SSL=true' >> .env`).*
 
@@ -88,7 +94,7 @@ Flags are **completely optional** — you do not have to specify any 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`:
+- **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 agent instructions file (e.g., `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.kiro/steering/`, or `.cursor/rules/`):
   ```markdown
   ## Figma UI Development
   Whenever a Figma link is provided or you are asked to build UI from Figma:
@@ -142,9 +148,9 @@ node figma-to-code/scripts/fetch_figma.js "<FigmaURL>" -i --shallow-instances
 
 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.
+- **Agent Instruction Guide (`SKILL.md`)**: The core skill definition read by AI agents (Claude Code, Kiro, Cursor, OpenCode, Codex, Antigravity) 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.
+- **Unit Test Suite (`scripts/test_fetch_figma.js`)**: Automated unit tests verifying environment/profile parsing, 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.
 

package/figma-to-code/SKILL.md

@@ -17,7 +17,7 @@ This skill connects to the Figma REST API, extracts a compact design-system-awar
 > **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.
+> 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.
 
 ---
@@ -27,7 +27,7 @@ This skill connects to the Figma REST API, extracts a compact design-system-awar
 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.
+* **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.
@@ -41,7 +41,9 @@ To protect your Figma file quota and prevent lockout penalties, `fetch_figma.js`
 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="..."`
+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
@@ -66,20 +68,20 @@ FIGMA_IGNORE_SSL=true
 
 ## Agent Execution Instructions
 
-To extract and build UI from a Figma URL, run `fetch_figma.js` from the skill's scripts directory:
+To extract and build UI from a Figma URL, run `fetch_figma.js` from this skill's `scripts/` directory:
 
 ```bash
 # Recommended: Extract compact AST (1 Tier 1 call)
-node <skill-dir>/scripts/fetch_figma.js "<FigmaURL>"
+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
+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>"`
+**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`).
 
 ---
 
@@ -89,13 +91,13 @@ node <skill-dir>/scripts/fetch_figma.js "<FigmaURL>" -i
 
 ```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"
+node "<skill-dir>/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
+node "<skill-dir>/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
+node "<skill-dir>/scripts/fetch_figma.js" "https://www.figma.com/design/:fileKey/:name?node-id=4023-474" --shallow-instances
 ```
 
 ### 2. CLI Flags Reference
@@ -169,7 +171,7 @@ When an `INSTANCE` node is present, internal property hashes are converted into
 
 ## How to Build Components from the Extracted Data
 
-When synthesizing code from the output:
+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`:
@@ -202,10 +204,10 @@ When synthesizing code from the output:
 
 - **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`.
+  - 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 export it in their environment.
+  - 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.