@pedroab0/skills 1.0.1 → 1.1.0

package/figma-extractor/scripts/fetch_figma.js

@@ -11,27 +11,138 @@ const { URL } = require('url');
 // Environment and Auth Utilities
 // -----------------------------------------------------------------------------
 
-function loadEnv() {
-  const home = process.env.HOME || '';
-  const candidates = [
-    path.join(process.cwd(), '.env'),
+function resolveHomeDir() {
+  return (
+    process.env.HOME ||
+    process.env.USERPROFILE ||
+    (typeof os.homedir === 'function' ? os.homedir() : '') ||
+    ''
+  );
+}
+
+function decodeEnvBuffer(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 getPowerShellProfilePaths(home) {
+  const paths = [];
+  if (process.env.PROFILE && process.env.PROFILE.toLowerCase().endsWith('.ps1')) {
+    paths.push(process.env.PROFILE);
+  }
+
+  const docRoots = [];
+  if (home) {
+    docRoots.push(
+      path.join(home, 'Documents'),
+      path.join(home, 'Documentos'),
+      path.join(home, 'OneDrive', 'Documents'),
+      path.join(home, 'OneDrive', 'Documentos'),
+    );
+  }
+
+  const oneDriveEnvs = [
+    process.env.OneDrive,
+    process.env.OneDriveConsumer,
+    process.env.OneDriveCommercial,
+  ].filter(Boolean);
+
+  for (const od of oneDriveEnvs) {
+    docRoots.push(path.join(od, 'Documents'), path.join(od, 'Documentos'));
+  }
+
+  const shellDirs = ['PowerShell', 'WindowsPowerShell'];
+  const profileFiles = [
+    'Microsoft.PowerShell_profile.ps1',
+    'Microsoft.VSCode_profile.ps1',
+    'profile.ps1',
+  ];
+
+  for (const docRoot of docRoots) {
+    if (!fs.existsSync(docRoot)) continue;
+    for (const shellDir of shellDirs) {
+      const fullShellDir = path.join(docRoot, shellDir);
+      if (!fs.existsSync(fullShellDir)) continue;
+      for (const profileFile of profileFiles) {
+        paths.push(path.join(fullShellDir, profileFile));
+      }
+    }
+  }
+
+  if (home) {
+    const xdgPsDir = path.join(process.env.XDG_CONFIG_HOME || path.join(home, '.config'), 'powershell');
+    if (fs.existsSync(xdgPsDir)) {
+      for (const profileFile of profileFiles) {
+        paths.push(path.join(xdgPsDir, profileFile));
+      }
+    }
+  }
+
+  return Array.from(new Set(paths));
+}
+
+function loadEnv(options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const home = options.home !== undefined ? options.home : resolveHomeDir();
+
+  const dotEnvCandidates = [
+    path.join(cwd, '.env'),
+    path.join(cwd, '.env.local'),
     home ? path.join(home, '.env') : null,
+  ].filter(Boolean);
+
+  const shellConfigCandidates = [
     home ? path.join(home, '.zshrc') : null,
+    home ? path.join(home, '.zprofile') : null,
+    home ? path.join(home, '.zshenv') : null,
     home ? path.join(home, '.bashrc') : null,
+    home ? path.join(home, '.bash_profile') : null,
+    home ? path.join(home, '.profile') : null,
+    ...getPowerShellProfilePaths(home),
   ].filter(Boolean);
 
-  for (const envPath of candidates) {
-    if (fs.existsSync(envPath)) {
+  const seen = new Set();
+  const candidates = [];
+  for (const p of dotEnvCandidates) {
+    if (!seen.has(p)) {
+      seen.add(p);
+      candidates.push({ filePath: p, isShellConfig: false });
+    }
+  }
+  for (const p of shellConfigCandidates) {
+    if (!seen.has(p)) {
+      seen.add(p);
+      candidates.push({ filePath: p, isShellConfig: true });
+    }
+  }
+
+  for (const { filePath, isShellConfig } of candidates) {
+    if (fs.existsSync(filePath)) {
       try {
-        const envContent = fs.readFileSync(envPath, 'utf8');
-        const lines = envContent.split('\n');
+        const rawBuf = fs.readFileSync(filePath);
+        const envContent = decodeEnvBuffer(rawBuf);
+        if (isShellConfig && !/figma_/i.test(envContent)) {
+          continue;
+        }
+        const lines = envContent.split(/\r?\n/);
         for (const line of lines) {
+          if (isShellConfig && !/figma_/i.test(line)) {
+            continue;
+          }
           const parsed = parseEnvLine(line);
           if (parsed && parsed.key) {
+            const isFigmaVar = /^FIGMA_/i.test(parsed.key);
+            const envKey = isFigmaVar ? parsed.key.toUpperCase() : parsed.key;
             // For dot-env files, load any variable; for shell configs, only load FIGMA_ variables
-            const isShellConfig = envPath.endsWith('.zshrc') || envPath.endsWith('.bashrc');
-            if (!process.env[parsed.key] && (!isShellConfig || parsed.key.startsWith('FIGMA_'))) {
-              process.env[parsed.key] = parsed.val;
+            if (!process.env[envKey] && (!isShellConfig || isFigmaVar)) {
+              process.env[envKey] = parsed.val;
             }
           }
         }
@@ -44,16 +155,47 @@ function loadEnv() {
 
 function parseEnvLine(line) {
   if (!line || typeof line !== 'string') return null;
-  let trimmed = line.trim();
-  if (trimmed.startsWith('export ')) {
-    trimmed = trimmed.substring(7).trim();
+  let trimmed = line.replace(/^\uFEFF/, '').trim();
+  if (!trimmed || trimmed.startsWith('#')) {
+    return null;
+  }
+
+  // Handle PowerShell [Environment]::SetEnvironmentVariable("KEY", "VAL", ...)
+  const setEnvMatch = trimmed.match(
+    /^\[(?:System\.)?Environment\]::SetEnvironmentVariable\(\s*(['"])([A-Za-z_][A-Za-z0-9_]*)\1\s*,\s*(['"])([^'"]*)\3/i,
+  );
+  if (setEnvMatch) {
+    return { key: setEnvMatch[2], val: setEnvMatch[4] };
   }
-  if (!trimmed || trimmed.startsWith('#') || !trimmed.includes('=')) {
+
+  // Strip Unix 'export ' or Windows CMD 'set ' prefix (requires whitespace after keyword)
+  if (/^export\s+/i.test(trimmed)) {
+    trimmed = trimmed.replace(/^export\s+/i, '').trim();
+  } else if (/^set\s+/i.test(trimmed)) {
+    trimmed = trimmed.replace(/^set\s+/i, '').trim();
+    if (trimmed.startsWith('"') && trimmed.endsWith('"') && trimmed.includes('=')) {
+      trimmed = trimmed.slice(1, -1).trim();
+    }
+  }
+
+  if (!trimmed.includes('=')) {
     return null;
   }
 
   const eqIdx = trimmed.indexOf('=');
-  const key = trimmed.slice(0, eqIdx).trim();
+  let key = trimmed.slice(0, eqIdx).trim();
+
+  // Strip PowerShell $env:KEY or ${env:KEY} syntax
+  if (/^\$env:/i.test(key)) {
+    key = key.replace(/^\$env:/i, '').trim();
+  } else if (/^\$\{env:([^}]+)\}$/i.test(key)) {
+    key = key.replace(/^\$\{env:([^}]+)\}$/i, '$1').trim();
+  }
+
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
+    return null;
+  }
+
   let rest = trimmed.slice(eqIdx + 1).trim();
 
   let val = '';
@@ -566,7 +708,7 @@ const MAX_REQUESTS_PER_WINDOW = 5; // Max 5 calls per minute (well below Figma 1
 const MIN_REQUEST_INTERVAL_MS = 2500; // Minimum 2.5s between consecutive requests
 
 function getRateGateFilePath() {
-  const home = process.env.HOME || (typeof os.homedir === 'function' ? os.homedir() : '');
+  const home = resolveHomeDir();
   return home ? path.join(home, '.figma_ratelimit.json') : path.join(process.cwd(), '.figma_ratelimit.json');
 }
 
@@ -1132,15 +1274,24 @@ async function main() {
         process.exit(1);
       }
       const { dictionary } = buildVariableMap(varsMeta);
-      console.log(
-        JSON.stringify(
-          {
-            tokens: dictionary,
-          },
-          null,
-          config.pretty ? 2 : 0,
-        ),
+      const tokenPayload = JSON.stringify(
+        {
+          tokens: dictionary,
+        },
+        null,
+        config.pretty ? 2 : 0,
       );
+      if (config.specJsonPath) {
+        const jsonDir = path.dirname(path.resolve(config.specJsonPath));
+        if (!fs.existsSync(jsonDir)) {
+          fs.mkdirSync(jsonDir, { recursive: true });
+        }
+        fs.writeFileSync(path.resolve(config.specJsonPath), tokenPayload, 'utf8');
+        const sizeKb = (Buffer.byteLength(tokenPayload, 'utf8') / 1024).toFixed(1);
+        console.log(`\n✔ Saved Figma design tokens to ${config.specJsonPath} (${sizeKb} KB)\n`);
+      } else {
+        console.log(tokenPayload);
+      }
       return;
     }
 
@@ -1236,7 +1387,7 @@ function formatApiError(error) {
   } else if (error.statusCode === 401 || error.statusCode === 403) {
     isTokenExpiredOrInvalid = true;
     errorMessage =
-      'FIGMA_TOKEN_EXPIRED_OR_INVALID: The provided Figma access token is expired, invalid, or unauthorized. Create a new token in Figma Settings -> Personal Access Tokens and export FIGMA_ACCESS_TOKEN or add it to .env.';
+      'FIGMA_TOKEN_EXPIRED_OR_INVALID: The provided Figma access token is expired, invalid, or unauthorized. Create a new token in Figma Settings -> Personal Access Tokens and set FIGMA_ACCESS_TOKEN in your environment or workspace .env file.';
   } else if (error.statusCode === 429) {
     isRateLimited = true;
     let retryMsg = ' Please wait 30-60 seconds before making more requests.';
@@ -1284,6 +1435,9 @@ function formatApiError(error) {
 
 // Export internal functions for unit testing
 module.exports = {
+  resolveHomeDir,
+  decodeEnvBuffer,
+  getPowerShellProfilePaths,
   loadEnv,
   parseEnvLine,
   getFigmaToken,

package/figma-extractor/scripts/test_fetch_figma.js

@@ -1,7 +1,11 @@
 #!/usr/bin/env node
 
 const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
 const {
+  decodeEnvBuffer,
   loadEnv,
   parseEnvLine,
   parseFigmaUrl,
@@ -70,6 +74,88 @@ test('parseEnvLine: returns null for comments, empty lines, and lines without eq
   assert.strictEqual(parseEnvLine('export FIGMA_TOKEN'), null);
 });
 
+test('parseEnvLine: parses Windows PowerShell $env: syntax, CRLF, and SetEnvironmentVariable', () => {
+  assert.deepStrictEqual(
+    parseEnvLine('$env:FIGMA_ACCESS_TOKEN="figd_win_ps1"\r\n'),
+    { key: 'FIGMA_ACCESS_TOKEN', val: 'figd_win_ps1' }
+  );
+  assert.deepStrictEqual(
+    parseEnvLine("$Env:FIGMA_ACCESS_TOKEN = 'figd_win_single' # ps comment\r\n"),
+    { key: 'FIGMA_ACCESS_TOKEN', val: 'figd_win_single' }
+  );
+  assert.deepStrictEqual(
+    parseEnvLine('${env:FIGMA_TOKEN}="figd_braced"'),
+    { key: 'FIGMA_TOKEN', val: 'figd_braced' }
+  );
+  assert.deepStrictEqual(
+    parseEnvLine('[System.Environment]::SetEnvironmentVariable("FIGMA_ACCESS_TOKEN", "figd_sys_env", "User")'),
+    { key: 'FIGMA_ACCESS_TOKEN', val: 'figd_sys_env' }
+  );
+});
+
+test('parseEnvLine: parses Windows CMD set syntax without corrupting SETTINGS/EXPORT keys', () => {
+  assert.deepStrictEqual(
+    parseEnvLine('set FIGMA_ACCESS_TOKEN=figd_cmd_plain\r\n'),
+    { key: 'FIGMA_ACCESS_TOKEN', val: 'figd_cmd_plain' }
+  );
+  assert.deepStrictEqual(
+    parseEnvLine('set "FIGMA_ACCESS_TOKEN=figd_cmd_quoted"'),
+    { key: 'FIGMA_ACCESS_TOKEN', val: 'figd_cmd_quoted' }
+  );
+  assert.deepStrictEqual(
+    parseEnvLine('SETTINGS=enabled'),
+    { key: 'SETTINGS', val: 'enabled' }
+  );
+  assert.deepStrictEqual(
+    parseEnvLine('EXPORT_MODE=fast'),
+    { key: 'EXPORT_MODE', val: 'fast' }
+  );
+  // Arbitrary PowerShell local variables must not parse as env identifiers
+  assert.strictEqual(parseEnvLine('$MaximumHistoryCount = 4096'), null);
+});
+
+test('loadEnv & decodeEnvBuffer: loads FIGMA_ vars from UTF-16LE PowerShell profile and ignores non-FIGMA_ vars', () => {
+  const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'figma-win-env-'));
+  const savedAccess = process.env.FIGMA_ACCESS_TOKEN;
+  const savedOther = process.env.UNRELATED_PS_SECRET;
+  delete process.env.FIGMA_ACCESS_TOKEN;
+  delete process.env.UNRELATED_PS_SECRET;
+
+  try {
+    const psDir = path.join(tmpRoot, 'OneDrive', 'Documentos', 'WindowsPowerShell');
+    fs.mkdirSync(psDir, { recursive: true });
+    const psFile = path.join(psDir, 'Microsoft.PowerShell_profile.ps1');
+
+    const psContent = '$env:FIGMA_ACCESS_TOKEN="figd_utf16_powershell"\r\n$env:UNRELATED_PS_SECRET="should_not_leak"\r\n';
+    const utf16WithBom = Buffer.concat([Buffer.from([0xff, 0xfe]), Buffer.from(psContent, 'utf16le')]);
+    fs.writeFileSync(psFile, utf16WithBom);
+
+    assert.ok(decodeEnvBuffer(utf16WithBom).includes('figd_utf16_powershell'));
+
+    loadEnv({ cwd: tmpRoot, home: tmpRoot });
+    assert.strictEqual(process.env.FIGMA_ACCESS_TOKEN, 'figd_utf16_powershell');
+    assert.strictEqual(process.env.UNRELATED_PS_SECRET, undefined);
+
+    // Case-insensitive PowerShell $env:figma_access_token normalization
+    delete process.env.FIGMA_ACCESS_TOKEN;
+    fs.writeFileSync(psFile, '$env:figma_access_token="figd_lowercase_ps"\r\n', 'utf8');
+    loadEnv({ cwd: tmpRoot, home: tmpRoot });
+    assert.strictEqual(process.env.FIGMA_ACCESS_TOKEN, 'figd_lowercase_ps');
+
+    // Workspace .env must take precedence over shell profile
+    delete process.env.FIGMA_ACCESS_TOKEN;
+    fs.writeFileSync(path.join(tmpRoot, '.env'), 'FIGMA_ACCESS_TOKEN="figd_from_dotenv"\n', 'utf8');
+    loadEnv({ cwd: tmpRoot, home: tmpRoot });
+    assert.strictEqual(process.env.FIGMA_ACCESS_TOKEN, 'figd_from_dotenv');
+  } finally {
+    if (savedAccess !== undefined) process.env.FIGMA_ACCESS_TOKEN = savedAccess;
+    else delete process.env.FIGMA_ACCESS_TOKEN;
+    if (savedOther !== undefined) process.env.UNRELATED_PS_SECRET = savedOther;
+    else delete process.env.UNRELATED_PS_SECRET;
+    fs.rmSync(tmpRoot, { recursive: true, force: true });
+  }
+});
+
 // 1. URL Parsing Tests
 test('parseFigmaUrl: extracts fileKey and nodeId with hyphens', () => {
   const url = 'https://www.figma.com/design/1KP9pVQ1ptZzHa3Gcpr6ta/Consulta-e-pagamento?node-id=4023-474&t=abcd';
@@ -342,8 +428,8 @@ test('parseArguments: --spec sets atomic specJsonPath and companion imagePath',
   const argv = ['node', 'fetch_figma.js', 'https://www.figma.com/design/xyz123/Test?node-id=1-2', '--spec', 'card'];
   const res = parseArguments(argv);
   assert.strictEqual(res.specName, 'card');
-  assert.strictEqual(res.specJsonPath, '.specs/card.json');
-  assert.strictEqual(res.imagePath, '.specs/card.png');
+  assert.strictEqual(res.specJsonPath, path.join('.specs', 'card.json'));
+  assert.strictEqual(res.imagePath, path.join('.specs', 'card.png'));
   assert.strictEqual(res.downloadImage, false, 'Default --spec must NOT download image to conserve Tier 1 quota');
 
   const argvWithImage = ['node', 'fetch_figma.js', 'https://www.figma.com/design/xyz123/Test?node-id=1-2', '--spec', 'card', '-i'];
@@ -353,8 +439,8 @@ test('parseArguments: --spec sets atomic specJsonPath and companion imagePath',
 
   const argvCustom = ['node', 'fetch_figma.js', 'xyz123', '1:2', '--spec', 'custom/dir/navbar.json'];
   const resCustom = parseArguments(argvCustom);
-  assert.strictEqual(resCustom.specJsonPath, 'custom/dir/navbar.json');
-  assert.strictEqual(resCustom.imagePath, 'custom/dir/navbar.png');
+  assert.strictEqual(resCustom.specJsonPath, path.join('custom', 'dir', 'navbar.json'));
+  assert.strictEqual(resCustom.imagePath, path.join('custom', 'dir', 'navbar.png'));
   assert.strictEqual(resCustom.downloadImage, false);
 });
 

package/figma-node-builder/README.md

@@ -67,7 +67,7 @@ When invoked, the agent systematically executes four phases:
 
 ## How to Use the Skill
 
-Simply prompt your AI coding assistant (Claude Code, Cursor, OpenCode, Codex, or Antigravity):
+Simply prompt your AI coding assistant (Claude Code, Kiro, Cursor, OpenCode, Codex, or Antigravity):
 
 ```text
 "Build the component from .specs/transaction-card.json using .specs/transaction-card.png as visual reference"

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-node-builder/scripts/test_inspect_spec.js

@@ -4,7 +4,9 @@ const assert = require('assert');
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
+const { execSync } = require('child_process');
 const {
+  decodeTextBuffer,
   resolveSpecPath,
   inspectSpec,
   formatTerminalReport,
@@ -141,8 +143,21 @@ try {
   } finally {
     process.chdir(origCwd);
   }
+
+  // 7. decodeTextBuffer & CLI UTF-8 BOM / UTF-16LE BOM resilience (Windows PowerShell 5.1 & Notepad)
+  const utf8BomFile = path.join(specsSubdir, 'utf8bom.json');
+  fs.writeFileSync(utf8BomFile, '\uFEFF' + JSON.stringify(mockSpec), 'utf8');
+  const utf16BomFile = path.join(specsSubdir, 'utf16le.json');
+  const utf16Buf = Buffer.concat([Buffer.from([0xff, 0xfe]), Buffer.from(JSON.stringify(mockSpec), 'utf16le')]);
+  fs.writeFileSync(utf16BomFile, utf16Buf);
+
+  assert.strictEqual(JSON.parse(decodeTextBuffer(fs.readFileSync(utf8BomFile))).name, 'Product Card');
+  assert.strictEqual(JSON.parse(decodeTextBuffer(fs.readFileSync(utf16BomFile))).name, 'Product Card');
+  const cliOut = execSync(`node "${path.join(__dirname, 'inspect_spec.js')}" "${utf16BomFile}" --markdown`, { encoding: 'utf8' });
+  assert.ok(cliOut.includes('Product Card'));
+  console.log('  ✓ decodeTextBuffer & CLI: parses UTF-8 BOM and UTF-16LE BOM specs cleanly');
 } finally {
   fs.rmSync(tmpDir, { recursive: true, force: true });
 }
 
-console.log('\nResults: 6/6 Spec Inspector tests passed.\n');
+console.log('\nResults: 7/7 Spec Inspector tests passed.\n');

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.