@aionixos/designspec

Extract Figma design specs via REST API. Generate AI-ready output, export optimized assets (webp), sync design tokens to GitHub. Built for AI-driven development.

Quick Start

# Install
pnpm add -g @aionixos/designspec

# Update to latest version
pnpm add -g @aionixos/designspec@latest

# Authenticate (one-time)
designspec auth

# Initialize project config (auto-detects framework)
designspec init

# Install the interpreter skill to your AI coding tools
designspec skills install

# Export a complete bundle to your project
designspec bundle "https://figma.com/design/ABC123/Page?node-id=10-234" --name login-screen
# -> .aionixos/specs/login-screen/
#    ├── spec.json           (AI-ready, minified)
#    ├── [email protected]  (optimized)
#    ├── icons/*.svg
#    ├── images/*@2x.webp
#    └── AI-INSTRUCTIONS.md

Authentication

Figma Token (required)

Generate a Personal Access Token at Figma Settings. Required scopes:

• current_user:read — validate token
• file_content:read — read design nodes, layout, styles
• library_assets:read — read components and shared styles
• file_variables:read — read variables/tokens (needed for variables and sync commands). Note: This scope is only available on Figma Enterprise/Organization plans. On free/Pro plans, use the Figma plugin to export variables instead.

# Interactive setup
designspec auth

# Non-interactive
designspec auth --token figd_xxxxxxxxxxxxxxxx

# Check status
designspec auth --status

GitHub Token (optional — only for sync command)

Only needed if you want to sync design tokens to a GitHub repo with automatic PRs.

1. Go to https://github.com/settings/tokens?type=beta
2. Generate a fine-grained token with access to the target repo
3. Permissions: Contents -> Read and Write, Pull requests -> Read and Write

designspec auth --github-token ghp_xxxxxxxxxxxxxxxx

Token Storage

Tokens are stored in ~/.aionixos/config.json with file permissions 600 (owner-only read/write). Environment variables FIGMA_TOKEN and GITHUB_TOKEN override stored tokens.

Project Config

Run designspec init to generate a .designspecrc in your project root. It auto-detects the CSS framework from your project files.

{
  "framework": "tailwind",
  "imageFormat": "webp",
  "quality": 80,
  "scale": 2,
  "format": "ai-ready",
  "depth": 10,
  "slim": true
}

All commands read this config automatically. CLI flags always override config values.

Auto-detection:

• tailwind.config.* or tailwindcss in package.json -> "framework": "tailwind"
• bootstrap in package.json -> "framework": "bootstrap"

Commands

init — Initialize Project Config

designspec init

Generates .designspecrc with auto-detected defaults and installs the CLI reference skill to .claude/skills/designspec/. Run once per project.

skills — Manage AI Tool Skills

Install the bundled aionixos-interpreter skill to your AI coding tools. The interpreter analyzes exported specs against your project's design system — resolving colors to tokens, detecting reusable components, identifying existing images, and producing structured briefs.

# See which tools are detected and their installation status
designspec skills list

# Install to all detected tools
designspec skills install

# Install to specific tools only
designspec skills install --target claude,cursor

# Force reinstall (even if up to date)
designspec skills install --force

# Update outdated installations
designspec skills update

# Remove from all tools
designspec skills remove

# Remove from specific tools
designspec skills remove --target windsurf

Supported tools:

| Tool | Format | Install Location | |------|--------|-----------------| | Claude Code | Multi-file skill | ~/.claude/skills/aionixos-interpreter/ | | Windsurf | Multi-file skill | ~/.codeium/windsurf/skills/aionixos-interpreter/ | | Gemini | Multi-file skill | ~/.gemini/skills/aionixos-interpreter/ | | Cursor | Single .mdc rule | ~/.cursor/rules/aionixos-interpreter.mdc |

The interpreter is versioned independently. When you update the CLI, run designspec skills update to refresh installed skills.

bundle — Export Complete Design Bundle (Recommended)

Exports spec + screenshot + icons + images + AI instructions to .aionixos/specs/ in your project. This is the primary command for AI-driven development.

# Basic usage — always provide a name
designspec bundle "<figma-url>" --name past-trips

# With options
designspec bundle "<url>" --name dashboard --framework bootstrap --scale 3
designspec bundle "<url>" --name hero-section --image-format png
designspec bundle "<url>" --name modal --quality 90

# Custom output directory
designspec bundle "<url>" --name login -o ./design-specs/login

Output structure:

.aionixos/specs/past-trips/
├── my-park-planner-spec.json   # AI-ready spec (minified JSON)
├── [email protected]    # Screenshot (sharp-optimized webp, ~75% smaller than PNG)
├── icons/
│   └── button-icon.svg         # Extracted SVG icons
├── images/
│   ├── [email protected]          # Raster images (optimized webp)
│   └── [email protected]
└── AI-INSTRUCTIONS.md          # Guide for AI/developers

Options:

| Flag | Default | Description | |------|---------|-------------| | -n, --name | Frame name | Folder name for the spec | | -f, --format | ai-ready | json, ai-ready, markdown | | --framework | tailwind | tailwind, bootstrap, css, css-variables | | --image-format | webp | webp, png, jpg | | --quality | 80 | Image quality 1-100 (webp/jpg) | | --scale | 2 | Export scale: 1, 2, 3 | | --depth | 10 | Max recursion depth | | -o, --output | .aionixos/specs/<name> | Custom output directory |

spec — Extract Design Specification

# JSON output (default)
designspec spec "https://figma.com/design/ABC123/Page?node-id=10-234"

# AI-ready format (best for code generation)
designspec spec "https://figma.com/design/ABC123/Page?node-id=10-234" \
  --format ai-ready --framework tailwind

# Markdown prompt (human-readable)
designspec spec "<url>" --format markdown

# Save to file
designspec spec "<url>" --format ai-ready -o spec.json

# Compact JSON
designspec spec "<url>" --compact

Options:

| Flag | Default | Description | |------|---------|-------------| | -f, --format | json | json, ai-ready, markdown, simplified, tailwind | | --framework | tailwind | tailwind, bootstrap, css, css-variables | | --depth <n> | 10 | Max recursion depth | | --slim | true | Omit coordinates, zero-padding | | --no-children | — | Flat spec, no recursion | | --include-hidden | — | Include hidden layers | | -o, --output | stdout | Write to file | | --compact | — | Minified JSON | | --extract-icons | — | Include SVG icon data |

assets — Export Images and SVGs

# Export SVGs
designspec assets "<url>" --format svg --output-dir ./src/assets

# Export PNGs at 2x
designspec assets "<url>" --format png --scale 2 --output-dir ./public/images

# Export JPGs
designspec assets "<url>" --format jpg --scale 1

variables — Extract Design Tokens

# Raw Figma variables JSON
designspec variables "<url>"

# W3C Design Tokens format
designspec variables "<url>" --format w3c

# Tokens Studio format
designspec variables "<url>" --format tokens-studio

# Save to file
designspec variables "<url>" --format w3c -o tokens.json

sync — Sync Tokens to GitHub

Push design tokens from Figma to a GitHub repository, automatically creating a PR.

# Create a PR with updated tokens
designspec sync "<url>" --repo owner/repo --path tokens/theme.json --pr

# Push directly to main
designspec sync "<url>" --repo owner/repo --path tokens/theme.json --push

# Custom commit message
designspec sync "<url>" --repo owner/repo --pr --message "update: brand colors v2"

# Tokens Studio format
designspec sync "<url>" --repo owner/repo --format tokens-studio --pr

Workflow:

1. Designer changes a token value in Figma Variables
2. Runs designspec sync <url> --repo owner/repo --pr
3. CLI extracts tokens, creates branch, commits JSON, opens PR
4. GitHub Actions picks it up (e.g., Style Dictionary generates CSS)
5. PR is reviewed and merged

Requires: GitHub Personal Access Token with repo scope.

auth — Token Management

designspec auth                            # Interactive setup
designspec auth --token figd_xxx           # Set Figma token
designspec auth --github-token ghp_xxx     # Set GitHub token
designspec auth --status                   # Check tokens
designspec auth --clear                    # Remove all tokens

Output Formats

json (default)

Full DesignSpec with all metadata: nodes, dimensions, fills, strokes, effects, typography, layout, frameworks output.

ai-ready

Structured for AI code generation. Includes:

• Semantic roles (button, card, nav, input, etc.)
• Layout specs (flex direction, gap, alignment)
• Sizing behavior (fixed, fill, hug)
• Framework-specific classes per element
• Reusable component detection
• Color palette and typography styles

markdown

Human-readable prompt with categorized styles (layout, size, spacing, colors, typography, border).

simplified

Lightweight JSON with only: name, Tailwind classes, text content, semantic role, size.

tailwind

Map of element names to Tailwind class strings.

Figma URL Format

https://www.figma.com/design/FILE_KEY/File-Name?node-id=NODE_ID

• With node-id: Extracts only that specific frame/component (fast)
• Without node-id: Processes the entire first page (slower for large files)

Update Notifications

The CLI automatically checks for newer versions once every 24 hours (non-blocking, silent on failure). When updates are available, a banner is shown after command execution:

  Update available: 0.3.0 -> 0.4.0
  Run: npm i -g @aionixos/designspec

If installed interpreter skills are outdated compared to the bundled version:

  Skill update available:
    Windsurf: 3.1.0 -> 3.2.0
  Run: designspec skills update

Claude Code Integration

This CLI includes a Claude Code Skill at .claude/skills/designspec/SKILL.md. When Claude Code is used in a project with this tool installed, it can automatically extract Figma specs and generate code from Figma URLs.

For enhanced spec interpretation (color resolution, component detection, image reuse), install the interpreter skill:

designspec skills install

Security

• Tokens stored at ~/.aionixos/config.json with chmod 600 (owner read/write only)
• Config directory created with chmod 700
• Environment variables (FIGMA_TOKEN, GITHUB_TOKEN) take precedence over stored tokens
• No tokens are ever sent to third-party servers (only to Figma API and GitHub API)
• Update check contacts only registry.npmjs.org (standard npm registry)

Development

pnpm install
pnpm run build         # Build with esbuild
pnpm run typecheck     # Type check with tsc
pnpm run lint          # Lint with Biome
pnpm run lint:fix      # Auto-fix lint issues
pnpm run test          # Run tests with Vitest
pnpm run test:watch    # Watch mode
pnpm run test:coverage # Coverage report
pnpm run dev           # Watch mode (build)

License

MIT