# 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
6. **Copy the Developer System Prompt** to your clipboard automatically. This prompt instructs code-generation AI agents on how to strictly implement the extracted design with zero guesswork.

---

## 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 |

### Developer System Prompt

To make it seamless to hand off the extracted data to frontend AI agents (e.g., code-generation models), the plugin automatically copies a specialized **Developer System Prompt** to your clipboard during the ZIP extraction.

This prompt enforces:
- **Strict Structural Fidelity**: Instructs the agent to prioritize the exact coordinates, properties, and tree structures in `data.md` over generic CSS styling defaults or auto-generated mockups.
- **Asset Pipeline Rules**: Directs the agent to organize visual assets into the target project's `/assets/images/` directory and map them correctly in the code.
- **Visual Verification**: Tells the agent to cross-verify SVG assets against matching PNG references to ensure no bounding boxes or layout boxes are missing.
- **Zero Guesswork**: Prohibits the agent from correcting typos, changing text cases, or merging styles from child nodes up to parent containers.

---

## Installation

To install and load the plugin locally in Figma:

1. **Download the project** or clone this repository to your local machine.
2. **Open your terminal** and navigate to the project directory.
3. **Install the dependencies** by running:
   ```bash
   npm i
   ```
4. **Build the project** to compile TypeScript:
   ```bash
   npm run build
   ```
5. **Open Figma** (either in the browser or the desktop app).
6. Navigate to **Plugins** > **Development** > **Import plugin from manifest...** (or search for it under plugins menu).
7. Select the `manifest.json` file located in the root folder of this project.

---

## How to Use

Once the plugin is installed:

1. **Select a frame** or layer group from your Figma design canvas.
2. **Open the plugin** (under Plugins > Development > AI Data Extractor) and click **Extract Selection**.
3. **Download the generated ZIP file** (`figma-ai-extraction.zip`) once the process is complete.
4. **Extract the ZIP archive** into a directory.
5. **Provide the extracted folder** to your AI agent model so it has access to `data.md` and the exported visual assets, then **paste the copied prompt** from your clipboard directly into the chat to instruct the agent model on how to implement the code.

---

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