@dannote/figma-use 0.1.4 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,123 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.0] - 2025-01-17
+
+### Added
+
+- **Subcommand structure** — commands reorganized into logical groups:
+  - `node get|tree|children|move|resize|rename|clone|delete`
+  - `create rect|ellipse|line|polygon|star|frame|text|component|instance|section|page`
+  - `set fill|stroke|radius|opacity|rotation|visible|text|font|effect|layout|blend|constraints|image`
+  - `get pages|components|styles`
+  - `export node|selection|screenshot`
+  - `selection get|set`
+  - `page list|set`
+  - `viewport get|set|zoom-to-fit`
+  - `variable list|get|create|set|delete|bind`
+  - `collection list|get|create|delete`
+  - `style list|create-paint|create-text|create-effect`
+  - `boolean union|subtract|intersect|exclude`
+  - `group create|ungroup|flatten`
+  - `find`, `import`, `eval`, `status`, `proxy`, `plugin`
+- **Variables support** — full CRUD for Figma variables and collections
+- **`node tree` command** — formatted hierarchy view with properties inline
+- **Export size guards** — prevents oversized exports (max 4096px, 16MP)
+- **Tree node limit** — `node tree` limits to 500 nodes by default
+- `--force` flag to override size/node limits
+- `--timeout` flag for heavy operations (export, screenshot, eval)
+
+### Changed
+
+- **BREAKING**: Command syntax changed from flat to nested (e.g., `create-rectangle` → `create rect`)
+- Renamed args: `--parentId` → `--parent`, `--itemSpacing` → `--gap`, `--layoutMode` → `--layout`
+- Tests reorganized into separate files by command group (80 tests)
+
+### Fixed
+
+- TypeScript strict mode compliance
+- Figma API compatibility (BlurEffect, ExportSettings)
+
+## [0.1.5] - 2025-01-17
+
+### Added
+
+- CHANGELOG.md
+- SKILL.md included in npm package
+- `--timeout` flag documentation
+
+## [0.1.4] - 2025-01-17
+
+### Added
+
+- CONTRIBUTING.md with setup and PR guidelines
+
+### Changed
+
+- Updated package description and keywords
+
+## [0.1.3] - 2025-01-17
+
+### Added
+
+- AGENTS.md for contributors
+- Git tags for all versions
+
+## [0.1.2] - 2025-01-17
+
+### Added
+
+- `eval` command to execute arbitrary JavaScript in Figma plugin context
+- `figma-use plugin` auto-installs plugin to Figma settings.json
+- `--force` flag for plugin install while Figma is running
+- `--uninstall` flag to remove plugin
+- Architecture diagram in README
+- Comparison table: official Figma MCP (read-only) vs figma-use (full control)
+
+### Changed
+
+- All `proxy` and `plugin` commands now use citty for consistency
+- README examples show inline styling (one command does fill + stroke + radius)
+
+## [0.1.1] - 2025-01-17
+
+### Added
+
+- Human-readable CLI output by default (agent-browser style)
+- `--json` flag for machine parsing on all commands
+- 69 integration tests
+
+### Changed
+
+- Renamed from figma-bridge to @dannote/figma-use
+
+## [0.1.0] - 2025-01-17
+
+### Added
+
+- Initial release
+- 60+ CLI commands for Figma control
+- WebSocket proxy server (Elysia)
+- Figma plugin with all command handlers
+- Create commands: rectangle, ellipse, line, polygon, star, vector, frame, section, text, component, instance
+- Style commands: fill, stroke, corner radius, opacity, effects, blend mode
+- Layout commands: auto-layout, constraints, min/max
+- Transform commands: move, resize, rotate, set parent
+- Query commands: get node, children, selection, pages, components, styles
+- Export commands: PNG/SVG/PDF export, screenshot
+- Inline styling: `--fill`, `--stroke`, `--radius` etc. on create commands
+
+[unreleased]: https://github.com/dannote/figma-use/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/dannote/figma-use/compare/v0.1.5...v0.2.0
+[0.1.5]: https://github.com/dannote/figma-use/compare/v0.1.4...v0.1.5
+[0.1.4]: https://github.com/dannote/figma-use/compare/v0.1.3...v0.1.4
+[0.1.3]: https://github.com/dannote/figma-use/compare/v0.1.2...v0.1.3
+[0.1.2]: https://github.com/dannote/figma-use/compare/v0.1.1...v0.1.2
+[0.1.1]: https://github.com/dannote/figma-use/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/dannote/figma-use/releases/tag/v0.1.0

package/README.md

@@ -6,22 +6,23 @@ Inspired by [agent-browser](https://github.com/vercel-labs/agent-browser) (brows
 
 ## Why not the official Figma MCP?
 
-The [official Figma MCP server](https://developers.figma.com/docs/figma-mcp-server/) is **read-only** — it can extract design context and take screenshots, but cannot create or modify anything.
+The [official Figma MCP server](https://developers.figma.com/docs/figma-mcp-server/) is focused on **design-to-code** — extracting structure and variables for code generation. It cannot create or modify designs.
 
 | Feature | Official MCP | figma-use |
 |---------|-------------|-----------|
 | Read node properties | ✓ | ✓ |
 | Take screenshots | ✓ | ✓ |
-| Extract variables/styles | ✓ | ✓ |
+| Extract variables | ✓ | ✓ |
 | **Create shapes** | ✗ | ✓ |
 | **Create text** | ✗ | ✓ |
 | **Create frames & components** | ✗ | ✓ |
 | **Modify properties** | ✗ | ✓ |
 | **Set fills, strokes, effects** | ✗ | ✓ |
 | **Auto-layout** | ✗ | ✓ |
+| **Create/modify variables** | ✗ | ✓ |
 | **Execute arbitrary code** | ✗ | ✓ |
 
-figma-use gives AI agents full control over Figma — not just reading, but **creating and editing** designs.
+figma-use gives AI agents **full read/write control** over Figma.
 
 ## How it works
 
@@ -57,14 +58,10 @@ figma-use proxy
 # Quit Figma first, then:
 figma-use plugin
 
-# Or force install while Figma is running (restart required):
-figma-use plugin --force
-
-# Show plugin path only:
-figma-use plugin --path
-
-# Uninstall:
-figma-use plugin --uninstall
+# Or with options:
+figma-use plugin --force      # Force install while Figma is running
+figma-use plugin --path       # Show plugin path only
+figma-use plugin --uninstall  # Uninstall
 ```
 
 Start Figma and find the plugin in **Plugins → Development → Figma Use**.
@@ -72,165 +69,223 @@ Start Figma and find the plugin in **Plugins → Development → Figma Use**.
 ### 3. Run commands
 
 ```bash
-# Create a styled button in one command (fill + stroke + radius + layout)
-figma-use create-frame --x 0 --y 0 --width 200 --height 48 \
-  --fill "#3B82F6" --stroke "#1D4ED8" --radius 8 \
-  --layoutMode HORIZONTAL --itemSpacing 8 --padding "12,24,12,24" \
+# Create a styled button
+figma-use create frame --x 0 --y 0 --width 200 --height 48 \
+  --fill "#3B82F6" --radius 8 \
+  --layout HORIZONTAL --gap 8 --padding "12,24,12,24" \
   --name "Button"
 
-# Add text with font styling
-figma-use create-text --x 0 --y 0 --text "Click me" \
+# Add text
+figma-use create text --x 0 --y 0 --text "Click me" \
   --fontSize 16 --fontFamily "Inter" --fontStyle "Medium" --fill "#FFFFFF" \
-  --parentId "1:23"
+  --parent "1:23"
 
 # Export to PNG
-figma-use export-node --id "1:23" --format PNG --scale 2 --output button.png
+figma-use export node "1:23" --format PNG --scale 2 --output button.png
 ```
 
-All create commands support inline styling — no need for separate `set-*` calls.
+All create commands support inline styling — no need for separate `set` calls.
 
-## Output Format
+## Commands
 
-Human-readable by default:
+### Node Operations
 
 ```bash
-$ figma-use create-rectangle --x 0 --y 0 --width 100 --height 50 --fill "#FF0000"
-✓ Created rect "Rectangle"
-  id: 1:23
-  box: 100x50 at (0, 0)
-  fill: #FF0000
+figma-use node get <id>                    # Get node properties
+figma-use node tree [id]                   # Get formatted tree (default: current page)
+figma-use node tree --depth 2              # Limit tree depth
+figma-use node tree -i                     # Only interactive elements
+figma-use node children <id>               # Get child nodes
+figma-use node delete <id>                 # Delete node
+figma-use node clone <id>                  # Clone node
+figma-use node rename <id> <name>          # Rename node
+figma-use node move <id> --x <x> --y <y>   # Move node
+figma-use node resize <id> --width <w> --height <h>
+```
 
-$ figma-use get-children --id "1:2"
-[0] frame "Header" (1:3)
-    box: 1200x80 at (0, 0)
-    fill: #FFFFFF
+The `tree` command outputs a human-readable hierarchy:
 
-[1] text "Title" (1:4)
-    box: 200x32 at (20, 24)
-    font: 24px
+```
+[0] frame "Card" (1:23)
+    400×300 at (0, 0) | fill: #FFFFFF | layout: col gap=16
+  [0] text "Title" (1:24)
+      200×32 at (24, 24) | fill: #000000 | "Hello World" | font: 24px Inter Bold
+  [1] frame "Content" (1:25)
+      352×200 at (24, 72) | fill: #F5F5F5 | radius: 8
 ```
 
-Add `--json` for machine-readable output:
+### Create Shapes
 
 ```bash
-$ figma-use get-node --id "1:2" --json
-{
-  "id": "1:2",
-  "name": "Frame",
-  "type": "FRAME",
-  ...
-}
+figma-use create rect --x 0 --y 0 --width 100 --height 50 [--fill --stroke --radius]
+figma-use create ellipse --x 0 --y 0 --width 100 --height 100 [--fill]
+figma-use create line --x 0 --y 0 --length 100 [--stroke]
+figma-use create polygon --x 0 --y 0 --size 60 --sides 6 [--fill]
+figma-use create star --x 0 --y 0 --size 60 --points 5 [--fill]
+figma-use create vector --x 0 --y 0 --path "M0,0 L100,100"
 ```
 
-## Commands
+### Create Containers
+
+```bash
+figma-use create frame --x 0 --y 0 --width 400 --height 300 \
+  [--fill --radius --layout HORIZONTAL --gap 12 --padding "16,16,16,16"]
+figma-use create component --x 0 --y 0 --width 200 --height 100
+figma-use create instance --component <id> --x 100 --y 100
+figma-use create section --x 0 --y 0 --width 800 --height 600 --name "Hero"
+figma-use create page "Page Name"
+```
+
+### Create Text
+
+```bash
+figma-use create text --x 0 --y 0 --text "Hello" \
+  [--fontSize 24 --fontFamily "Inter" --fontStyle "Bold" --fill "#000"]
+```
+
+### Set Properties
+
+```bash
+figma-use set fill <id> "#FF0000"
+figma-use set stroke <id> "#000" [--weight 2]
+figma-use set radius <id> --radius 12
+figma-use set radius <id> --topLeft 16 --bottomRight 16
+figma-use set opacity <id> 0.5
+figma-use set rotation <id> 45
+figma-use set visible <id> false
+figma-use set text <id> "New text"
+figma-use set font <id> --family "Inter" --style "Bold" --size 20
+figma-use set effect <id> --type DROP_SHADOW --radius 10 --offsetY 4 --color "#00000040"
+figma-use set layout <id> --mode VERTICAL --gap 12 --padding 16
+figma-use set blend <id> MULTIPLY
+figma-use set constraints <id> --horizontal CENTER --vertical MAX
+figma-use set image <id> image.png [--mode FILL]
+```
 
-### Shapes
-
-| Command | Description |
-|---------|-------------|
-| `create-rectangle` | Create rectangle with optional fill, stroke, radius |
-| `create-ellipse` | Create ellipse/circle |
-| `create-line` | Create line |
-| `create-polygon` | Create polygon |
-| `create-star` | Create star |
-| `create-vector` | Create vector path |
-
-### Containers
-
-| Command | Description |
-|---------|-------------|
-| `create-frame` | Create frame with optional auto-layout |
-| `create-component` | Create component |
-| `create-instance` | Create component instance |
-| `create-section` | Create section |
-| `group-nodes` | Group nodes |
-| `ungroup-node` | Ungroup |
-
-### Text
-
-| Command | Description |
-|---------|-------------|
-| `create-text` | Create text with font, size, color |
-| `set-text` | Update text content |
-| `set-font` | Change font family, size, weight |
-| `set-text-properties` | Line height, letter spacing, alignment |
-
-### Styling
-
-| Command | Description |
-|---------|-------------|
-| `set-fill-color` | Set fill color |
-| `set-stroke-color` | Set stroke color and weight |
-| `set-corner-radius` | Set corner radius (uniform or individual) |
-| `set-opacity` | Set opacity |
-| `set-effect` | Add shadow or blur |
-| `set-blend-mode` | Set blend mode |
-
-### Layout
-
-| Command | Description |
-|---------|-------------|
-| `set-layout` | Enable auto-layout (horizontal/vertical) |
-| `set-layout-child` | Set child sizing (fill/fixed/hug) |
-| `set-constraints` | Set resize constraints |
-| `set-min-max` | Set min/max width/height |
-
-### Transform
-
-| Command | Description |
-|---------|-------------|
-| `move-node` | Move to x, y |
-| `resize-node` | Resize to width, height |
-| `set-rotation` | Rotate by angle |
-| `set-parent` | Move to different parent |
+### Variables (Design Tokens)
+
+```bash
+figma-use variable list [--type COLOR|FLOAT|STRING|BOOLEAN]
+figma-use variable get <id>
+figma-use variable create "Primary" --collection <id> --type COLOR --value "#FF0000"
+figma-use variable set <id> --mode <modeId> --value "#00FF00"
+figma-use variable delete <id>
+figma-use variable bind --node <nodeId> --field fills --variable <varId>
+
+figma-use collection list
+figma-use collection get <id>
+figma-use collection create "Colors"
+figma-use collection delete <id>
+```
+
+### Styles
+
+```bash
+figma-use style list
+figma-use style create-paint "Brand/Primary" --color "#E11D48"
+figma-use style create-text "Heading/H1" --family "Inter" --style "Bold" --size 32
+figma-use style create-effect "Shadow/Medium" --type DROP_SHADOW --radius 8 --offsetY 4
+```
 
 ### Export
 
-| Command | Description |
-|---------|-------------|
-| `export-node` | Export node as PNG/SVG/PDF |
-| `screenshot` | Screenshot current viewport |
+```bash
+figma-use export node <id> [--format PNG|SVG|PDF] [--scale 2] [--output file.png]
+figma-use export selection [--format PNG] [--scale 2] [--output file.png]
+figma-use export screenshot [--output viewport.png]
+```
 
-### Query
+Export commands have built-in guards against oversized exports (max 4096px dimension, 16MP total). Override with `--force`:
 
-| Command | Description |
-|---------|-------------|
-| `get-node` | Get node properties |
-| `get-children` | Get child nodes |
-| `get-selection` | Get selected nodes |
-| `get-pages` | List all pages |
-| `find-by-name` | Find nodes by name |
+```bash
+figma-use export node <id> --scale 10 --force
+```
 
-### Navigation
+Heavy operations support `--timeout` (seconds):
+```bash
+figma-use export node <id> --scale 2 --output large.png --timeout 300
+```
 
-| Command | Description |
-|---------|-------------|
-| `set-current-page` | Switch to page |
-| `zoom-to-fit` | Zoom to fit nodes |
-| `set-viewport` | Set viewport position and zoom |
+### Selection & Navigation
 
-### Advanced
+```bash
+figma-use selection get
+figma-use selection set "1:2,1:3,1:4"
+
+figma-use page list
+figma-use page set <id|name>
+
+figma-use viewport get
+figma-use viewport set --x 100 --y 200 --zoom 0.5
+figma-use viewport zoom-to-fit <ids...>
+```
 
-| Command | Description |
-|---------|-------------|
-| `eval` | Execute arbitrary JavaScript in Figma |
+### Find & Query
 
-#### eval
+```bash
+figma-use find --name "Button"
+figma-use find --name "Icon" --type FRAME
+figma-use get pages
+figma-use get components
+figma-use get styles
+```
 
-Run any JavaScript code in the Figma plugin context:
+### Boolean & Group
 
 ```bash
-# Simple expression
-figma-use eval "return 2 + 2"
+figma-use boolean union "1:2,1:3"
+figma-use boolean subtract "1:2,1:3"
+figma-use boolean intersect "1:2,1:3"
+figma-use boolean exclude "1:2,1:3"
+
+figma-use group create "1:2,1:3"
+figma-use group ungroup <id>
+figma-use group flatten "1:2,1:3"
+```
 
-# Access Figma API
-figma-use eval "return figma.currentPage.name"
+### Advanced
 
-# Create nodes
+```bash
+# Execute arbitrary JavaScript in Figma
+figma-use eval "return figma.currentPage.name"
 figma-use eval "const r = figma.createRectangle(); r.resize(100, 100); return r.id"
+figma-use eval "await figma.loadFontAsync({family: 'Inter', style: 'Bold'})"
+
+# Import SVG
+figma-use import --svg "<svg>...</svg>" --x 0 --y 0
+```
+
+## Output Format
+
+Human-readable by default:
+
+```bash
+$ figma-use create rect --x 0 --y 0 --width 100 --height 50 --fill "#FF0000"
+✓ Created rect "Rectangle"
+  id: 1:23
+  box: 100x50 at (0, 0)
+  fill: #FF0000
+
+$ figma-use node children "1:2"
+[0] frame "Header" (1:3)
+    box: 1200x80 at (0, 0)
+    fill: #FFFFFF
 
-# Async code (top-level await supported)
-figma-use eval "const node = await figma.getNodeByIdAsync('1:2'); return node.name"
+[1] text "Title" (1:4)
+    box: 200x32 at (20, 24)
+    font: 24px
+```
+
+Add `--json` for machine-readable output:
+
+```bash
+$ figma-use node get "1:2" --json
+{
+  "id": "1:2",
+  "name": "Frame",
+  "type": "FRAME",
+  ...
+}
 ```
 
 ## Environment Variables
@@ -250,10 +305,10 @@ Copy the included skill to teach your agent how to use figma-use:
 
 ```bash
 # From npm package
-cp node_modules/@dannote/figma-use/SKILL.md ~/.claude/skills/figma-use/SKILL.md
+mkdir -p ~/.claude/skills/figma-use
+cp node_modules/@dannote/figma-use/SKILL.md ~/.claude/skills/figma-use/
 
 # Or download directly
-mkdir -p ~/.claude/skills/figma-use
 curl -o ~/.claude/skills/figma-use/SKILL.md \
   https://raw.githubusercontent.com/dannote/figma-use/main/SKILL.md
 ```
@@ -271,13 +326,13 @@ For agents that don't support skills, add to your project's `CLAUDE.md` or `AGEN
 ```markdown
 ## Figma Automation
 
-Use `figma-use` for Figma control. Run `figma-use --help` for all 73 commands.
+Use `figma-use` for Figma control. Run `figma-use --help` for commands.
 
-Quick workflow:
+Workflow:
 1. `figma-use status` - Check plugin connection
-2. `figma-use create-frame --x 0 --y 0 --width 400 --height 300 --fill "#FFF" --name "Card"`
-3. `figma-use create-text --x 20 --y 20 --text "Title" --fontSize 24 --fill "#000" --parentId "1:2"`
-4. `figma-use screenshot --output preview.png` - Verify result
+2. `figma-use create frame --x 0 --y 0 --width 400 --height 300 --fill "#FFF" --name "Card"`
+3. `figma-use create text --x 20 --y 20 --text "Title" --fontSize 24 --fill "#000" --parent "1:2"`
+4. `figma-use export screenshot --output preview.png` - Verify result
 ```
 
 ## License