figma-pilot

Original source / Raw SKILL.md

---
name: figma-pilot
description: REQUIRED reading before using figma_execute. Contains API syntax, parameter formats, and examples. READ rules/*.md files for correct usage.
metadata:
  tags: figma, mcp, design, ai, components, accessibility, tokens
---

## When to use

**ALWAYS read this skill BEFORE calling figma_execute!** This skill contains the correct API syntax, parameter formats, and examples that you MUST follow. Failure to read this will result in syntax errors.

Use this skill whenever you are working with figma-pilot MCP tools to create or modify Figma designs.

## Code Execution Mode

figma-pilot uses a **code execution mode** for maximum efficiency. Instead of 15+ individual tools, you use `figma_execute` to run JavaScript code with access to all Figma APIs.

### Available Tools

| Tool | Description |
|------|-------------|
| `figma_status` | Check connection to Figma plugin (call first) |
| `figma_execute` | Execute JavaScript with all Figma APIs |
| `figma_get_api_docs` | Get detailed API documentation |

### Quick Example

```javascript
// figma_execute
// Create a card and modify selection
await figma.create({
  type: 'card',
  name: 'Welcome Card',
  children: [
    { type: 'text', content: 'Hello!', fontSize: 24 }
  ]
});

const { nodes } = await figma.query({ target: 'selection' });
for (const node of nodes) {
  await figma.modify({ target: node.id, fill: '#0066FF' });
}
console.log(`Modified ${nodes.length} elements`);
```

### Benefits

- **90%+ fewer tokens** - 3 tools instead of 15+
- **Batch operations** - Modify many elements in one call
- **Data filtering** - Filter results before returning to context
- **Complex workflows** - Loops, conditionals, error handling

## API Reference

Read individual rule files for detailed API documentation:

### Getting Started
- [rules/quick-start.md](rules/quick-start.md) - Quick start guide and setup requirements
- [rules/workflow.md](rules/workflow.md) - Recommended agent workflow and operator rules

### Core APIs
- [rules/status.md](rules/status.md) - `figma.status()` - Check connection
- [rules/query.md](rules/query.md) - `figma.query()` - Query elements by ID, name, or selection

### Creating Elements
- [rules/create.md](rules/create.md) - `figma.create()` - Create elements (frames, text, shapes, semantic types)
- [rules/layout.md](rules/layout.md) - Auto-layout configuration and patterns

### Modifying Elements
- [rules/modify.md](rules/modify.md) - `figma.modify()`, `figma.delete()`, `figma.append()`

### Styling
- [rules/effects.md](rules/effects.md) - Shadows, blur, and visual effects
- [rules/gradients.md](rules/gradients.md) - Gradient fills (linear, radial, angular)
- [rules/corner-radius.md](rules/corner-radius.md) - Independent corner radius
- [rules/strokes.md](rules/strokes.md) - Stroke styling (dash patterns, caps, alignment)
- [rules/transforms.md](rules/transforms.md) - Rotation and blend modes
- [rules/constraints.md](rules/constraints.md) - Responsive constraints and min/max sizes

### Text
- [rules/text.md](rules/text.md) - Text elements, wrapping, and sizing
- [rules/fonts.md](rules/fonts.md) - Loading and using custom fonts

### Components
- [rules/components.md](rules/components.md) - `figma.listComponents()`, `figma.instantiate()`, `figma.toComponent()`, `figma.createVariants()`

### Accessibility
- [rules/accessibility.md](rules/accessibility.md) - `figma.accessibility()` - WCAG compliance checking and auto-fixing

### Design Tokens
- [rules/tokens.md](rules/tokens.md) - `figma.createToken()`, `figma.bindToken()`, `figma.syncTokens()`

### Export
- [rules/export.md](rules/export.md) - `figma.export()` - Export as PNG, SVG, PDF, JPG

### Common Patterns
- [rules/patterns.md](rules/patterns.md) - Cards, navigation bars, page layouts

### Reference
- [rules/target-specifiers.md](rules/target-specifiers.md) - How to target elements (ID, selection, name)


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### rules/quick-start.md

```markdown
---
name: quick-start
description: Quick start guide and setup requirements for figma-pilot
metadata:
  tags: setup, installation, getting-started
---

## Quick Start

figma-pilot uses **code execution mode** for efficiency. Use `figma_execute` to run JavaScript with all Figma APIs:

```javascript
// First, check connection
figma_status()

// Then use figma_execute for all operations:

// Create a simple frame
await figma.create({ type: "frame", name: "Card", width: 320, height: 200 });

// Create a button with auto-layout
await figma.create({ type: "button", name: "Submit" });

// Modify the current selection
await figma.modify({ target: "selection", fill: "#FF0000" });

// Check accessibility
const result = await figma.accessibility({ target: "selection", level: "AA", autoFix: true });
console.log(`Fixed ${result.fixedCount} issues`);
```

## Available Tools

| Tool | Description |
|------|-------------|
| `figma_status` | Check connection (call first) |
| `figma_execute` | Execute JavaScript with Figma APIs |
| `figma_get_api_docs` | Get detailed API documentation |

## Setup Requirements

1. The figma-pilot Figma plugin must be installed and running in Figma Desktop
2. The MCP server must be configured in your AI client (Claude, Cursor, Codex, etc.)
3. Call `figma_status()` first to verify the connection
4. Call `figma_get_api_docs()` if you need detailed API parameter documentation

```

### rules/workflow.md

```markdown
---
name: workflow
description: Recommended agent workflow and operator rules for figma-pilot
metadata:
  tags: workflow, best-practices, tips
---

## Agent Workflow (Recommended)

figma-pilot uses **code execution mode**. Use `figma_status` to check connection, then `figma_execute` for all operations:

```text
1) figma_status                     # Check connection first
2) figma_execute with your code     # All operations in one call
3) figma_export at the end          # Export for review (inside figma_execute)
```

### Example Workflow

```javascript
// figma_execute - complete workflow in one call
// 1. Query existing elements
const { nodes } = await figma.query({ target: 'selection' });

// 2. List components if needed
const { components } = await figma.listComponents({ filter: 'Button' });

// 3. Create/modify elements
await figma.create({
  type: 'card',
  name: 'New Card',
  children: [
    { type: 'text', content: 'Title', fontSize: 18 }
  ]
});

// 4. Check accessibility
const a11y = await figma.accessibility({ target: 'selection', autoFix: true });
console.log(`Accessibility: ${a11y.passed} passed, ${a11y.fixedCount} fixed`);

// 5. Export for review
await figma.export({ target: 'selection', format: 'png', scale: 2 });
```

## Benefits of Code Execution Mode

- **Batch operations** - Modify 100 elements in one call, not 100 tool calls
- **Data filtering** - Filter query results before logging
- **Complex logic** - Loops, conditionals, error handling
- **90% fewer tokens** - 3 tools instead of 15+

## Operator Rules

- Always name containers you expect to modify later.
- Prefer `"name:"` targeting over IDs for stability.
- Use `children` for complex layouts instead of multiple create calls.
- If no selection exists, use `name:` targets or create a container first.
- Export once at the end, not after each step.

## Tips for AI Agents

1. **Always call `figma_status()` first** to verify the connection
2. **Query before you modify** - use `figma.query()` to avoid mis-targeting
3. **Use `figma_get_api_docs()`** if you need detailed parameter documentation
4. **Batch operations** - do multiple creates/modifies in one `figma_execute` call
5. **Filter data before logging** - reduce output by only logging what you need
6. **Use semantic types** (`card`, `button`, `nav`) - they come pre-styled with auto-layout
7. **Use nested `children`** for complex layouts instead of creating elements separately
8. **Use `"selection"` target** for operations on user-selected elements
9. **Run accessibility checks** after creating UI components
10. **Prefer `"name:"` targeting** over IDs - names are more readable and stable
11. **Use `textColor` for text elements** instead of `fill` for better clarity
12. **Use `maxWidth` for long text** to enable automatic text wrapping
13. **Use `layoutSizingHorizontal: "FILL"`** to make child elements stretch to parent width
14. **Use tokens for consistency** via `figma.createToken()` and `figma.bindToken()`

```

### rules/status.md

```markdown
---
name: status
description: Check connection status to Figma plugin
metadata:
  tags: connection, status, health-check
---

## figma.status()

Check connection status to Figma plugin. Call this first to verify the plugin is running.

```javascript
// Use figma_status tool directly, or inside figma_execute:
await figma.status()
// Returns: { connected: true, pluginVersion: "1.0.0", documentName: "...", currentPage: "..." }
```

Always call `figma_status` before running `figma_execute` to ensure the connection is active.

```

### rules/query.md

```markdown
---
name: query
description: Query elements by ID, name, or current selection
metadata:
  tags: query, element, details, selection
---

## figma.query()

Get detailed information about elements.

```javascript
// Inside figma_execute:

// Query current selection (returns all selected elements)
const { nodes } = await figma.query({ target: "selection" });

// Query by node ID
const { node } = await figma.query({ target: "123:456" });

// Query by element name
const { node } = await figma.query({ target: "name:Hero Section" });

// Filter and process results
const rects = nodes.filter(n => n.type === "RECTANGLE");
console.log(`Found ${rects.length} rectangles`);
```

### Target Options

See [target-specifiers.md](target-specifiers.md) for full details.

| Specifier | Description | Example |
|-----------|-------------|---------|
| `"selection"` | Currently selected element(s) | Returns multiple nodes if multiple are selected |
| `"123:456"` | A specific node ID | Returns single node |
| `"name:ElementName"` | Find element by name | Returns single node |

### Response

The response includes:
- `node`: The first/only matching node (or null)
- `nodes`: Array of all matching nodes (useful for selection)

**Recommended**: Use `"name:"` prefix for targeting - names are more stable than IDs.

```

### rules/create.md

```markdown
---
name: create
description: Create elements in Figma - frames, text, shapes, and semantic types
metadata:
  tags: create, frame, text, rect, ellipse, button, card
---

## figma.create()

Create new elements in Figma. Supports frames, text, rectangles, ellipses, and semantic types.

**Basic element types**: `frame`, `text`, `rect`, `ellipse`, `line`
**Semantic types** (pre-styled): `card`, `button`, `form`, `nav`, `input`

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `type` | string | Element type (required) |
| `name` | string | Element name |
| `width` | number | Width in pixels |
| `height` | number | Height in pixels |
| `x` | number | X position |
| `y` | number | Y position |
| `parent` | string | Parent container (ID, "selection", or "name:ElementName") |
| `fill` | string | Fill color (hex, e.g., "#FF0000") |
| `stroke` | string | Stroke color (hex) |
| `strokeWidth` | number | Stroke width |
| `cornerRadius` | number | Corner radius (uniform) |
| `content` | string | Text content (for text elements) |
| `fontSize` | number | Font size (for text elements) |
| `fontWeight` | number | Font weight 100-900 (for text elements) |
| `fontFamily` | string | Font family name (e.g., "Inter", "Roboto") |
| `textAlign` | string | Text alignment: "LEFT", "CENTER", "RIGHT", "JUSTIFIED" |
| `textColor` | string | Text color (hex). Preferred over `fill` for text elements |
| `maxWidth` | number | Max width for text wrapping |
| `lineHeight` | number | Line height in pixels |
| `letterSpacing` | number | Letter spacing in pixels |
| `layout` | object | Auto-layout configuration |
| `children` | array | Nested child elements |

See also: [layout.md](layout.md), [effects.md](effects.md), [gradients.md](gradients.md), [text.md](text.md)

### Basic Examples

```javascript
// Inside figma_execute:

// Simple frame
await figma.create({ type: "frame", name: "Container", width: 400, height: 300 });

// Text element
await figma.create({ type: "text", content: "Hello World", fontSize: 24, fill: "#333333" });

// Text with custom font
await figma.create({ 
  type: "text", 
  content: "Custom Font", 
  fontFamily: "Roboto", 
  fontWeight: 700, 
  fontSize: 32,
  textAlign: "CENTER"
});

// Pre-styled button
await figma.create({ type: "button", name: "Primary Button" });

// Frame with auto-layout
await figma.create({
  type: "frame",
  name: "Row",
  layout: { direction: "row", gap: 16, padding: 24 }
});

// Positioned element
await figma.create({ type: "rect", width: 100, height: 100, x: 50, y: 50, fill: "#0066FF" });

// Create inside a parent container
await figma.create({ type: "text", content: "Hello", parent: "name:Hero Section" });
await figma.create({ type: "text", content: "Hello", parent: "selection" });
```

### Complex Nested Layout

Use the `children` parameter to create complex nested layouts in a single call.

```javascript
// Inside figma_execute:
await figma.create({
  type: "frame",
  name: "User Card",
  width: 320,
  height: 80,
  fill: "#FFFFFF",
  cornerRadius: 8,
  layout: { direction: "row", gap: 12, padding: 16 },
  children: [
    {
      type: "ellipse",
      name: "Avatar",
      width: 48,
      height: 48,
      fill: "#E0E0E0"
    },
    {
      type: "frame",
      name: "Info",
      layout: { direction: "column", gap: 4 },
      children: [
        { type: "text", content: "John Doe", fontSize: 16, fontWeight: 600 },
        { type: "text", content: "[email protected]", fontSize: 14, fill: "#666666" }
      ]
    }
  ]
});
```

**Best Practices for Nested Layouts:**
- Use `children` for complex layouts instead of multiple create calls
- Each child can have its own `children` for deep nesting
- Name important containers for easy targeting later
- Use auto-layout on parent frames for proper alignment

```

### rules/layout.md

```markdown
---
name: layout
description: Auto-layout configuration and patterns for Figma frames
metadata:
  tags: layout, auto-layout, gap, padding, alignment
---

## Layout Object Schema

```typescript
interface Layout {
  direction?: "row" | "column";
  gap?: number;
  padding?: number | { top: number; right: number; bottom: number; left: number };
  alignItems?: "start" | "center" | "end" | "baseline";
  justifyContent?: "start" | "center" | "end" | "space-between" | "space-around";
  wrap?: boolean; // Enable wrapping for multi-row/column layouts
}
```

Note: For stretch behavior, use `layoutSizingVertical` or `layoutSizingHorizontal: "FILL"` on child elements.

## Examples

```javascript
// Inside figma_execute:

// Horizontal row with gap
await figma.create({
  type: "frame",
  name: "Row",
  layout: { direction: "row", gap: 16, padding: 24 }
});

// Vertical column centered
await figma.create({
  type: "frame",
  name: "Column",
  layout: { 
    direction: "column", 
    gap: 12, 
    alignItems: "center",
    justifyContent: "center"
  }
});

// Asymmetric padding
await figma.create({
  type: "frame",
  name: "Card",
  layout: { 
    direction: "column",
    padding: { top: 24, right: 16, bottom: 24, left: 16 }
  }
});

// Wrapping layout (multi-row)
await figma.create({
  type: "frame",
  name: "Grid",
  width: 400,
  layout: {
    direction: "row",
    gap: 16,
    wrap: true  // Items wrap to next row when exceeding width
  }
});
```

## Layout Sizing

Control how child elements size within auto-layout:

| Parameter | Values | Description |
|-----------|--------|-------------|
| `layoutSizingHorizontal` | "FIXED", "HUG", "FILL" | Horizontal sizing behavior |
| `layoutSizingVertical` | "FIXED", "HUG", "FILL" | Vertical sizing behavior |

```javascript
// Inside figma_execute:

// Child element that fills parent width
await figma.create({
  type: "frame",
  width: 400,
  layout: { direction: "column", gap: 16 },
  children: [
    {
      type: "text",
      content: "Full width text",
      layoutSizingHorizontal: "FILL"  // Stretches to parent width
    }
  ]
});
```

```

### rules/modify.md

```markdown
---
name: modify
description: Modify, move, and delete elements in Figma
metadata:
  tags: modify, update, delete, append, move, properties
---

## figma.modify()

Modify existing elements.

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `target` | string | Element to modify (required): ID, "selection", or "name:ElementName" |
| `name` | string | New name |
| `width` | number | New width |
| `height` | number | New height |
| `x` | number | New X position |
| `y` | number | New Y position |
| `fill` | string | New fill color (hex) |
| `stroke` | string | New stroke color (hex) |
| `strokeWidth` | number | Stroke width |
| `cornerRadius` | number | New corner radius |
| `opacity` | number | Opacity (0-1) |
| `visible` | boolean | Visibility |
| `locked` | boolean | Lock/unlock element |
| `content` | string | New text content |
| `fontSize` | number | New font size |
| `fontFamily` | string | New font family |
| `fontWeight` | number | New font weight |
| `textColor` | string | New text color |
| `layout` | object | Layout updates |

### Examples

```javascript
// Inside figma_execute:

// Change fill color
await figma.modify({ target: "selection", fill: "#FF0000" });

// Target by name
await figma.modify({ target: "name:Hero Section", fill: "#0066FF" });

// Resize and move
await figma.modify({ target: "123:456", width: 200, height: 100, x: 50, y: 50 });

// Change text
await figma.modify({ target: "selection", content: "New Text", fontSize: 18 });

// Toggle visibility
await figma.modify({ target: "selection", visible: false });

// Change opacity
await figma.modify({ target: "selection", opacity: 0.5 });

// Update layout
await figma.modify({ target: "selection", layout: { gap: 24, padding: 16 } });

// Batch modify multiple elements
const { nodes } = await figma.query({ target: "selection" });
for (const node of nodes) {
  await figma.modify({ target: node.id, fill: "#0066FF" });
}
console.log(`Modified ${nodes.length} elements`);
```

---

## figma.delete()

Delete elements.

```javascript
// Inside figma_execute:
await figma.delete({ target: "selection" });
await figma.delete({ target: "123:456" });
await figma.delete({ target: "name:OldElement" });
```

---

## figma.append()

Move element(s) into a container frame.

```javascript
// Inside figma_execute:

// Move selection into a frame by name
await figma.append({ target: "selection", parent: "name:Hero Section" });

// Move specific element into another
await figma.append({ target: "name:Title", parent: "name:Card" });

// Move by ID
await figma.append({ target: "123:456", parent: "789:012" });
```

```

### rules/effects.md

```markdown
---
name: effects
description: Shadows, blur, and visual effects for Figma elements
metadata:
  tags: effects, shadow, blur, drop-shadow, inner-shadow
---

## Effects (Shadows & Blur)

Add visual effects like shadows and blur to elements using the `effects` parameter.

### Effect Types

| Type | Description | Properties |
|------|-------------|------------|
| `DROP_SHADOW` | Shadow outside the element | color, offset, radius, spread |
| `INNER_SHADOW` | Shadow inside the element | color, offset, radius, spread |
| `LAYER_BLUR` | Blur the element itself | radius |
| `BACKGROUND_BLUR` | Blur content behind element | radius |

### Examples

```javascript
// Inside figma_execute:

// Drop shadow
await figma.create({
  type: "card",
  name: "Elevated Card",
  width: 320,
  fill: "#FFFFFF",
  cornerRadius: 16,
  effects: [
    {
      type: "DROP_SHADOW",
      color: "#00000040",  // 25% opacity black
      offset: { x: 0, y: 4 },
      radius: 12,
      spread: 0
    }
  ],
  children: [
    { type: "text", content: "Card with shadow", fontSize: 16 }
  ]
});

// Multiple shadows (layered)
await figma.create({
  type: "frame",
  name: "Multi-Shadow",
  width: 200,
  height: 100,
  fill: "#FFFFFF",
  cornerRadius: 8,
  effects: [
    { type: "DROP_SHADOW", color: "#0000001A", offset: { x: 0, y: 1 }, radius: 3 },
    { type: "DROP_SHADOW", color: "#0000000F", offset: { x: 0, y: 4 }, radius: 6 },
    { type: "DROP_SHADOW", color: "#0000000A", offset: { x: 0, y: 10 }, radius: 15 }
  ]
});

// Inner shadow
await figma.create({
  type: "rect",
  name: "Inset",
  width: 100,
  height: 100,
  fill: "#F0F0F0",
  effects: [
    { type: "INNER_SHADOW", color: "#00000020", offset: { x: 0, y: 2 }, radius: 4 }
  ]
});

// Layer blur
await figma.create({
  type: "rect",
  name: "Blurred",
  width: 200,
  height: 200,
  fill: "#0066FF80",
  effects: [
    { type: "LAYER_BLUR", radius: 20 }
  ]
});

// Background blur (glass effect)
await figma.create({
  type: "frame",
  name: "Glass Panel",
  width: 300,
  height: 150,
  fill: "#FFFFFF40",
  cornerRadius: 20,
  effects: [
    { type: "BACKGROUND_BLUR", radius: 40 }
  ]
});
```

```

### rules/gradients.md

```markdown
---
name: gradients
description: Gradient fills for Figma elements - linear, radial, angular, diamond
metadata:
  tags: gradient, linear, radial, angular, fill
---

## Gradient Fills

Create gradient fills instead of solid colors using the `gradient` parameter.

### Gradient Types

| Type | Description |
|------|-------------|
| `LINEAR` | Straight line gradient, use `angle` to control direction |
| `RADIAL` | Circular gradient from center outward |
| `ANGULAR` | Gradient that sweeps around center (conic) |
| `DIAMOND` | Diamond-shaped gradient from center |

### Examples

```javascript
// Inside figma_execute:

// Linear gradient (left to right)
await figma.create({
  type: "frame",
  name: "Gradient Banner",
  width: 800,
  height: 200,
  gradient: {
    type: "LINEAR",
    angle: 0,  // 0 = left-to-right, 90 = top-to-bottom
    stops: [
      { position: 0, color: "#667EEA" },
      { position: 1, color: "#764BA2" }
    ]
  }
});

// Diagonal gradient
await figma.create({
  type: "rect",
  name: "Diagonal Gradient",
  width: 200,
  height: 200,
  gradient: {
    type: "LINEAR",
    angle: 45,
    stops: [
      { position: 0, color: "#FF6B6B" },
      { position: 0.5, color: "#FFE66D" },
      { position: 1, color: "#4ECDC4" }
    ]
  }
});

// Radial gradient
await figma.create({
  type: "ellipse",
  name: "Radial Glow",
  width: 200,
  height: 200,
  gradient: {
    type: "RADIAL",
    stops: [
      { position: 0, color: "#FFFFFF" },
      { position: 1, color: "#0066FF" }
    ]
  }
});

// Angular gradient (conic)
await figma.create({
  type: "ellipse",
  name: "Color Wheel",
  width: 200,
  height: 200,
  gradient: {
    type: "ANGULAR",
    stops: [
      { position: 0, color: "#FF0000" },
      { position: 0.17, color: "#FFFF00" },
      { position: 0.33, color: "#00FF00" },
      { position: 0.5, color: "#00FFFF" },
      { position: 0.67, color: "#0000FF" },
      { position: 0.83, color: "#FF00FF" },
      { position: 1, color: "#FF0000" }
    ]
  }
});
```

```

### rules/corner-radius.md

```markdown
---
name: corner-radius
description: Independent corner radius for Figma elements
metadata:
  tags: corner, radius, rounded, border-radius
---

## Independent Corner Radius

Set different radius for each corner using individual properties.

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `cornerRadius` | number | Uniform corner radius |
| `topLeftRadius` | number | Top-left corner radius |
| `topRightRadius` | number | Top-right corner radius |
| `bottomLeftRadius` | number | Bottom-left corner radius |
| `bottomRightRadius` | number | Bottom-right corner radius |

### Examples

```javascript
// Inside figma_execute:

// Speech bubble style
await figma.create({
  type: "frame",
  name: "Speech Bubble",
  width: 200,
  height: 80,
  fill: "#E8E8E8",
  topLeftRadius: 16,
  topRightRadius: 16,
  bottomLeftRadius: 4,
  bottomRightRadius: 16
});

// Tab shape
await figma.create({
  type: "rect",
  name: "Tab",
  width: 120,
  height: 40,
  fill: "#FFFFFF",
  topLeftRadius: 8,
  topRightRadius: 8,
  bottomLeftRadius: 0,
  bottomRightRadius: 0
});

// Notch style
await figma.create({
  type: "frame",
  name: "Notched Card",
  width: 300,
  height: 200,
  fill: "#FFFFFF",
  topLeftRadius: 24,
  topRightRadius: 4,
  bottomLeftRadius: 4,
  bottomRightRadius: 24
});
```

```

### rules/strokes.md

```markdown
---
name: strokes
description: Stroke styling for Figma elements - dash patterns, caps, alignment
metadata:
  tags: stroke, border, dashed, dotted, arrow
---

## Stroke Styling

Advanced stroke options for lines and shapes.

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `stroke` | string | Stroke color (hex) |
| `strokeWidth` | number | Stroke width in pixels |
| `strokeAlign` | string | "INSIDE", "OUTSIDE", "CENTER" |
| `strokeCap` | string | "NONE", "ROUND", "SQUARE", "ARROW_LINES", "ARROW_EQUILATERAL" |
| `strokeJoin` | string | "MITER", "BEVEL", "ROUND" (for corners) |
| `dashPattern` | number[] | Dash pattern, e.g., [5, 5] for dashed line |

### Examples

```javascript
// Inside figma_execute:

// Dashed border
await figma.create({
  type: "rect",
  name: "Dashed Box",
  width: 200,
  height: 100,
  fill: "#FFFFFF",
  stroke: "#666666",
  strokeWidth: 2,
  dashPattern: [8, 4],  // 8px dash, 4px gap
  cornerRadius: 8
});

// Dotted line
await figma.create({
  type: "line",
  name: "Dotted Divider",
  width: 300,
  stroke: "#CCCCCC",
  strokeWidth: 2,
  dashPattern: [2, 4],
  strokeCap: "ROUND"
});

// Arrow line
await figma.create({
  type: "line",
  name: "Arrow",
  width: 150,
  stroke: "#333333",
  strokeWidth: 2,
  strokeCap: "ARROW_EQUILATERAL"
});

// Inside stroke
await figma.create({
  type: "rect",
  name: "Inside Border",
  width: 100,
  height: 100,
  fill: "#FFFFFF",
  stroke: "#0066FF",
  strokeWidth: 4,
  strokeAlign: "INSIDE",
  cornerRadius: 8
});
```

```

### rules/transforms.md

```markdown
---
name: transforms
description: Rotation and blend modes for Figma elements
metadata:
  tags: rotation, transform, blend-mode
---

## Transform Properties

Apply rotation and blend modes to elements.

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `rotation` | number | Rotation angle in degrees |
| `blendMode` | string | Blend mode for compositing |

### Blend Modes

`PASS_THROUGH`, `NORMAL`, `DARKEN`, `MULTIPLY`, `LINEAR_BURN`, `COLOR_BURN`, `LIGHTEN`, `SCREEN`, `LINEAR_DODGE`, `COLOR_DODGE`, `OVERLAY`, `SOFT_LIGHT`, `HARD_LIGHT`, `DIFFERENCE`, `EXCLUSION`, `HUE`, `SATURATION`, `COLOR`, `LUMINOSITY`

### Examples

```javascript
// Inside figma_execute:

// Rotated element
await figma.create({
  type: "rect",
  name: "Diamond",
  width: 100,
  height: 100,
  fill: "#FF6B6B",
  rotation: 45,
  x: 100,
  y: 100
});

// Blend mode overlay
await figma.create({
  type: "frame",
  name: "Overlay Container",
  width: 400,
  height: 300,
  fill: "#000000",
  children: [
    {
      type: "rect",
      name: "Background Image",
      width: 400,
      height: 300,
      fill: "#336699"
    },
    {
      type: "rect",
      name: "Color Overlay",
      width: 400,
      height: 300,
      fill: "#FF6B6B",
      blendMode: "MULTIPLY"
    }
  ]
});
```

```

### rules/constraints.md

```markdown
---
name: constraints
description: Responsive constraints and min/max sizes for Figma elements
metadata:
  tags: constraints, responsive, min-width, max-width
---

## Responsive Constraints

Set constraints for responsive behavior.

### Constraint Values

| Value | Behavior |
|-------|----------|
| `MIN` | Anchor to left/top |
| `CENTER` | Stay centered |
| `MAX` | Anchor to right/bottom |
| `STRETCH` | Stretch with container |
| `SCALE` | Scale proportionally |

### Examples

```javascript
// Inside figma_execute:

// Element that stretches horizontally
await figma.create({
  type: "frame",
  name: "Header",
  width: 1440,
  height: 60,
  fill: "#FFFFFF",
  constraints: {
    horizontal: "STRETCH",
    vertical: "MIN"
  }
});

// Centered element
await figma.create({
  type: "frame",
  name: "Modal",
  width: 400,
  height: 300,
  fill: "#FFFFFF",
  cornerRadius: 16,
  constraints: {
    horizontal: "CENTER",
    vertical: "CENTER"
  }
});

// Bottom-right anchored
await figma.create({
  type: "button",
  name: "FAB",
  constraints: {
    horizontal: "MAX",
    vertical: "MAX"
  }
});
```

## Min/Max Size Constraints

Set size limits for responsive elements.

| Parameter | Type | Description |
|-----------|------|-------------|
| `minWidth` | number | Minimum width constraint |
| `minHeight` | number | Minimum height constraint |
| `maxWidth` | number | Maximum width constraint |
| `maxHeight` | number | Maximum height constraint |

```javascript
// Inside figma_execute:

// Card with min/max width
await figma.create({
  type: "card",
  name: "Responsive Card",
  width: 320,
  minWidth: 280,
  maxWidth: 480,
  layout: { direction: "column", padding: 24, gap: 16 },
  children: [
    { type: "text", content: "Flexible Card", fontSize: 20, fontWeight: 600 }
  ]
});

// Text container with max height
await figma.create({
  type: "frame",
  name: "Scrollable Content",
  width: 300,
  minHeight: 100,
  maxHeight: 400,
  fill: "#FFFFFF",
  clipsContent: true,
  layout: { direction: "column", padding: 16, gap: 8 }
});
```

```

### rules/text.md

```markdown
---
name: text
description: Text elements, wrapping, and sizing in Figma
metadata:
  tags: text, font, wrapping, typography, fontFamily
---

## Text Elements

Create and configure text elements.

### Text Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `content` | string | Text content |
| `fontSize` | number | Font size in pixels |
| `fontWeight` | number | Font weight (100-900) |
| `fontFamily` | string | Font family name (e.g., "Inter", "Roboto", "Arial") |
| `textAlign` | string | Horizontal alignment: "LEFT", "CENTER", "RIGHT", "JUSTIFIED" |
| `textColor` | string | Text color (hex). Preferred over `fill` |
| `textAutoResize` | string | "WIDTH_AND_HEIGHT", "HEIGHT", "TRUNCATE", "NONE" |
| `maxWidth` | number | Max width for text wrapping |
| `lineHeight` | number | Line height in pixels |
| `letterSpacing` | number | Letter spacing in pixels |
| `textDecoration` | string | "NONE", "UNDERLINE", "STRIKETHROUGH" |
| `textCase` | string | "ORIGINAL", "UPPER", "LOWER", "TITLE" |

### Font Weight to Style Mapping

| Weight | Style |
|--------|-------|
| 100 | Thin |
| 200 | Extra Light |
| 300 | Light |
| 400 | Regular |
| 500 | Medium |
| 600 | Semi Bold |
| 700 | Bold |
| 800 | Extra Bold |
| 900 | Black |

## Text Wrapping and Sizing

```javascript
// Inside figma_execute:

// Text with custom font
await figma.create({
  type: "text",
  content: "Custom Font Text",
  fontFamily: "Roboto",
  fontWeight: 700,
  fontSize: 24
});

// Text that wraps within a max width
await figma.create({
  type: "text",
  content: "This is a long paragraph that will wrap to multiple lines.",
  maxWidth: 300,  // Automatically enables text wrapping
  lineHeight: 24
});

// Centered text
await figma.create({
  type: "text",
  content: "Centered Heading",
  textAlign: "CENTER",
  fontSize: 32,
  fontWeight: 700
});

// Text with explicit color (white text on dark background)
await figma.create({
  type: "frame",
  fill: "#333333",
  layout: { direction: "row", padding: 16 },
  children: [
    { type: "text", content: "Button", textColor: "#FFFFFF", fontWeight: 600 }
  ]
});

// Child element that fills parent width
await figma.create({
  type: "frame",
  width: 400,
  layout: { direction: "column", gap: 16 },
  children: [
    {
      type: "text",
      content: "Full width text",
      layoutSizingHorizontal: "FILL"  // Stretches to parent width
    }
  ]
});
```

```

### rules/fonts.md

```markdown
---
name: fonts
description: Loading and using custom fonts in Figma with figma-pilot
metadata:
  tags: font, fontFamily, typography, text
---

## Using Fonts

figma-pilot supports custom fonts through the `fontFamily` and `fontWeight` parameters.

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `fontFamily` | string | Font family name (e.g., "Inter", "Roboto", "Arial") |
| `fontWeight` | number | Font weight from 100 to 900 |

### Font Weight to Style Mapping

| Weight | Style Name |
|--------|------------|
| 100 | Thin |
| 200 | Extra Light |
| 300 | Light |
| 400 | Regular |
| 500 | Medium |
| 600 | Semi Bold |
| 700 | Bold |
| 800 | Extra Bold |
| 900 | Black |

### Examples

```javascript
// Inside figma_execute:

// Default Inter font
await figma.create({
  type: "text",
  content: "Default Inter Text",
  fontSize: 16
});

// Using Roboto Bold
await figma.create({
  type: "text",
  content: "Roboto Bold",
  fontFamily: "Roboto",
  fontWeight: 700,
  fontSize: 24
});

// Using system fonts
await figma.create({
  type: "text",
  content: "System Font",
  fontFamily: "Arial",
  fontWeight: 400,
  fontSize: 16
});

// Light weight text
await figma.create({
  type: "text",
  content: "Light Text",
  fontFamily: "Inter",
  fontWeight: 300,
  fontSize: 18
});

// Multiple text styles in a card
await figma.create({
  type: "card",
  name: "Typography Demo",
  width: 300,
  children: [
    { type: "text", content: "Heading", fontFamily: "Inter", fontWeight: 700, fontSize: 24 },
    { type: "text", content: "Subheading", fontFamily: "Inter", fontWeight: 500, fontSize: 16 },
    { type: "text", content: "Body text goes here", fontFamily: "Inter", fontWeight: 400, fontSize: 14, fill: "#666666" }
  ]
});
```

### Font Fallback

If the specified font is not available, figma-pilot will fall back to Inter Regular. Common fonts that typically work:

- **System fonts**: Arial, Helvetica, Times New Roman, Georgia
- **Google fonts** (if installed in Figma): Roboto, Open Sans, Lato, Montserrat, Poppins
- **Figma default**: Inter (always available)

### Tips

- Use `fontWeight` to specify the exact weight - figma-pilot maps it to the appropriate font style
- The default font is "Inter" if no `fontFamily` is specified
- The default weight is 400 (Regular) if no `fontWeight` is specified
- For titles, use `fontWeight: 700` (Bold) or `fontWeight: 600` (Semi Bold)
- For body text, use `fontWeight: 400` (Regular)
- For captions or subtle text, use `fontWeight: 300` (Light)

```

### rules/components.md

```markdown
---
name: components
description: Create, list, and manage Figma components - convert, variants, instances
metadata:
  tags: component, variants, instance, reusable
---

## figma.listComponents()

List all available components in the Figma file.

```javascript
// Inside figma_execute:
const { components } = await figma.listComponents();
const { components } = await figma.listComponents({ filter: "Button" });  // Filter by name
console.log(`Found ${components.length} components`);
```

Use this to discover existing components before creating instances.

---

## figma.toComponent()

Convert an element to a reusable component.

```javascript
// Inside figma_execute:
await figma.toComponent({ target: "selection" });
await figma.toComponent({ target: "selection", name: "Button/Primary" });
```

Use `/` in the name to create component hierarchies (e.g., "Button/Primary", "Button/Secondary").

---

## figma.createVariants()

Create component variants with different property values.

```javascript
// Inside figma_execute:

// Create state variants
await figma.createVariants({
  target: "selection",
  property: "state",
  values: ["default", "hover", "pressed", "disabled"]
});

// Create size variants
await figma.createVariants({
  target: "123:456",
  property: "size",
  values: ["small", "medium", "large"]
});
```

This creates multiple variants of the component with the specified property values.

---

## figma.instantiate()

Create an instance of a component.

```javascript
// Inside figma_execute:
await figma.instantiate({ component: "123:456" });
await figma.instantiate({ component: "123:456", x: 100, y: 200 });
await figma.instantiate({ component: "name:Button/Primary", parent: "name:Card" });
```

Use `figma.listComponents()` first to discover available components and their IDs or names.

---

## Component Workflow Example

```javascript
// Inside figma_execute - complete component workflow:

// 1. Create a button design
await figma.create({
  type: "button",
  name: "Button",
  children: [
    { type: "text", content: "Click Me", textColor: "#FFFFFF" }
  ]
});

// 2. Convert to component
await figma.toComponent({ target: "selection", name: "Button/Primary" });

// 3. Create variants
await figma.createVariants({ 
  target: "selection", 
  property: "state", 
  values: ["default", "hover", "pressed"] 
});

// 4. List components to verify
const { components } = await figma.listComponents({ filter: "Button" });
console.log(`Created ${components.length} button components`);

// 5. Create instances
await figma.instantiate({ component: "name:Button/Primary", x: 100, y: 100 });
```

```

### rules/accessibility.md

```markdown
---
name: accessibility
description: WCAG compliance checking and auto-fixing for Figma designs
metadata:
  tags: accessibility, wcag, a11y, contrast
---

## figma.accessibility()

Unified accessibility tool - check and optionally fix accessibility issues.

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `target` | string | Element to check (required): ID, "selection", "page", or "name:ElementName" |
| `level` | string | WCAG conformance level: "AA" or "AAA" (default: "AA") |
| `autoFix` | boolean | Automatically fix issues where possible (default: false) |
| `output` | string | Output format: "json" or "text" (default: "json") |

### Checks Performed

- **Text contrast**: Ensures text meets WCAG contrast requirements
- **Touch targets**: Ensures interactive elements are at least 44x44px

### Examples

```javascript
// Inside figma_execute:

// Audit current selection (read-only check)
const result = await figma.accessibility({ target: "selection" });

// Audit with AAA level
await figma.accessibility({ target: "selection", level: "AAA" });

// Audit and auto-fix issues
const fixed = await figma.accessibility({ target: "selection", level: "AA", autoFix: true });
console.log(`Fixed ${fixed.fixedCount} of ${fixed.totalIssues} issues`);

// Audit entire page with text output
await figma.accessibility({ target: "page", output: "text" });
```

### Response

```javascript
{
  issues: AccessibilityIssue[],
  totalIssues: number,
  fixedCount: number,    // Number fixed (if autoFix was true)
  passed: number,
  failed: number,
  warnings: number
}
```

## Accessibility Workflow

```javascript
// Inside figma_execute - complete accessibility workflow:

// 1. Audit the page
const audit = await figma.accessibility({ target: "page", level: "AA" });
console.log(`Found ${audit.totalIssues} issues`);

// 2. Fix issues automatically
const fixed = await figma.accessibility({ target: "page", level: "AA", autoFix: true });
console.log(`Fixed ${fixed.fixedCount} issues`);

// 3. Verify fixes
const verify = await figma.accessibility({ target: "page", level: "AA" });
console.log(`Remaining issues: ${verify.totalIssues}`);
```

```

### rules/tokens.md

```markdown
---
name: tokens
description: Create, bind, and sync design tokens in Figma
metadata:
  tags: tokens, design-tokens, variables, styles
---

## Design Tokens

### figma.bindToken()

Bind a design token to a node property.

```javascript
// Inside figma_execute:
await figma.bindToken({ target: "selection", property: "fill", token: "colors/primary" });
await figma.bindToken({ target: "name:Button", property: "cornerRadius", token: "radii/sm" });
```

### figma.createToken()

Create a new design token.

```javascript
// Inside figma_execute:
await figma.createToken({
  collection: "colors",
  name: "primary",
  type: "COLOR",
  value: "#2563EB"
});
```

### figma.syncTokens()

Import or export token JSON.

```javascript
// Inside figma_execute:

// Import tokens
await figma.syncTokens({ from: "/path/to/tokens.json" });

// Export tokens
await figma.syncTokens({ to: "/path/to/tokens.json" });
```

Use tokens for consistency in design systems. Create tokens for colors, spacing, radii, and other reusable values.

```

### rules/export.md

```markdown
---
name: export
description: Export Figma elements as PNG, SVG, PDF, or JPG
metadata:
  tags: export, png, svg, pdf, image
---

## figma.export()

Export elements as images.

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `target` | string | Element to export (required) |
| `format` | string | Export format: "png", "svg", "pdf", "jpg" (required) |
| `scale` | number | Scale factor (default: 1) |

### Examples

```javascript
// Inside figma_execute:

// Export selection as PNG
await figma.export({ target: "selection", format: "png" });

// Export as SVG
await figma.export({ target: "selection", format: "svg" });

// Export at 2x scale
const result = await figma.export({ target: "selection", format: "png", scale: 2 });
console.log(`Exported ${result.size} bytes`);
```

**Tip**: After finishing a requested change (not every step), export a PNG for review.

```

### rules/patterns.md

```markdown
---
name: patterns
description: Common design patterns - cards, navigation, page layouts
metadata:
  tags: patterns, card, navigation, layout, page
---

## Card Component

```javascript
// Inside figma_execute:

// 1. Create the card layout
await figma.create({
  type: "card",
  name: "Card",
  width: 320,
  children: [
    { type: "text", name: "Title", content: "Card Title", fontSize: 18, fontWeight: 600 },
    { type: "text", name: "Description", content: "Card description goes here", fontSize: 14, fill: "#666666" }
  ]
});

// 2. Convert to component
await figma.toComponent({ target: "selection", name: "Card/Default" });

// 3. Create variants
await figma.createVariants({ target: "selection", property: "state", values: ["default", "hover"] });
```

**Key Points:**
- Use the `card` semantic type for pre-styled card layouts
- Convert to component for reusability
- Create variants for different states (default, hover, etc.)

---

## Navigation Bar

```javascript
// Inside figma_execute:
await figma.create({
  type: "nav",
  name: "Navigation",
  width: 1200,
  children: [
    { type: "text", content: "Logo", fontSize: 20, fontWeight: 700 },
    {
      type: "frame",
      layout: { direction: "row", gap: 24 },
      children: [
        { type: "text", content: "Home", fontSize: 14 },
        { type: "text", content: "About", fontSize: 14 },
        { type: "text", content: "Contact", fontSize: 14 }
      ]
    },
    {
      type: "button",
      name: "CTA",
      children: [{ type: "text", content: "Sign Up", fill: "#FFFFFF" }]
    }
  ]
});
```

**Key Points:**
- Use the `nav` semantic type for pre-styled navigation layouts
- Group menu items in a frame with row layout
- Include a CTA button for conversion

---

## Page Layout with Sections

When creating multiple sections for a page, always specify position to stack them vertically:

```javascript
// Inside figma_execute:

// Navigation at top (y=0)
await figma.create({
  type: "frame", name: "Nav", width: 1440, height: 80,
  x: 0, y: 0, fill: "#FFFFFF"
});

// Hero section below nav (y=80)
await figma.create({
  type: "frame", name: "Hero", width: 1440, height: 600,
  x: 0, y: 80, fill: "#F5F5F5"
});

// Features section (y=680)
await figma.create({
  type: "frame", name: "Features", width: 1440, height: 400,
  x: 0, y: 680, fill: "#FFFFFF"
});

// Footer (y=1080)
await figma.create({
  type: "frame", name: "Footer", width: 1440, height: 200,
  x: 0, y: 1080, fill: "#333333"
});
```

**Key Points:**
- Always specify `x` and `y` to avoid element overlap
- Use consistent widths for page sections
- Name each section for easy targeting later

```