diff --git a/README.md b/README.md index 64bbc21..e3761f9 100644 --- a/README.md +++ b/README.md @@ -1,40 +1,128 @@ -Below are the steps to get your plugin running. You can also find instructions at: +# AI Data Extractor — Figma Plugin - https://www.figma.com/plugin-docs/plugin-quickstart-guide/ +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. -This plugin template uses Typescript and NPM, two standard tools in creating JavaScript applications. +--- -First, download Node.js which comes with NPM. This will allow you to install TypeScript and other -libraries. You can find the download link here: +## What It Does - https://nodejs.org/en/download/ +Select any frame or group of layers in Figma, click **Extract**, and the plugin will: -Next, install TypeScript using the command: +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 - npm install -g typescript +--- -Finally, in the directory of your plugin, get the latest type definitions for the plugin API by running: +## Output Structure - npm install --save-dev @figma/plugin-typings +The generated ZIP follows a predictable, hierarchical folder structure: -If you are familiar with JavaScript, TypeScript will look very familiar. In fact, valid JavaScript code -is already valid Typescript code. +``` +figma-ai-extraction.zip +├── data.md # Full hierarchical tree + properties +└── / # One folder per selected root node + ├── .png + ├── .svg + └── children/ + └── / + ├── .png + ├── .svg + └── children/ + └── ... # Recursively nested +``` -TypeScript adds type annotations to variables. This allows code editors such as Visual Studio Code -to provide information about the Figma API while you are writing code, as well as help catch bugs -you previously didn't notice. +### `data.md` -For more information, visit https://www.typescriptlang.org/ +The markdown file contains: -Using TypeScript requires a compiler to convert TypeScript (code.ts) into JavaScript (code.js) -for the browser to run. +- **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) -We recommend writing TypeScript code using Visual Studio code: +### Asset Export Rules -1. Download Visual Studio Code if you haven't already: https://code.visualstudio.com/. -2. Open this directory in Visual Studio Code. -3. Compile TypeScript to JavaScript: Run the "Terminal > Run Build Task..." menu item, - then select "npm: watch". You will have to do this again every time - you reopen Visual Studio Code. +| 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 | -That's it! Visual Studio Code will regenerate the JavaScript file every time you save. +--- + +## 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 +```