figma-local-analyzer

name	figma-local-analyzer
description	Analyze a local Figma file on disk. Use when user has a .fig file, a Figma-exported JSON, or wants to inspect components, tokens, layers, frames, or design system structure from a locally saved Figma design file. Fully offline — no API key needed.
risk	safe
source	custom
date_added	2026-07-10

Cross-platform: PowerShell scripts (.ps1) for Windows — Bash scripts (.sh) for macOS/Linux. Both live in scripts/ and are feature-identical. The agent MUST detect the OS and run the correct variant.

Figma Local File Analyzer

Analyze Figma design files entirely offline from the local filesystem. The agent handles all tooling setup, conversion, and analysis — the user only needs to provide the file path.

CRITICAL: The .fig Binary Problem

.fig files are proprietary Kiwi-encoded binary — they CANNOT be read as text or JSON directly. You MUST convert them first using fig2json. If the user provides a .json file already, skip straight to Step 3.

---

Step 1 — Identify the Input

Ask the user for the file path. Then determine file type:

# Check file extension
$file = "C:\path\to\design.fig"  # or design.json
$ext = [System.IO.Path]::GetExtension($file)

if ($ext -eq ".fig") {
    # Must convert — go to Step 2
} elseif ($ext -eq ".json") {
    # Already readable — skip to Step 3
} else {
    # Ask user to clarify
}

---

Step 2 — Install Required Tools

The skill needs two tools: fig2json (converts .fig binary) and jq (parses JSON in scripts). Run the appropriate block for the user's OS — detect with $PSVersionTable (PowerShell) or uname (bash).

Windows (PowerShell)

# 1. Check Node.js
node --version
# If missing: winget install OpenJS.NodeJS.LTS  (then restart shell)

# 2. Check jq
jq --version
# If missing:
winget install jqlang.jq
# Or via Chocolatey: choco install jq
# Or via Scoop:      scoop install jq

# 3. fig2json is run via npx — no install needed
npx --yes fig2json --version

macOS (bash)

# 1. Check Node.js
node --version
# If missing: brew install node

# 2. Check jq
jq --version
# If missing: brew install jq

# 3. fig2json via npx — no install needed
npx --yes fig2json --version

Linux (bash)

# 1. Node.js
node --version
# If missing: curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo bash - && sudo apt-get install -y nodejs

# 2. jq
jq --version
# If missing: sudo apt-get install jq   (Debian/Ubuntu)
#             sudo yum install jq        (RHEL/CentOS)

# 3. fig2json via npx
npx --yes fig2json --version

Step 2b — Convert .fig to JSON

Windows (PowerShell)

$inputFig  = "C:\path\to\design.fig"
$outputJson = "C:\path\to\design.json"

npx --yes fig2json "$inputFig" "$outputJson"

if ($LASTEXITCODE -eq 0) {
    Write-Host "Conversion successful: $outputJson"
} else {
    Write-Error "Conversion failed. Only Figma Design files are supported (not FigJam/Slides)."
}

macOS / Linux (bash)

input_fig="/path/to/design.fig"
output_json="/path/to/design.json"

npx --yes fig2json "$input_fig" "$output_json" && \
  echo "Conversion successful: $output_json" || \
  echo "ERROR: Conversion failed. Only Figma Design files are supported (not FigJam/Slides)."

Pitfalls:

• FigJam (.figjam) and Slides files will fail — only standard Design files work
• The fig2json output is intentionally simplified (metadata stripped for LLM use)
• Large files may take 10–30 seconds to convert
• If npx hangs: npm install -g fig2json then fig2json input.fig output.json

---

Step 3 — Load and Inspect the JSON

3a. Verify the JSON and get file size

$jsonPath = "C:\path\to\design.json"
$size = (Get-Item $jsonPath).Length / 1MB
Write-Host "File size: $([math]::Round($size, 2)) MB"

# Quick structure check
$raw = Get-Content $jsonPath -Raw
$data = $raw | ConvertFrom-Json
Write-Host "Document name: $($data.document.name)"
Write-Host "Pages: $($data.document.children.Count)"

3b. For large files (>10MB) — use targeted grep instead of loading whole file

# Search for component names without loading full JSON
Select-String -Path $jsonPath -Pattern '"type"\s*:\s*"COMPONENT"' | Measure-Object | Select-Object Count
Select-String -Path $jsonPath -Pattern '"name"\s*:\s*"[^"]*"' -AllMatches | Select-Object -First 50

---

Step 4 — Analysis Workflows

All scripts live in skills/figma-local-analyzer/scripts/. Run the .ps1 version on Windows and the .sh version on macOS/Linux. Make bash scripts executable once: chmod +x scripts/*.sh

Workflow A: Quick File Summary

Windows:

& "$SKILL_DIR\scripts\fig-walker.ps1" -JsonPath "C:\path\to\design.json" -Mode summary

macOS/Linux:

"$SKILL_DIR/scripts/fig-walker.sh" -f /path/to/design.json -m summary

Produces: page names, frame counts, node type breakdown, library totals.

Workflow B: Full Component Inventory

Windows:

& "$SKILL_DIR\scripts\fig-walker.ps1" -JsonPath "C:\path\to\design.json" -Mode components

macOS/Linux:

"$SKILL_DIR/scripts/fig-walker.sh" -f /path/to/design.json -m components

Produces: table of all components/sets — name, type, variant count, has description.

Workflow C: Design Token Extraction

Windows:

# W3C format (default)
& "$SKILL_DIR\scripts\extract-tokens.ps1" -JsonPath "C:\path\to\design.json" -OutputPath "tokens.json" -Format w3c
# CSS custom properties
& "$SKILL_DIR\scripts\extract-tokens.ps1" -JsonPath "C:\path\to\design.json" -OutputPath "tokens.css" -Format css

macOS/Linux:

# W3C format (default)
"$SKILL_DIR/scripts/extract-tokens.sh" -f /path/to/design.json -o tokens.json -t w3c
# CSS custom properties
"$SKILL_DIR/scripts/extract-tokens.sh" -f /path/to/design.json -o tokens.css -t css

Extracts: color styles, text styles, effect/shadow styles, variables (Enterprise).

Workflow D: Layer / Node Deep Dive

Windows:

& "$SKILL_DIR\scripts\fig-walker.ps1" -JsonPath "C:\path\to\design.json" -Mode node -NodeName "Button/Primary"

macOS/Linux:

"$SKILL_DIR/scripts/fig-walker.sh" -f /path/to/design.json -m node -n "Button/Primary"

Produces: child tree, fills, auto-layout settings, component properties, bound variables.

Workflow E: Design System Health Check

Windows:

& "$SKILL_DIR\scripts\fig-walker.ps1" -JsonPath "C:\path\to\design.json" -Mode health

macOS/Linux:

"$SKILL_DIR/scripts/fig-walker.sh" -f /path/to/design.json -m health

Checks: unstyled text, hard-coded colors, missing descriptions, naming consistency, hidden frames.

Workflow F: Component-to-TypeScript Props

Windows:

& "$SKILL_DIR\scripts\fig-walker.ps1" -JsonPath "C:\path\to\design.json" -Mode props -NodeName "Button/Primary"

macOS/Linux:

"$SKILL_DIR/scripts/fig-walker.sh" -f /path/to/design.json -m props -n "Button/Primary"

Outputs a TypeScript interface from componentPropertyDefinitions.

---

Step 5 — Manual JSON Navigation (When Needed)

When the scripts aren't enough, navigate the JSON directly using PowerShell:

$data = Get-Content "design.json" | ConvertFrom-Json

# List all pages
$data.document.children | Select-Object name, id, type

# Get all top-level frames on page 1
$page1 = $data.document.children[0]
$page1.children | Select-Object name, id, type

# Find a component by name (recursive)
function Find-Node {
    param($node, $name)
    if ($node.name -like "*$name*") { return $node }
    foreach ($child in $node.children) {
        $result = Find-Node $child $name
        if ($result) { return $result }
    }
}
$btn = Find-Node $data.document "Button"
$btn | ConvertTo-Json -Depth 3

# List all components from the flat map
$data.components.PSObject.Properties | Select-Object Name, @{N='ComponentName';E={$_.Value.name}}

# Get all color styles
$data.styles.PSObject.Properties | Where-Object { $_.Value.styleType -eq 'FILL' } | 
    Select-Object @{N='id';E={$_.Name}}, @{N='name';E={$_.Value.name}}

---

JSON Schema Quick Reference

Root:
  document          → Root DOCUMENT node
  components        → { [nodeId]: { name, description, key } }
  componentSets     → { [nodeId]: { name, description, key } }
  styles            → { [styleId]: { name, styleType: FILL|TEXT|EFFECT|GRID } }
  schemaVersion     → int
  version           → string (Figma file version)

Node structure (all nodes):
  id                → string "1:234"
  name              → string
  type              → DOCUMENT | CANVAS | FRAME | GROUP | COMPONENT | COMPONENT_SET |
                      INSTANCE | TEXT | VECTOR | RECTANGLE | ELLIPSE | LINE | STAR |
                      REGULAR_POLYGON | BOOLEAN_OPERATION | SECTION
  children          → Node[]  (not present on leaf nodes)
  visible           → bool
  locked            → bool

Layout (FRAME, COMPONENT, GROUP):
  absoluteBoundingBox → { x, y, width, height }
  constraints         → { horizontal, vertical }
  layoutMode          → NONE | HORIZONTAL | VERTICAL  (auto-layout)
  primaryAxisSizingMode, counterAxisSizingMode
  paddingLeft/Right/Top/Bottom
  itemSpacing

Visual:
  fills             → Paint[]  { type: SOLID|IMAGE|GRADIENT_*, color: {r,g,b,a} }
  strokes           → Paint[]
  strokeWeight      → number
  effects           → Effect[] { type: DROP_SHADOW|INNER_SHADOW|LAYER_BLUR|BACKGROUND_BLUR }
  opacity           → number 0-1
  cornerRadius      → number

Text nodes (type=TEXT):
  characters        → string  (actual text content)
  style             → { fontFamily, fontSize, fontWeight, lineHeightPx, textAlignHorizontal }
  styleOverrideTable

Component nodes (type=COMPONENT):
  componentPropertyDefinitions → {
    [propName]: {
      type: TEXT | BOOLEAN | INSTANCE_SWAP | VARIANT,
      defaultValue: any,
      variantOptions: string[]  (for VARIANT type only)
    }
  }
  description       → string

Instance nodes (type=INSTANCE):
  componentId       → string  (ID of the main COMPONENT)
  componentProperties → { [propName]: { value, type } }

Variables (Enterprise exports):
  variables         → { [varId]: { name, resolvedType, valuesByMode } }
  variableCollections → { [collId]: { name, modes, defaultModeId } }

---

Output Formats

After analysis, create an artifact with one of these formats based on user need:

Component Inventory Table:

| Component Name | ID | Page | Variants | Has Description |
|---|---|---|---|---|
| Button/Primary | 1:234 | Components | 3 (size, state, icon) | Yes |

Design Tokens JSON (W3C format):

{
  "color": {
    "primary": { "$value": "#3B82F6", "$type": "color" }
  },
  "typography": {
    "heading-1": { "$value": { "fontFamily": "Inter", "fontSize": "32px" }, "$type": "typography" }
  }
}

TypeScript Props Interface:

interface ButtonProps {
  size: 'sm' | 'md' | 'lg';
  state: 'default' | 'hover' | 'disabled';
  hasIcon: boolean;
  label: string;
}

---

When to Use

Trigger this skill when the user:

• Has a .fig file and wants to understand its design structure
• Has an exported Figma JSON and wants component/token analysis
• Asks to "analyze", "inspect", "inventory", "extract tokens from", or "audit" a local Figma file
• Wants to map Figma components to code props

Limitations

• Only works with standard Figma Design files — FigJam and Slides are NOT supported
• Variables API data (design tokens as variables) is only present in exports from Enterprise Figma plans
• The .fig binary format may change with Figma updates, potentially breaking fig2json
• Very large files (>50MB JSON) may require targeted queries rather than full-file analysis