figma-agent

A production-oriented MVP that converts Figma frame exports into a visual-only semantic DSL and concise prompts for AI coding agents.

Product Boundary

This tool is intentionally not a Figma-to-code generator.

• Deterministic TypeScript parses Figma JSON into visual structure
• AI is used only for generating prompt text
• Prompts describe visual/layout properties only
• Business logic, events, and behavior are intentionally excluded

Implemented MVP

• Figma plugin exports minimal JSON from selected frame
• CLI commands:
  • init
  • sync
  • analyze
  • generate <component>
• Visual DSL component types:
  • button
  • text
  • container
  • card
  • hero
  • header
  • footer
• Prompt caching to avoid unnecessary regeneration

Requirements

• Node.js 20+

Install

npm install

Commands

init

Creates AI workspace folders and sample JSON files.

npm run dev -- init

sync

Pulls latest design JSON from a GitHub raw URL or local file and stores it in:

• ai/figma/layout.json (versioned snapshot)
• ai/raw/figma.json (analyze input)

npm run dev -- sync --source https://raw.githubusercontent.com/<owner>/<repo>/<branch>/ai/figma/layout.json

Local file source example:

npm run dev -- sync --source ai/figma/layout.json

For private GitHub sources, pass token:

npm run dev -- sync --source <url> --token <github-token>

You can also set FIGMA_SYNC_SOURCE and GITHUB_TOKEN.

analyze

Converts ai/raw/figma.json into visual semantic outputs:

• ai/semantic/layout.json
• ai/semantic/components/*.json

npm run dev -- analyze

generate <component>

Creates a visual-only prompt markdown file for one semantic component.

npm run dev -- generate hero-cta-button-1

Output:

• ai/prompts/<component>.prompt.md

Cache file:

• ai/prompts/.cache.json

File Structure

ai/
  figma/
    layout.json
  raw/
    figma.json
  semantic/
    layout.json
    components/
      hero-1.json
      button-1.json
  prompts/
    hero.prompt.md
    .cache.json

Visual DSL Shape

Each semantic component is visual-only:

• type
• text (if present)
• width, height
• position: { x, y }
• layout
• color: { background, text, border }
• spacing: { top, right, bottom, left }
• variant
• children

Typical Workflow

1. In Figma, select a frame and run plugin export.
2. Save/export JSON and commit it under ai/figma/layout.json.
3. Run npx figma-agent sync.
4. Run npx figma-agent analyze.
5. Run npx figma-agent generate <component>.
6. Use generated prompt with coding agent; then add business logic manually.

Future (Not Implemented)

• Full page prompt generation
• Multi-framework support
• Real-time Figma sync
• Automated advanced classification beyond visual heuristics