efecto-web-design

What this skill does

# Efecto — Design Web Pages with AI

Efecto is a real-time web design tool that AI agents control programmatically. You create a **session**, the user opens a URL in their browser, and you push design commands that render instantly. Every node maps to a real HTML element styled with Tailwind CSS — web-native, semantic, and pixel-accurate.

---

## Setup

This skill requires the **Efecto MCP server**. Check if it's available by looking for tools like `create_session`, `add_section`, or `get_document` in your tool list.

**If Efecto tools are NOT available, install the MCP server:**

### Claude Code
```bash
claude mcp add efecto -- npx -y @efectoapp/mcp
```

### Cursor
Add to `.cursor/mcp.json`:
```json
{
  "mcpServers": {
    "efecto": {
      "command": "npx",
      "args": ["-y", "@efectoapp/mcp"]
    }
  }
}
```

### Windsurf / VS Code / Other MCP Clients
```json
{
  "mcpServers": {
    "efecto": {
      "command": "npx",
      "args": ["-y", "@efectoapp/mcp"]
    }
  }
}
```

Once installed, you'll have access to 68 MCP tools, including image search and native animation authoring. The MCP server connects your agent to the Efecto design canvas at [efecto.app](https://efecto.app).

---

## How Sessions Work

```
Agent ──POST /execute──> Server ──SSE──> Browser (renders live)
Agent <──poll/response── Server <──POST── Browser (returns results)
```

1. You create a session via the MCP server or REST API
2. The user opens the returned Efecto URL in their browser
3. You push tool calls — each one executes in the browser and returns a result
4. The user sees every change live as you build the design

Sessions expire after 2 hours of inactivity. The browser must be connected before tool calls can execute. If you restart or lose the MCP process, call `attach_session` with the user's current Efecto URL instead of creating a duplicate session.

---

## Quick Start — Build a Page in 7 Steps

### Step 1: Create a Session
```
create_session
  label: "Landing page design"
```
Returns `{ sessionId, documentId, designUrl }`. Tell the user to open the URL. The session ID is stored automatically — all subsequent tools use it.

If the user already has an Efecto URL with `?session=...`, resume it:
```
attach_session
  designUrl: "https://efecto.app/design/<file-id>/untitled?session=<session-id>"
```

**Do not call `create_session` again to "reconnect".** Use `attach_session` for an existing URL. A second `create_session` call refuses to overwrite a paired session unless you pass `force: true`.

### Step 2: Wait for Browser Connection
```
wait_for_connection
```
Blocks until the browser opens the URL and pairs (default 120s). Returns immediately if already paired.

To inspect routing state at any time:
```
session_status                # legacy single-session shape (sessionId, paired, browserConnected, knownSessions)
session_status { all: true }  # list shape — all sessions in this MCP process with isActive / paired flags
```

### Step 3: Create an Artboard
```
create_artboard
  name: "Homepage"
  width: 1440
  height: 900
  backgroundColor: "#ffffff"
  className: "flex flex-col"
```
Returns the artboard ID. **Always set className to "flex flex-col"** so children stack vertically.

### Step 4: Add Sections with JSX
```
add_section
  parentId: "<artboard-id>"
  jsx: '<nav className="flex items-center justify-between px-16 py-5 bg-white w-full">
    <h2 className="text-xl font-bold text-gray-900">Acme</h2>
    <div className="flex items-center gap-8">
      <a className="text-sm text-gray-600" href="#">Features</a>
      <a className="text-sm text-gray-600" href="#">Pricing</a>
      <button className="px-4 py-2 text-sm font-medium text-white bg-gray-900 rounded-lg">Get Started</button>
    </div>
  </nav>'
```
This is the most efficient way to build complex layouts — one JSX string per section.

### Step 5: Read Current State
```
get_document
```
Returns JSX-like markup with `data-id` attributes on every node. Use these IDs for updates.

### Step 6: Fine-Tune with Updates
```
batch_update
  updates: [
    { nodeId: "abc", className: "text-2xl font-extrabold text-gray-900" },
    { nodeId: "def", textContent: "Updated heading text" }
  ]
```

### Step 7: Iterate
Repeat Steps 4-6 to add more sections, adjust styling, and refine the design. The user sees every change in real time.

---

## The Design Tools

### Reading State

| Tool | Purpose |
|------|---------|
| `get_selection` | Returns currently selected nodes/artboards with JSX subtrees |
| `get_document` | Returns document as JSX. Scoped modes (preferred on large docs): `outline: true` (one-line summary per top-level child), `artboardId` (single artboard), `maxDepth` (cap descent; 0 = artboard header only, 1 = top-level children only). Response includes an approx-token count. |
| `list_artboards` | Lists all artboards with IDs, names, dimensions |
| `find_nodes` | Search nodes by name, text content, type, or className. Returns IDs without subtree — use this to locate before calling `get_node_tree`. |
| `get_node_tree` | Serializes one node/artboard subtree only — drill in after `outline` or `find_nodes`. |

### Creating Content

| Tool | Purpose |
|------|---------|
| `create_artboard` | Creates a new artboard (screen/frame) |
| `add_section` | Adds complex layouts from JSX markup (preferred) |
| `add_node` | Adds a single node to a parent |

### Modifying Content

| Tool | Purpose |
|------|---------|
| `update_node` | Updates any node property (className, textContent, tag, style, src, link, elementId, etc.) |
| `update_class` | Shortcut: replaces only className on a node |
| `update_artboard` | Updates artboard properties (name, size, background, className, `timelineDuration`) |
| `batch_update` | Updates multiple nodes in one call (bulk styling) |
| `replace_section` | Replaces a node and its children with new JSX |

### Animation

| Tool | Purpose |
|------|---------|
| `list_animation_presets` | Lists native Efecto animation presets with ids, categories, defaults, and supported controls |
| `apply_animation_plan` | Applies a validated multi-layer animation plan in one call |
| `clear_animations` | Clears native animations from nodes, the selection, an artboard, or the whole document |

### Organizing Structure

| Tool | Purpose |
|------|---------|
| `move_node` | Reparents or reorders a node |
| `duplicate_node` | Deep-clones a node with fresh IDs |
| `duplicate_artboard` | Deep-clones an artboard for variations |
| `group_nodes` | Wraps selected nodes in a frame container |
| `ungroup_node` | Unwraps a group, moving children to parent |
| `reorder_node` | Brings to front or sends to back (z-order) |

### Display & Selection

| Tool | Purpose |
|------|---------|
| `select_nodes` | Highlights nodes for the user to see |
| `set_visibility` | Shows/hides nodes (like Figma eye icon) |
| `delete_nodes` | Deletes nodes and their children |
| `delete_artboard` | Deletes an artboard and all contents |

### Alignment & Distribution

| Tool | Purpose |
|------|---------|
| `align_nodes` | Aligns multiple nodes (left/center/right/top/middle/bottom) |
| `distribute_nodes` | Distributes nodes evenly (horizontal/vertical) |

### History

| Tool | Purpose |
|------|---------|
| `undo` | Undoes the last action (Cmd+Z) |
| `redo` | Redoes the last undone action (Cmd+Shift+Z) |

### Viewport & Document

| Tool | Purpose |
|------|---------|
| `zoom_to_artboard` | Zooms viewport to show a specific artboard |
| `zoom_to_fit` | Zooms to fit all artboards in the viewport |
| `set_viewport` | Sets viewport zoom level and/or pan position |
| `rename_document` | Renames the document |
| `new_document` | Creates a new blank document (replaces current) |

### Canvas & Reading

| Tool | Purpose |
|------|---------|
| `move_artboard` | Repositions an artboard on the canvas for multi-screen flows |
| `deselect_all` | Clears the current node selection |
| `get_node_tree` | Returns JSX for one node/artboard subtree (faster than full docum