@pedroab0/skills 1.0.1 → 1.2.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;
   }
-  if (!trimmed || trimmed.startsWith('#') || !trimmed.includes('=')) {
+
+  // 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] };
+  }
+
+  // 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 = '';
@@ -409,13 +551,234 @@ function normalizeComponentProps(componentProperties) {
 // AST Pruning & Token Optimization
 // -----------------------------------------------------------------------------
 
-function pruneFigmaNode(node, context = {}, options = {}) {
+const VECTOR_PRIMITIVE_TYPES = new Set([
+  'VECTOR',
+  'BOOLEAN_OPERATION',
+  'STAR',
+  'LINE',
+  'REGULAR_POLYGON',
+  'POLYGON',
+]);
+
+function cleanLayerName(rawName, fallback = 'Node') {
+  if (!rawName || typeof rawName !== 'string') return fallback;
+  const trimmed = rawName.trim();
+  if (!trimmed) return fallback;
+  if (/^data:image\//i.test(trimmed)) return 'Image';
+  if (/^(?:<svg\b|<\?xml\b)/i.test(trimmed)) return 'SVG';
+  if (/^https?:\/\//i.test(trimmed) && trimmed.length > 60) {
+    try {
+      const lastSeg = trimmed.split('?')[0].split('/').pop();
+      return lastSeg && lastSeg.length <= 60 ? lastSeg : 'Image';
+    } catch (_) {
+      return 'Image';
+    }
+  }
+  const singleLine = trimmed.replace(/\s+/g, ' ');
+  return singleLine.length > 80 ? singleLine.slice(0, 80) + '…' : singleLine;
+}
+
+function isRawAssetString(str) {
+  if (!str || typeof str !== 'string') return false;
+  const t = str.trim();
+  return /^data:image\//i.test(t) || /^(?:<svg\b|<\?xml\b)/i.test(t);
+}
+
+function nodeHasImageFill(node) {
+  return Array.isArray(node.fills) && node.fills.some((f) => f && f.visible !== false && f.type === 'IMAGE');
+}
+
+const GRAPHIC_NAME_RE =
+  /svg|icon|ícone|icone|logo|marca|brand|illustrat|ilustra|vector|vetor|symbol|simbol|símbolo|glyph|graphic|ornament|pattern|artwork/i;
+
+function hasSvgExportSetting(node) {
+  if (!Array.isArray(node.exportSettings) || node.exportSettings.length === 0) return false;
+  return node.exportSettings.some((s) => s && String(s.format || '').toUpperCase() === 'SVG');
+}
+
+function subtreeHasNoInstances(node, maxNodes = 400) {
+  let visited = 0;
+  function walk(curr, isRoot) {
+    if (!curr || typeof curr !== 'object' || ++visited > maxNodes) return false;
+    const t = curr.type || '';
+    if (!isRoot && (t === 'INSTANCE' || t === 'COMPONENT' || t === 'COMPONENT_SET')) return false;
+    const kids = Array.isArray(curr.children) ? curr.children.filter((c) => c && c.visible !== false) : [];
+    for (const k of kids) {
+      if (!walk(k, false)) return false;
+    }
+    return true;
+  }
+  return walk(node, true);
+}
+
+function analyzeVectorSubtree(node, varMap, maxNodes = 600) {
+  let visited = 0;
+  let vectorPrimitiveCount = 0;
+  let shapeCount = 0;
+  let plainRectCount = 0;
+  let primaryFill = null;
+
+  const rootType = node.type || '';
+  const hasSvgExport = hasSvgExportSetting(node);
+
+  // Preserve Auto-Layout wrapper frames with their own styling (e.g., Icon Badge) unless explicitly exported as SVG
+  if (rootType === 'FRAME' && !hasSvgExport && node.layoutMode && node.layoutMode !== 'NONE') {
+    const ownFills = simplifyFills(node.fills, node.boundVariables || {}, varMap);
+    const ownStrokes = simplifyStrokes(node.strokes, node.strokeWeight, node.strokeAlign, node.boundVariables || {}, varMap);
+    if (ownFills || ownStrokes || node.cornerRadius) {
+      return { isPure: false, primaryFill: null };
+    }
+  }
+
+  function check(curr, isRoot) {
+    if (!curr || typeof curr !== 'object' || ++visited > maxNodes) return false;
+    const t = curr.type || '';
+    if (t === 'TEXT' || t === 'SLICE' || t === 'STICKY' || t === 'TABLE') return false;
+    if (!isRoot && (t === 'INSTANCE' || t === 'COMPONENT' || t === 'COMPONENT_SET')) return false;
+    if (nodeHasImageFill(curr)) return false;
+
+    if (!primaryFill) {
+      const fills = simplifyFills(curr.fills, curr.boundVariables || {}, varMap);
+      const solidFill = fills && fills.find((f) => f.type === 'SOLID' && f.color);
+      if (solidFill) {
+        primaryFill = solidFill;
+      } else {
+        const strokes = simplifyStrokes(curr.strokes, curr.strokeWeight, curr.strokeAlign, curr.boundVariables || {}, varMap);
+        if (strokes && strokes.colors && strokes.colors[0]) {
+          const c0 = strokes.colors[0];
+          primaryFill = typeof c0 === 'object' ? { type: 'SOLID', ...c0 } : { type: 'SOLID', color: c0 };
+        }
+      }
+    }
+
+    if (VECTOR_PRIMITIVE_TYPES.has(t)) {
+      vectorPrimitiveCount++;
+      return true;
+    }
+
+    if (t === 'ELLIPSE') {
+      shapeCount++;
+      return true;
+    }
+
+    if (t === 'RECTANGLE') {
+      if (curr.isMask === true || /clip|mask|vector|path|rect|bound|bg/i.test(String(curr.name || ''))) {
+        shapeCount++;
+      } else {
+        plainRectCount++;
+      }
+      return true;
+    }
+
+    if (t === 'GROUP' || t === 'FRAME' || (isRoot && (t === 'INSTANCE' || t === 'COMPONENT'))) {
+      if (!isRoot && t === 'FRAME' && curr.layoutMode && curr.layoutMode !== 'NONE') {
+        return false;
+      }
+      const kids = Array.isArray(curr.children) ? curr.children.filter((c) => c && c.visible !== false) : [];
+      if (kids.length === 0) return !isRoot;
+      for (const k of kids) {
+        if (!check(k, false)) return false;
+      }
+      return true;
+    }
+
+    return false;
+  }
+
+  const treeOk = check(node, true);
+  const w = node.absoluteBoundingBox ? node.absoluteBoundingBox.width : 9999;
+  const h = node.absoluteBoundingBox ? node.absoluteBoundingBox.height : 9999;
+
+  if (!treeOk) {
+    if (hasSvgExport && w <= 800 && h <= 800 && !nodeHasImageFill(node) && subtreeHasNoInstances(node)) {
+      return { isPure: true, primaryFill };
+    }
+    return { isPure: false, primaryFill: null };
+  }
+
+  const isSmallGraphic = w <= 160 && h <= 160;
+  const hasGraphicName = GRAPHIC_NAME_RE.test(String(node.name || ''));
+
+  const hasEnoughPrimitives =
+    vectorPrimitiveCount > 0 ||
+    (shapeCount + plainRectCount >= 2 && (hasSvgExport || (isSmallGraphic && hasGraphicName)));
+
+  const rectGuardOk =
+    plainRectCount === 0 ||
+    vectorPrimitiveCount >= 2 ||
+    isSmallGraphic ||
+    hasGraphicName ||
+    hasSvgExport;
+
+  const isPure = hasEnoughPrimitives && rectGuardOk;
+  return { isPure, primaryFill };
+}
+
+function analyzeMaskedImageSubtree(node) {
+  const t = node.type || '';
+  if (t !== 'GROUP' && t !== 'FRAME') return null;
+  if (node.layoutMode && node.layoutMode !== 'NONE') return null;
+
+  const kids = Array.isArray(node.children) ? node.children.filter((c) => c && c.visible !== false) : [];
+  if (kids.length === 0 || kids.length > 20) return null;
+
+  let foundImageFill = false;
+  let hasMaskOrClip = false;
+
+  function scan(curr) {
+    const ct = curr.type || '';
+    if (ct === 'TEXT' || ct === 'INSTANCE' || ct === 'COMPONENT') return false;
+    if (curr.isMask === true) hasMaskOrClip = true;
+    if (nodeHasImageFill(curr)) foundImageFill = true;
+
+    const sub = Array.isArray(curr.children) ? curr.children.filter((c) => c && c.visible !== false) : [];
+    for (const s of sub) {
+      if (!scan(s)) return false;
+    }
+    return true;
+  }
+
+  if (!scan(node) || !foundImageFill) return null;
+  if (!hasMaskOrClip && !/mask|image|img|photo|avatar|banner|thumb/i.test(String(node.name || ''))) {
+    return null;
+  }
+  return true;
+}
+
+function pruneFigmaNode(node, context = {}, options = {}, _depth = 0) {
   if (!node || typeof node !== 'object') return node;
 
   const { varMap, components, componentSets } = context;
+  const cleanName = cleanLayerName(node.name, 'Node');
+  const bound = node.boundVariables || {};
+  const bounds = node.absoluteBoundingBox
+    ? {
+        width: Math.round(node.absoluteBoundingBox.width),
+        height: Math.round(node.absoluteBoundingBox.height),
+      }
+    : undefined;
+
+  // 1. Leaf Vector Primitives (VECTOR, BOOLEAN_OPERATION, STAR, LINE, POLYGON)
+  if (VECTOR_PRIMITIVE_TYPES.has(node.type)) {
+    const vecNode = { name: cleanName, type: 'VECTOR' };
+    if (options.includeIds && node.id) vecNode.id = node.id;
+    if (node.visible === false) vecNode.visible = false;
+    if (bounds) vecNode.bounds = bounds;
+    const fills = simplifyFills(node.fills, bound, varMap);
+    if (fills) {
+      vecNode.fills = fills;
+    } else {
+      const strokes = simplifyStrokes(node.strokes, node.strokeWeight, node.strokeAlign, bound, varMap);
+      if (strokes && strokes.colors && strokes.colors[0]) {
+        const c0 = strokes.colors[0];
+        vecNode.fills = [typeof c0 === 'object' ? { type: 'SOLID', ...c0 } : { type: 'SOLID', color: c0 }];
+      }
+    }
+    return vecNode;
+  }
 
   const pruned = {
-    name: node.name,
+    name: cleanName,
     type: node.type,
   };
 
@@ -425,16 +788,14 @@ function pruneFigmaNode(node, context = {}, options = {}) {
 
   if (node.visible === false) pruned.visible = false;
 
-  const bound = node.boundVariables || {};
-
   // Component Instance & Master Resolution
   if (node.type === 'INSTANCE') {
     if (node.componentId && components && components[node.componentId]) {
       const master = components[node.componentId];
       const set = master.componentSetId && componentSets ? componentSets[master.componentSetId] : null;
       pruned.component = {
-        name: set ? set.name : master.name,
-        variant: master.name,
+        name: cleanLayerName(set ? set.name : master.name, cleanName),
+        variant: cleanLayerName(master.name, cleanName),
       };
       if (options.includeIds) {
         pruned.component.id = node.componentId;
@@ -446,12 +807,7 @@ function pruneFigmaNode(node, context = {}, options = {}) {
 
     // Shallow instances: skip internal rendering sub-layers if requested
     if (options.shallowInstances) {
-      if (node.absoluteBoundingBox) {
-        pruned.bounds = {
-          width: Math.round(node.absoluteBoundingBox.width),
-          height: Math.round(node.absoluteBoundingBox.height),
-        };
-      }
+      if (bounds) pruned.bounds = bounds;
       return pruned;
     }
   } else if (node.type === 'COMPONENT' || node.type === 'COMPONENT_SET') {
@@ -459,11 +815,42 @@ function pruneFigmaNode(node, context = {}, options = {}) {
     if (props) pruned.props = props;
   }
 
+  // 2. Collapse Pure SVG / Icon / Vector Graphic Containers
+  if (_depth > 0 || node.type === 'GROUP' || node.type === 'INSTANCE') {
+    const vecCheck = analyzeVectorSubtree(node, varMap);
+    if (vecCheck.isPure) {
+      if (node.type !== 'INSTANCE' && node.type !== 'COMPONENT') {
+        pruned.type = 'VECTOR';
+        pruned.isSvg = true;
+      }
+      if (bounds) pruned.bounds = bounds;
+      const ownFills = simplifyFills(node.fills, bound, varMap);
+      if (ownFills) {
+        pruned.fills = ownFills;
+      } else if (vecCheck.primaryFill) {
+        pruned.fills = [vecCheck.primaryFill];
+      }
+      return pruned;
+    }
+  }
+
+  // 3. Collapse Masked Image Groups
+  if (_depth > 0 && analyzeMaskedImageSubtree(node)) {
+    if (bounds) pruned.bounds = bounds;
+    pruned.fills = [{ type: 'IMAGE' }];
+    if (node.cornerRadius) pruned.cornerRadius = node.cornerRadius;
+    return pruned;
+  }
+
   // Layout & Flexbox properties
   if (node.layoutMode && node.layoutMode !== 'NONE') {
     pruned.layoutMode = node.layoutMode;
-    if (node.primaryAxisAlignItems) pruned.primaryAxisAlignItems = node.primaryAxisAlignItems;
-    if (node.counterAxisAlignItems) pruned.counterAxisAlignItems = node.counterAxisAlignItems;
+    if (node.primaryAxisAlignItems && node.primaryAxisAlignItems !== 'MIN') {
+      pruned.primaryAxisAlignItems = node.primaryAxisAlignItems;
+    }
+    if (node.counterAxisAlignItems && node.counterAxisAlignItems !== 'MIN') {
+      pruned.counterAxisAlignItems = node.counterAxisAlignItems;
+    }
 
     if (node.itemSpacing) {
       pruned.itemSpacing = node.itemSpacing;
@@ -484,18 +871,15 @@ function pruneFigmaNode(node, context = {}, options = {}) {
       if (padToken) pruned.paddingToken = padToken;
     }
 
-    if (node.layoutWrap) pruned.layoutWrap = node.layoutWrap;
+    if (node.layoutWrap && node.layoutWrap !== 'NO_WRAP') pruned.layoutWrap = node.layoutWrap;
   }
 
   if (node.layoutGrow) pruned.layoutGrow = node.layoutGrow;
-  if (node.layoutAlign) pruned.layoutAlign = node.layoutAlign;
+  if (node.layoutAlign && node.layoutAlign !== 'INHERIT') pruned.layoutAlign = node.layoutAlign;
 
   // Dimensions & Coordinates
-  if (node.absoluteBoundingBox) {
-    pruned.bounds = {
-      width: Math.round(node.absoluteBoundingBox.width),
-      height: Math.round(node.absoluteBoundingBox.height),
-    };
+  if (bounds) {
+    pruned.bounds = bounds;
   }
 
   if (node.minWidth) pruned.minWidth = node.minWidth;
@@ -514,8 +898,9 @@ function pruneFigmaNode(node, context = {}, options = {}) {
     pruned.cornerRadius = node.cornerRadius;
     const radiusToken = resolveVariableToken(bound.cornerRadius, varMap);
     if (radiusToken) pruned.cornerRadiusToken = radiusToken;
+  } else if (Array.isArray(node.rectangleCornerRadii) && node.rectangleCornerRadii.some((r) => r > 0)) {
+    pruned.cornerRadii = node.rectangleCornerRadii;
   }
-  if (node.rectangleCornerRadii) pruned.cornerRadii = node.rectangleCornerRadii;
   if (node.opacity !== undefined && node.opacity !== 1) pruned.opacity = node.opacity;
 
   // Effects (Drop Shadows, Layer Blurs)
@@ -533,25 +918,32 @@ function pruneFigmaNode(node, context = {}, options = {}) {
 
   // Typography (for TEXT nodes)
   if (node.type === 'TEXT') {
-    pruned.characters = node.characters;
+    pruned.characters = isRawAssetString(node.characters) ? '[raw-asset-omitted]' : node.characters;
     if (node.style) {
-      pruned.typography = {
-        fontFamily: node.style.fontFamily,
-        fontSize: node.style.fontSize,
-        fontWeight: node.style.fontWeight,
-        lineHeightPx: node.style.lineHeightPx ? Math.round(node.style.lineHeightPx) : undefined,
-        letterSpacing: node.style.letterSpacing,
-        textAlignHorizontal: node.style.textAlignHorizontal,
-        textAlignVertical: node.style.textAlignVertical,
-      };
+      const typo = {};
+      if (node.style.fontFamily) typo.fontFamily = node.style.fontFamily;
+      if (node.style.fontSize) typo.fontSize = node.style.fontSize;
+      if (node.style.fontWeight) typo.fontWeight = node.style.fontWeight;
+      if (node.style.lineHeightPx) typo.lineHeightPx = Math.round(node.style.lineHeightPx);
+      if (node.style.letterSpacing) typo.letterSpacing = node.style.letterSpacing;
+      if (node.style.textAlignHorizontal && node.style.textAlignHorizontal !== 'LEFT') {
+        typo.textAlignHorizontal = node.style.textAlignHorizontal;
+      }
+      if (node.style.textAlignVertical && node.style.textAlignVertical !== 'TOP') {
+        typo.textAlignVertical = node.style.textAlignVertical;
+      }
+      if (Object.keys(typo).length > 0) {
+        pruned.typography = typo;
+      }
     }
   }
 
   // Recursively process children
   if (Array.isArray(node.children) && node.children.length > 0) {
-    pruned.children = node.children
-      .filter((c) => c.visible !== false)
-      .map((c) => pruneFigmaNode(c, context, options));
+    const visibleChildren = node.children.filter((c) => c && c.visible !== false);
+    if (visibleChildren.length > 0) {
+      pruned.children = visibleChildren.map((c) => pruneFigmaNode(c, context, options, _depth + 1));
+    }
   }
 
   return pruned;
@@ -566,7 +958,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 +1524,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 +1637,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 +1685,9 @@ function formatApiError(error) {
 
 // Export internal functions for unit testing
 module.exports = {
+  resolveHomeDir,
+  decodeEnvBuffer,
+  getPowerShellProfilePaths,
   loadEnv,
   parseEnvLine,
   getFigmaToken,

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"