1 changed files with 113 additions and 25 deletions
-
138README.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 |
||||
|
└── <TopLevelNode>/ # One folder per selected root node |
||||
|
├── <NodeName>.png |
||||
|
├── <NodeName>.svg |
||||
|
└── children/ |
||||
|
└── <ChildNode>/ |
||||
|
├── <ChildNode>.png |
||||
|
├── <ChildNode>.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 |
||||
|
``` |
||||
Write
Preview
Loading…
Cancel
Save
Reference in new issue