extrafigma 0.1.0

Pull Figma files into agent-readable local folders

ExtraFigma

A pull-only CLI that converts Figma files into agent-readable local folders. Drop the output into your project and let Claude Code (or any AI coding agent) implement pixel-perfect frontend code from the design.

Install

pip install extrafigma
# or
uvx extrafigma --help

Quick start

extrafigma pull "https://www.figma.com/design/abc123/My-App" ./my-design

On first run you'll be prompted for a Figma Personal Access Token. Get one at Figma → Settings → Security → Personal Access Tokens (scopes needed: file_content:read, file_metadata:read).

The token is stored at ~/.config/extrafigma/credentials.json and reused for all future pulls.

What gets extracted

my-design/
  CLAUDE.md               ← instructions for AI agents
  index.md                ← overview of all pages and frames
  tokens/
    colors.json           ← named color styles → hex values
    typography.json       ← named text styles → font properties
  assets/
    icon-name.svg         ← exported SVG icons (VECTOR nodes)
  pages/
    Page-1/
      page.md
      Hero.frame.json     ← distilled layout tree (CSS-friendly)
      Hero.png            ← 2× frame render (visual ground truth)

frame.json structure

Every frame is distilled to a CSS-friendly layout tree:

{
  "type": "FRAME",
  "name": "Hero",
  "width": 1440,
  "height": 900,
  "layout": { "mode": "flex", "direction": "column", "gap": 24 },
  "background": "colors/brand-primary",
  "borderRadius": 0,
  "children": [
    {
      "type": "TEXT",
      "content": "Welcome",
      "style": "typography/heading-xl",
      "color": "colors/gray-800"
    }
  ]
}

Named Figma Styles become tokens (colors/brand-primary, typography/heading-xl). Raw hex values that weren't saved as styles are flagged with # not in tokens.

Auth commands

extrafigma auth login               # interactive prompt
extrafigma auth login --pat <token> # non-interactive (CI-friendly)
extrafigma auth status              # check stored PAT
extrafigma auth logout              # remove stored PAT

Rate limits

Figma's REST API limits GET /v1/files calls based on your seat type:

Seat	Limit
View / Collab	6 per month
Dev / Full (Starter)	10 per minute
Dev / Full (Professional)	15 per minute

Use an account with an editor seat on the file for meaningful usage.

Known limitations

• Design tokens require named Figma Styles. If the designer applied colors directly without saving them as named styles, tokens will be empty. Variables (Figma Professional+) are not supported — use Styles instead.
• SVG export skips remote library components. Icons that are instances of components from external shared libraries cannot be exported via the REST API. They'll appear as INSTANCE nodes in the frame JSON.
• x/y positions are canvas-space coordinates. For absolute-layout frames, subtract the parent's x/y to get relative positions.

How it works

1. GET /v1/files/:key — fetches the full document tree
2. Batch-fetches style node data to resolve exact color/font values
3. Distills each top-level frame to a CSS-friendly JSON tree
4. Exports frame PNGs at 2× resolution
5. Exports VECTOR nodes as SVGs in a second pass

License

MIT