figma-local 1.0.0 → 1.2.0

package/skills/figma-local/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: figma-local
+description: |
+  Use this skill whenever the user wants to work with Figma designs, read design context, get design specs, translate designs to code, generate CSS from Figma, inspect UI components, extract design tokens, or bridge Figma Desktop with code. Triggers on: "read the design", "get the Figma specs", "what's on the canvas", "match the design", "inspect this component", "generate CSS from Figma", "get the colors/fonts/spacing", "design tokens", "Figma to code", "check Figma", "read from Figma", or any reference to reading, inspecting, or extracting from Figma designs. Do NOT trigger for Figma API (REST), Figma plugins development, or Figma file URL fetching — this is for local Figma Desktop control only.
+allowed-tools:
+  - Bash(fig *)
+  - Bash(fig-start *)
+  - Bash(figma-cli *)
+---
+
+# Figma Local
+
+Control Figma Desktop directly from Claude Code. Read designs, inspect specs, generate CSS/Tailwind, extract styles — no API key required.
+
+## Prerequisites
+
+The `fig` CLI must be installed and connected to Figma Desktop.
+
+**Check status:**
+```bash
+fig daemon status
+```
+
+**If not connected:**
+```bash
+fig connect --safe
+```
+
+This starts the daemon and waits for the Figma Local plugin to connect. The user must have the plugin running in Figma Desktop (Plugins > Development > Figma Local).
+
+**If not installed:**
+```bash
+npm install -g figma-local
+```
+
+## Workflow: Design to Code
+
+Always follow this staged approach — never dump the full canvas at once.
+
+### Step 1 — Scan the canvas (always do this first)
+
+```bash
+fig read
+```
+
+Returns: page name, frame names, sizes, count. Use this to understand what exists before doing anything else.
+
+### Step 2 — Read a specific frame
+
+```bash
+fig read "Login Screen"
+```
+
+Returns: layout hierarchy, component tree, text content, and only the design tokens that frame uses. This is the primary command for getting design context.
+
+### Step 3 — Get detailed specs for a specific element
+
+Select the element in Figma, then:
+
+```bash
+fig inspect
+```
+
+Returns: dimensions (px + rem), padding, gap, colors (hex + rgba), typography (font, size, weight, line-height, letter-spacing), border radius, strokes, shadows, opacity, variable bindings.
+
+### Step 4 — Generate code-ready CSS
+
+```bash
+fig css                   # CSS in rem
+fig css --px              # CSS in px
+fig css --tailwind        # Tailwind utility classes
+```
+
+### Step 5 — Verify your implementation
+
+```bash
+fig verify                # Screenshot for visual comparison
+```
+
+## Command Reference
+
+### Reading designs
+
+| Command | What it does |
+|---------|-------------|
+| `fig read` | List all frames on the current page |
+| `fig read "Frame Name"` | Layout tree + components + used tokens for that frame |
+| `fig read "Frame" --tokens` | Only the design tokens that frame uses |
+| `fig read --selection` | Read whatever is selected in Figma |
+| `fig read --link "https://..."` | Read a node from a Figma selection URL |
+| `fig read --json` | Raw JSON output |
+
+### Inspecting specs
+
+| Command | What it does |
+|---------|-------------|
+| `fig inspect` | Full specs for current selection (px + rem) |
+| `fig inspect --deep` | Inspect element + all children |
+| `fig inspect --link "https://..."` | Inspect from a Figma link |
+| `fig inspect --node "123:456"` | Inspect a specific node ID |
+| `fig inspect --json` | Raw JSON output |
+
+### Generating CSS
+
+| Command | What it does |
+|---------|-------------|
+| `fig css` | CSS for current selection (rem units) |
+| `fig css --px` | CSS in px units |
+| `fig css --tailwind` | Tailwind utility classes |
+| `fig css --link "https://..."` | CSS from a Figma link |
+| `fig css --node "123:456"` | CSS for a specific node |
+
+### Measuring spacing
+
+| Command | What it does |
+|---------|-------------|
+| `fig measure` | Select 2 elements in Figma, get spacing between them (px + rem) |
+
+### Extracting styles
+
+| Command | What it does |
+|---------|-------------|
+| `fig styles "Frame Name"` | All text styles, colors, spacing, radii in that frame |
+| `fig styles --selection` | Styles from current selection |
+| `fig styles --link "https://..."` | Styles from a Figma link |
+
+### Design tokens
+
+| Command | What it does |
+|---------|-------------|
+| `fig tokens preset shadcn` | Apply full shadcn token system (Light/Dark) |
+| `fig tokens tailwind` | Apply Tailwind color palette |
+| `fig var list` | List all variables |
+| `fig var export css` | Export as CSS custom properties |
+| `fig var export tailwind` | Export as Tailwind config |
+
+### Creating in Figma
+
+| Command | What it does |
+|---------|-------------|
+| `fig render '<JSX>'` | Render JSX to Figma canvas |
+| `fig shadcn add button card` | Add shadcn/ui components |
+| `fig blocks create dashboard-01` | Pre-built dashboard layout |
+| `fig create icon lucide:home` | Add icons (150k+ via Iconify) |
+
+### Exporting
+
+| Command | What it does |
+|---------|-------------|
+| `fig prompt "Frame" --target lovable` | AI prompt for Lovable |
+| `fig prompt "Frame" --target figma-make` | AI prompt for Figma Make |
+| `fig export screenshot -o out.png` | Screenshot |
+| `fig export-jsx "1:234"` | Export as React JSX |
+
+### Verification
+
+| Command | What it does |
+|---------|-------------|
+| `fig verify` | Screenshot of current selection |
+| `fig verify --compare "url"` | Compare prototype vs design |
+| `fig lint` | Design lint (accessibility, contrast, etc.) |
+
+## Important Rules
+
+1. **Always `fig read` first** — scan the canvas before doing anything
+2. **Staged reading** — never request full canvas data; focus on one frame at a time
+3. **Verify after creating** — always run `fig verify` after rendering or adding components
+4. **Use `fig inspect` for pixel-perfect code** — it gives exact specs in px + rem
+5. **Use `fig css` to generate code** — paste directly into your codebase
+6. **Select in Figma first** — most commands operate on the current Figma selection

package/skills/figma-measure/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: figma-measure
+description: |
+  Use this skill when the user wants to measure spacing, gaps, or distances between elements in Figma. Triggers on: "measure spacing", "distance between", "gap between", "how far apart", "spacing between elements", "measure the gap". Requires exactly 2 elements to be selected in Figma.
+allowed-tools:
+  - Bash(fig measure *)
+  - Bash(fig measure)
+---
+
+# Figma Measure
+
+Measure the exact spacing between two selected elements in Figma. Returns horizontal gap, vertical gap, and center-to-center distance — all in px and rem.
+
+## Prerequisites
+
+The `fig` CLI must be connected. Check with `fig daemon status`. If not connected: `fig connect --safe`.
+
+## Usage
+
+Select exactly **2 elements** in Figma (hold Shift and click both), then:
+
+```bash
+fig measure
+```
+
+**Output example:**
+```
+Submit Button (120x44)
+  |
+Cancel Button (100x44)
+
+Spacing
+  Horizontal: 16px (1rem)
+  Vertical:   0px (0rem)
+Center-to-center
+  X: 126px (7.875rem)
+  Y: 0px (0rem)
+```
+
+### Raw JSON output
+
+```bash
+fig measure --json
+```
+
+## When to use
+
+- Checking the gap between sibling elements (buttons, cards, list items)
+- Verifying margin/spacing values when coding a layout
+- Comparing spacing consistency across a design
+- Measuring distance between a label and its input field
+
+## Tips
+
+- Select exactly 2 elements — fewer or more will fail
+- Hold Shift in Figma to multi-select
+- Horizontal spacing of 0 means elements overlap or are aligned vertically
+- Vertical spacing of 0 means elements are on the same horizontal line
+- Center-to-center distance is useful for grid alignment verification

package/skills/figma-styles/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: figma-styles
+description: |
+  Use this skill when the user wants to extract a style guide, design system overview, or all unique styles from a Figma frame or component. Triggers on: "what styles are used", "style guide", "extract colors", "extract typography", "what fonts", "spacing scale", "design system", "all the colors in this frame", "text styles", "border radii used". Also use when setting up a project's CSS variables, Tailwind config, or theme from a Figma design. Requires a frame name or element selected in Figma.
+allowed-tools:
+  - Bash(fig styles *)
+  - Bash(fig styles)
+  - Bash(fig read *)
+  - Bash(fig read)
+---
+
+# Figma Styles
+
+Extract all unique text styles, colors, spacing values, and border radii from a Figma frame — a complete mini style guide for translating designs to code.
+
+## Prerequisites
+
+The `fig` CLI must be connected. Check with `fig daemon status`. If not connected: `fig connect --safe`.
+
+## Usage
+
+### Extract styles from a named frame
+
+```bash
+fig styles "Login Screen"
+```
+
+**Output example:**
+```
+Typography (4 styles)
+  Inter Bold  24px (1.5rem)  line-height: 32px  x2
+  Inter Medium  16px (1rem)  line-height: 24px  x5
+  Inter Regular  14px (0.875rem)  line-height: 20px  x8
+  Inter Regular  12px (0.75rem)  line-height: 16px  x3
+
+Colors (6 unique)
+  #18181b  used by: Heading, Label  x7
+  #71717a  used by: Description, Helper text  x4
+  #ffffff  used by: Card, Input  x3
+  #f4f4f5  used by: Background  x1
+  #3b82f6  used by: Button  x2
+  #ef4444  used by: Error text  x1
+
+Spacing scale (5 values)
+  4px      0.25rem   x3
+  8px      0.5rem    x8
+  12px     0.75rem   x4
+  16px     1rem      x6
+  24px     1.5rem    x2
+
+Border radii (3 values)
+  4px      0.25rem   x2
+  8px      0.5rem    x5
+  full     full      x3
+```
+
+### Extract from current selection
+
+```bash
+fig styles --selection
+```
+
+### Extract from a Figma link
+
+```bash
+fig styles --link "https://www.figma.com/design/FILEID/Name?node-id=123-456"
+```
+
+### Raw JSON output
+
+```bash
+fig styles --json
+```
+
+## What it extracts
+
+| Category | Details |
+|----------|---------|
+| **Typography** | Font family, style, size (px + rem), line-height, usage count |
+| **Colors** | Hex values, which layers use them, usage count (fills + strokes) |
+| **Spacing** | All gap and padding values used (px + rem), usage count |
+| **Border radii** | All corner radius values (px + rem), usage count |
+
+## Workflow: Setting Up a Project Theme
+
+1. **Scan the canvas:** `fig read` to see available frames
+2. **Extract styles:** `fig styles "Main Screen"` to get the full style inventory
+3. **Map to your system:**
+   - Typography → CSS font classes or Tailwind `text-*` utilities
+   - Colors → CSS custom properties or Tailwind `colors` config
+   - Spacing → Tailwind `spacing` scale or CSS variables
+   - Radii → Tailwind `borderRadius` config
+4. **Export tokens if available:** `fig var export css` or `fig var export tailwind`
+
+## Combining with other commands
+
+```bash
+# Get the full picture for a frame
+fig read "Dashboard"           # Structure + component tree
+fig styles "Dashboard"         # All unique styles used
+fig var export css             # Design tokens as CSS variables
+
+# Then for individual components
+fig inspect                    # Exact specs for selected element
+fig css                        # Ready-to-paste CSS
+```
+
+## Tips
+
+- Usage count (`xN`) shows how many times a style appears — higher counts indicate primary/system styles
+- Colors are sorted by frequency — the most-used color appears first
+- Spacing values are sorted by size — helps identify the spacing scale
+- Use `--json` to pipe into scripts that generate Tailwind configs or CSS variable files
+- Run on the top-level page frame to get the complete style inventory for a screen

package/src/daemon.js

@@ -72,7 +72,7 @@ async function getFigmaClient() {
 
 const PORT = parseInt(process.env.DAEMON_PORT) || 3456;
 const MODE = process.env.DAEMON_MODE || 'auto'; // 'auto', 'cdp', 'plugin'
-const IDLE_TIMEOUT_MS = parseInt(process.env.DAEMON_IDLE_TIMEOUT) || 10 * 60 * 1000; // Default: 10 minutes
+const IDLE_TIMEOUT_MS = parseInt(process.env.DAEMON_IDLE_TIMEOUT) || 60 * 60 * 1000; // Default: 1 hour
 
 // ============ SECURITY ============