Metadata-Version: 2.4
Name: extrafigma
Version: 0.1.0
Summary: Pull Figma files into agent-readable local folders
Project-URL: Homepage, https://github.com/think41/extrafigma
Project-URL: Repository, https://github.com/think41/extrafigma
Project-URL: Issues, https://github.com/think41/extrafigma/issues
License-Expression: MIT
License-File: LICENSE
Keywords: ai,cli,codegen,design,figma
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Software Development :: Code Generators
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27.0
Requires-Dist: rich>=13.0.0
Requires-Dist: typer>=0.12.0
Description-Content-Type: text/markdown

# 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

```bash
pip install extrafigma
# or
uvx extrafigma --help
```

## Quick start

```bash
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:

```json
{
  "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

```bash
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
