Figma Integration Guide

December 10, 2025 · View on GitHub

Last reviewed: 2025-02-21
Status: Legacy/archived — Figma integration is not supported in v4.4.x; kept for historical reference only.

This guide explains how to use AX CLI with Figma to automate design-to-code workflows, extract design tokens, and audit design consistency.

Interactive Mode
Quick Start
Authentication
Commands
Workflows
Configuration
Troubleshooting

Interactive Mode

The easiest way to use Figma integration is through interactive mode with natural language:

# Start interactive mode
ax-cli

# Then simply describe what you want:
> Map my Figma file ABC123xyz
> Extract design tokens from my Figma file as Tailwind config
> Audit my design for accessibility and naming issues
> Search for all button components in my design
> List my design aliases

Example Conversations

Mapping a file:

You: Show me the structure of my Figma file ABC123xyz
AX: Fetching Figma file... Here's the structure:

Page: Landing Page
├── Frame: Hero Section (123:456)
│   ├── Text: Headline
│   └── Frame: CTA Button
└── Frame: Features (123:789)

Extracting tokens:

You: Get the design tokens from my Figma file and format them for Tailwind
AX: Extracting tokens... Here's your Tailwind config:

module.exports = {
  theme: {
    extend: {
      colors: { primary: '#0066FF' },
      spacing: { sm: '8px', md: '16px' }
    }
  }
}

Running an audit:

You: Check my design for accessibility issues
AX: Running audit... Found 2 issues:

  WARNING: Color contrast ratio 4.2:1 below WCAG AA (4.5:1)
  INFO: Frame "Card" uses fixed positioning, consider auto-layout

Quick Start

# 1. Authenticate with Figma
ax-cli design auth login

# 2. Map your Figma file to see its structure
ax-cli design map YOUR_FILE_KEY

# 3. Create an alias for quick access
ax-cli design alias add hero 123:456

# 4. Extract design tokens
ax-cli design tokens pull YOUR_FILE_KEY --format tailwind --output tailwind.config.js

# 5. Audit your design for consistency
ax-cli design audit hero --rules all

Authentication

Get Your Figma Access Token

Go to Figma Account Settings
Scroll to Personal Access Tokens
Click Generate new token
Copy the token (you won't see it again!)

# Interactive login (recommended)
ax-cli design auth login

# Set token directly
ax-cli design auth token YOUR_PERSONAL_ACCESS_TOKEN

# Check auth status
ax-cli design auth status

Environment Variable

For CI/CD, set the FIGMA_ACCESS_TOKEN environment variable:

export FIGMA_ACCESS_TOKEN=your_token_here
ax-cli design tokens pull FILE_KEY --format json

Commands

design map

Display the structure of a Figma file as a navigable tree.

# Basic usage
ax-cli design map YOUR_FILE_KEY

# Limit depth (default: 3)
ax-cli design map YOUR_FILE_KEY --depth 5

# Start from a specific node (using alias)
ax-cli design map YOUR_FILE_KEY --subtree landing.hero

# Output as JSON (for scripting)
ax-cli design map YOUR_FILE_KEY --json

Getting Your File Key:

The file key is in your Figma URL:

https://www.figma.com/file/ABC123xyz/My-Design
                           ^^^^^^^^^
                           This is your file key

Example Output:

Page: Landing Page
├── Frame: Hero Section (123:456)
│   ├── Text: Headline
│   ├── Text: Subheadline
│   └── Frame: CTA Button
├── Frame: Features (123:789)
│   ├── Component: Feature Card
│   └── Component: Feature Card
└── Frame: Footer (123:012)

design alias

Create shortcuts to frequently used Figma nodes.

# Add an alias
ax-cli design alias add hero 123:456
ax-cli design alias add ds.colors 789:012 --file ds-file-key

# List all aliases
ax-cli design alias list

# Remove an alias
ax-cli design alias remove hero

Why Use Aliases?

Stability: Node IDs don't change when you rename layers
Readability: hero is easier to remember than 123:456
Team sharing: Aliases stored in .ax-cli/design.json can be committed

Aliases File:

{
  "version": 1,
  "defaultFile": "ABC123xyz",
  "aliases": {
    "landing.hero": { "fileKey": "ABC123xyz", "nodeId": "123:456" },
    "landing.features": { "fileKey": "ABC123xyz", "nodeId": "123:789" },
    "ds.colors": { "fileKey": "DS456def", "nodeId": "789:012" }
  },
  "dsFile": "DS456def"
}

design tokens

Extract design tokens from Figma and convert to code-ready formats.

# Pull tokens as JSON
ax-cli design tokens pull FILE_KEY --format json --output tokens.json

# Pull tokens as Tailwind config
ax-cli design tokens pull FILE_KEY --format tailwind --output tailwind.config.js

# Compare local tokens with Figma
ax-cli design tokens compare FILE_KEY ./tokens.json

Supported Token Types:

Type	Figma Source	Output
Colors	Fill colors, Effects	HEX, RGB, HSL
Typography	Text styles	Font family, size, weight, line-height
Spacing	Auto-layout gaps, padding	px, rem
Border radius	Corner radius	px
Shadows	Drop shadows, Inner shadows	CSS box-shadow

JSON Output Example:

{
  "colors": {
    "primary": { "value": "#0066FF", "type": "color" },
    "secondary": { "value": "#FF6600", "type": "color" }
  },
  "spacing": {
    "xs": { "value": "4px", "type": "dimension" },
    "sm": { "value": "8px", "type": "dimension" },
    "md": { "value": "16px", "type": "dimension" }
  },
  "typography": {
    "heading-1": {
      "fontFamily": "Inter",
      "fontSize": "48px",
      "fontWeight": 700,
      "lineHeight": "56px"
    }
  }
}

Tailwind Output Example:

module.exports = {
  theme: {
    extend: {
      colors: {
        primary: '#0066FF',
        secondary: '#FF6600'
      },
      spacing: {
        xs: '4px',
        sm: '8px',
        md: '16px'
      },
      fontSize: {
        'heading-1': ['48px', { lineHeight: '56px', fontWeight: '700' }]
      }
    }
  }
}

design audit

Run design consistency checks against your Figma file.

# Audit a specific node
ax-cli design audit landing.hero

# Audit with specific rules
ax-cli design audit landing.hero --rules spacing-consistency,color-contrast

# Output as JSON (for CI/CD)
ax-cli design audit landing.hero --json

Available Rules:

Rule	Description	Severity
`spacing-consistency`	Spacing values match design system tokens	warning
`color-contrast`	WCAG AA/AAA compliance for text	error
`naming-convention`	Component/layer names follow pattern	info
`token-usage`	Colors and text styles match defined tokens	warning
`missing-autolayout`	Frames without auto-layout	info

Example Output:

Design Audit Report: landing.hero

  ERRORS (1)
  color-contrast: Text "Subscribe" (#666666 on #FFFFFF) fails WCAG AA
                  Contrast ratio: 4.2:1 (minimum: 4.5:1)
                  Node: 123:789

  WARNINGS (2)
  spacing-consistency: Padding 17px doesn't match token (expected 16px)
                       Node: 123:456
  token-usage: Color #0065FF not in design system (closest: #0066FF)
               Node: 123:012

  INFO (1)
  missing-autolayout: Frame "Card" uses fixed positioning
                      Consider auto-layout for responsive design
                      Node: 123:345

Summary: 1 error, 2 warnings, 1 info

Workflows

Design Token Sync Workflow

Keep your codebase in sync with Figma design tokens:

# 1. Pull latest tokens from Figma
ax-cli design tokens pull FILE_KEY --format tailwind --output src/styles/tokens.js

# 2. Compare with existing tokens
ax-cli design tokens compare FILE_KEY src/styles/tokens.js

# 3. Run audit to check consistency
ax-cli design audit ds.colors --rules token-usage --json > audit-report.json

CI/CD Integration

Add to your CI pipeline to catch design drift:

# .github/workflows/design-audit.yml
name: Design Audit
on: [pull_request]

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '24'
      - run: npm install -g @defai.digital/ax-cli
      - run: ax-cli design audit landing.hero --json > audit.json
        env:
          FIGMA_ACCESS_TOKEN: ${{ secrets.FIGMA_ACCESS_TOKEN }}
      - name: Check for errors
        run: |
          if jq -e '.errors | length > 0' audit.json; then
            echo "Design audit failed!"
            exit 1
          fi

Component Documentation

Generate component documentation from Figma:

# Map your design system file
ax-cli design map DS_FILE_KEY --depth 4 --json > components.json

# Use with your documentation tool
ax-cli -p "Generate component documentation from this Figma structure" < components.json

Configuration

Project Configuration

Store Figma settings in .ax-cli/design.json:

{
  "version": 1,
  "defaultFile": "YOUR_DEFAULT_FILE_KEY",
  "dsFile": "YOUR_DESIGN_SYSTEM_FILE_KEY",
  "aliases": {},
  "audit": {
    "rules": ["spacing-consistency", "color-contrast", "token-usage"],
    "ignorePatterns": ["**/deprecated/**"]
  },
  "tokens": {
    "format": "tailwind",
    "output": "src/styles/design-tokens.js"
  }
}

Rate Limiting

Figma Professional plan allows 60 requests/minute. AX CLI automatically:

Caches responses to minimize API calls
Implements exponential backoff on rate limit errors
Shows progress for long operations

Troubleshooting

Common Errors

"Invalid token" or "403 Forbidden"

# Re-authenticate
ax-cli design auth login

# Verify token has correct permissions
ax-cli design auth status

"File not found"

Check your file key is correct (from the Figma URL)
Ensure you have access to the file in Figma

"Rate limit exceeded"

Wait 60 seconds and retry
Use --json output and cache results locally
Consider upgrading to Figma Organization plan for higher limits

"Node not found"

Node IDs can change when duplicating frames
Use aliases for stable references
Re-run design map to find new node IDs

Debug Mode

# Enable verbose logging
ax-cli --debug design map FILE_KEY

Best Practices

Use aliases for important nodes - They're stable and readable
Commit .ax-cli/design.json - Share aliases with your team
Set up CI audits - Catch design drift before it ships
Extract tokens regularly - Keep code and design in sync
Use JSON output for automation - All commands support --json

MCP Integration - Extend with Model Context Protocol
CLI Reference - Complete command reference
Configuration - All configuration options
ADR-004: Figma Integration - Architecture decisions