@mstrathman/figma 0.1.0 → 0.2.1

package/CHANGELOG.md

@@ -5,6 +5,10 @@ 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).
 
+## [0.2.1] - 2026-01-18
+
+## [0.2.0] - 2026-01-18
+
 ## [0.1.0] - 2025-01-17
 
 ### Added

package/README.md

@@ -1,6 +1,6 @@
 # figma
 
-A command-line interface for the Figma API, inspired by GitHub's `gh` CLI. Built for design-to-code workflows.
+A command-line interface for the Figma API, inspired by GitHub's `gh` CLI. Built for design-to-code workflows and agent-to-agent handoffs.
 
 > **Note:** This is an unofficial tool and is not affiliated with or endorsed by Figma, Inc.
 
@@ -58,17 +58,54 @@ figma auth status
 
 ## Commands
 
+All commands accept either a **Figma URL** or a **file key**:
+
+```bash
+# Using full Figma URL (recommended)
+figma file get "https://www.figma.com/file/ABC123xyz/My-Design"
+
+# Using file key
+figma file get ABC123xyz
+```
+
 ### Files
 
 ```bash
-# Get file structure
-figma file get <file-key>
+# Get file JSON structure
+figma file get <url>
+
+# Get simplified file structure (for understanding hierarchy)
+figma file structure <url>
+figma file structure <url> --depth 3 --format tree
 
 # Get specific nodes
-figma file nodes <file-key> --ids "1:2,1:3"
+figma file nodes <url> --id "1:2,1:3"
+
+# Export images from nodes
+figma file images <url> --id "1:2" --format svg --output ./exports
+
+# Use node-id from URL directly
+figma file images "https://www.figma.com/file/ABC123xyz/Design?node-id=1-2" -o ./exports
+
+# Naming strategies for exported images
+figma file images <url> --id "1:2,1:3" --naming name -o ./icons    # Uses node names
+figma file images <url> --id "1:2,1:3" --naming path -o ./icons    # Includes parent path
+```
+
+### Frames
+
+```bash
+# List all frames in a file
+figma frame list --file <url>
+
+# Filter by page
+figma frame list --file <url> --page "Components"
 
-# Export images
-figma file images <file-key> --ids "1:2" --format svg --output ./icons
+# Filter by type
+figma frame list --file <url> --type component,component_set
+
+# Only top-level frames
+figma frame list --file <url> --top-level --format table
 ```
 
 ### Projects
@@ -85,7 +122,7 @@ figma project files <project-id>
 
 ```bash
 # List components in a file
-figma component list --file <file-key>
+figma component list --file <url>
 
 # List team components
 figma component list --team <team-id>
@@ -98,7 +135,7 @@ figma component get <component-key>
 
 ```bash
 # List styles in a file
-figma style list --file <file-key>
+figma style list --file <url>
 
 # List team styles
 figma style list --team <team-id>
@@ -111,27 +148,62 @@ figma style get <style-key>
 
 ```bash
 # List variables
-figma variable list <file-key>
+figma variable list <url>
 
 # Export as design tokens
-figma variable export <file-key> --format css --output tokens.css
-figma variable export <file-key> --format style-dictionary --output tokens.json
+figma variable export <url> --format css --output tokens.css
+figma variable export <url> --format style-dictionary --output tokens.json
+
+# Group by scope (colors, spacing, radius, etc.)
+figma variable export <url> --categorize --format css
 ```
 
 ### Export (Design-to-Code)
 
 ```bash
-# Export design tokens
-figma export tokens <file-key> --format css
-figma export tokens <file-key> --format scss
-figma export tokens <file-key> --format tailwind
-figma export tokens <file-key> --format style-dictionary
+# Export design tokens from styles
+figma export tokens <url> --format css
+figma export tokens <url> --format scss
+figma export tokens <url> --format tailwind
+figma export tokens <url> --format style-dictionary
 
 # Export icons
-figma export icons <file-key> --frame "Icons" --format svg --output ./icons
+figma export icons <url> --frame "Icons" --format svg --output ./icons
+
+# Handle icon variants
+figma export icons <url> --variant-format suffix   # icon-name--large.svg
+figma export icons <url> --variant-format folder   # icon-name/large.svg
 
 # Export complete theme package
-figma export theme <file-key> --formats "css,json,tailwind" --output ./theme
+figma export theme <url> --formats "css,json,tailwind" --output ./theme
+```
+
+### Handoff (All-in-One)
+
+Export a complete design handoff package for developers or AI agents:
+
+```bash
+# Export everything
+figma handoff <url> --all --output ./design-handoff
+
+# Customize what to export
+figma handoff <url> --tokens css,scss --assets --structure --readme
+
+# Just tokens and structure (no assets)
+figma handoff <url> --tokens css,json --structure
+```
+
+Output structure:
+
+```
+figma-handoff/
+├── tokens/
+│   ├── tokens.css
+│   └── tokens.json
+├── assets/
+│   └── *.svg
+├── structure.json
+└── HANDOFF.md
 ```
 
 ### Raw API Access
@@ -155,7 +227,8 @@ Most commands support `--format` for output:
 - `table` - Human-readable table format
 
 ```bash
-figma component list --file <key> --format table
+figma component list --file <url> --format table
+figma frame list --file <url> --format table
 ```
 
 ## Configuration
@@ -167,39 +240,60 @@ Configuration is loaded in this priority order:
 3. Local config (`.figmarc` in current directory)
 4. User config (`~/.config/figma/config.json`)
 
-## File Keys
+## Figma URLs
 
-File keys can be found in Figma URLs:
+Commands accept full Figma URLs with automatic parsing:
 
 ```
-https://www.figma.com/file/ABC123xyz/My-Design
-                           ^^^^^^^^^
-                           This is the file key
+https://www.figma.com/file/ABC123xyz/My-Design?node-id=1-2
+                           ^^^^^^^^^                  ^^^
+                           file key                   node ID (optional)
 ```
 
+The CLI extracts the file key and node ID automatically. You can override the node ID with `--id`.
+
 ## Examples
 
 ### Export a design system
 
 ```bash
 # Export tokens as CSS variables
-figma export tokens ABC123xyz --format css --output ./src/styles/tokens.css
+figma export tokens "https://www.figma.com/file/ABC123xyz/Design-System" \
+  --format css --output ./src/styles/tokens.css
 
-# Export all icons as SVGs
-figma export icons ABC123xyz --frame "Icons" --output ./src/assets/icons
+# Export all icons as SVGs with semantic names
+figma export icons "https://www.figma.com/file/ABC123xyz/Icons" \
+  --frame "Icons" --naming name --output ./src/assets/icons
 
-# Export complete theme
-figma export theme ABC123xyz --output ./src/theme
+# Complete handoff package
+figma handoff "https://www.figma.com/file/ABC123xyz/Design-System" \
+  --all --output ./design-handoff
 ```
 
 ### Automate with scripts
 
 ```bash
 # Get all components and process with jq
-figma component list --file ABC123xyz | jq '.meta.components[].name'
+figma component list --file <url> | jq '.meta.components[].name'
+
+# Export specific nodes as PNGs at 2x
+figma file images <url> --id "1:2,1:3,1:4" --format png --scale 2 --output ./exports
+
+# List all frames and their IDs
+figma frame list --file <url> --format table
+```
+
+### Agent-to-agent workflows
+
+```bash
+# Get file structure for AI analysis
+figma file structure <url> --depth 3 --format json > structure.json
+
+# Export handoff for coding agent
+figma handoff <url> --all --output ./handoff
 
-# Export specific nodes as PNGs
-figma file images ABC123xyz --ids "1:2,1:3,1:4" --format png --scale 2 --output ./exports
+# The HANDOFF.md contains structured info for LLMs
+cat ./handoff/HANDOFF.md
 ```
 
 ## Tech Stack