# AI Data Extractor — Figma Plugin

A Figma plugin that extracts design structure, layout properties, text content, and visual assets from your selected layers — packaged into a structured ZIP archive optimized for AI and machine learning interpretation.

---

## What It Does

Select any frame or group of layers in Figma, click **Extract**, and the plugin will:

1. **Traverse the full node tree** of your selection, capturing the parent-child hierarchy
2. **Extract metadata** for every node — dimensions, position, fills, strokes, effects, opacity, border radius, and layout properties (auto-layout mode, padding, spacing, alignment)
3. **Capture text content** inline, including font family, size, line height, letter spacing, and alignment
4. **Export visual assets** — PNG for every non-text node, plus SVG for nodes that don't contain text children
5. **Package everything** into a downloadable `.zip` archive with a structured `data.md` file

---

## Output Structure

The generated ZIP follows a predictable, hierarchical folder structure:

```
figma-ai-extraction.zip
├── data.md                          # Full hierarchical tree + properties
└── <TopLevelNode>/                  # One folder per selected root node
    ├── <NodeName>.png
    ├── <NodeName>.svg
    └── children/
        └── <ChildNode>/
            ├── <ChildNode>.png
            ├── <ChildNode>.svg
            └── children/
                └── ...              # Recursively nested
```

### `data.md`

The markdown file contains:

- **AI Interpretation Guide** — instructions for how an AI model should parse the data
- **Hierarchical Tree** — indented list of every node with:
  - Node name, type, and folder path
  - Inline text content (for text nodes)
  - Raw properties JSON (dimensions, position, fills, strokes, effects, layout config, typography)

### Asset Export Rules

| Node Type | PNG | SVG | Reasoning |
|-----------|-----|-----|-----------|
| Text node | ✗ | ✗ | Text content is captured inline in `data.md` |
| Node with text children | ✓ | ✗ | PNG preserves visual context; SVG skipped to avoid exposing raw text paths |
| Node without text | ✓ | ✓ | Both formats exported for maximum flexibility |

---

## How to Use

1. Open a Figma file
2. Run the **AI Data Extractor** plugin
3. Select one or more frames/layers on the canvas
4. Click **Extract Selection**
5. Wait for processing — the plugin traverses nodes, exports assets, and generates the ZIP
6. The archive downloads automatically when complete

---

## Limits

- **500 node maximum** per extraction — the plugin counts all nodes (including deeply nested children) and will show an error if the selection exceeds this limit. This prevents performance issues with very large component trees.

---

## Technical Details

| Detail | Value |
|--------|-------|
| Figma API | `1.0.0` |
| Editor | Figma (design files) |
| UI Size | 320 × 180 px |
| ZIP Library | [JSZip 3.10.1](https://stuk.github.io/jszip/) (loaded via CDN) |
| Network Access | `cdnjs.cloudflare.com` only |

### Architecture

- **`code.ts`** — Plugin backend running in Figma's sandbox. Handles node traversal, property extraction, and asset export via the Figma Plugin API.
- **`ui.html`** — Plugin frontend. Manages UI state (idle → processing → exporting → complete/error), generates the ZIP archive using JSZip, and triggers the browser download.
- **`manifest.json`** — Plugin configuration and permissions.

### Node Position Handling

Positions are calculated **relative to the top-level selected node** (not the canvas). The root node is always positioned at `(0, 0)`, and all children use offsets from the root's `absoluteBoundingBox`. This makes the output self-contained and canvas-position-independent.

---

## States

The plugin UI cycles through these states:

| State | Icon | Description |
|-------|------|-------------|
| **Idle** | 📦 | Waiting for user to click "Extract Selection" |
| **Processing** | 🔄 | Traversing nodes and exporting assets |
| **Exporting** | 🔄 + progress bar | Generating the ZIP archive |
| **Complete** | ✅ | Download finished successfully |
| **Error** | ⚠️ | Something went wrong (with message) |

---

## Development

### Build

Compile TypeScript to JavaScript:

```bash
npx tsc code.ts --outDir . --target ES6
```

### Project Files

```
├── manifest.json    # Plugin manifest
├── code.ts          # Source (TypeScript)
├── code.js          # Compiled output (loaded by Figma)
├── ui.html          # Plugin UI
└── README.md        # This file
```