pablostanley/efecto-plugin/web-design

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

claude mcp add efecto -- npx -y @efectoapp/mcp

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "efecto": {
      "command": "npx",
      "args": ["-y", "@efectoapp/mcp"]
    }
  }
}

Windsurf / VS Code / Other MCP Clients

{
  "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.

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 name="Primary Navigation" className="flex items-center justify-between px-16 py-5 bg-white w-full">
    <h2 name="Brand Name" className="text-xl font-bold text-gray-900">Acme</h2>
    <div name="Navigation Links" className="flex items-center gap-8">
      <a name="Features Link" className="text-sm text-gray-600" href="#">Features</a>
      <a name="Pricing Link" className="text-sm text-gray-600" href="#">Pricing</a>
      <button name="Get Started 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

Creating Content

Modifying Content

Animation

Organizing Structure

Display & Selection

Alignment & Distribution

History

Viewport & Document

Canvas & Reading

Fill & Export

Theme

Design Validation

Image Search

Native Animation — Animate Existing Designs

Efecto has a native layer animation system. Do not use Tailwind animate-*, transition-*, or duration-* classes as the animation authoring path.

Workflow for "animate this":

1. Inspect the target with get_selection, get_document, get_node_tree, or list_artboards.
2. Call list_animation_presets to see supported preset IDs and settings.
3. Pick the meaningful layers: hero image, headline, supporting copy, CTA, cards, icons, or product visuals. Avoid animating every nested child.
4. Call apply_animation_plan with timed entries. Use mode: "replace" for a new motion system or mode: "append" to add exit/outro animations.
5. Set timelineDuration with update_artboard when the artboard needs a deliberate playback end.
6. Use select_nodes to highlight the changed layers.

Timing defaults:

• Small UI elements: 0.18-0.35s.
• Hero/slide elements: 0.35-0.6s.
• Sibling stagger: 0.04-0.12s.
• Entrances: ease-out.
• Exits: ease-in.

Preset guidance:

• fade-in: subtle supporting content.
• slide-in: directional reveals, usually 16-48px.
• scale-in: cards, product shots, badges, modals.
• blur-in: cinematic/editorial reveals.
• tilt-in, spin-in, bounce-in, pop-spark: playful or promotional moments.
• mask-in, fade-mask-in, slide-mask-in, scale-mask-in: high-impact hero, frame, or title reveals. Use maskStyle: "linear" for clean wipes, "diagonal" for editorial energy, and "iris" for spotlit reveals. Use maskDirection for edge movement and maskOrigin for iris origin.
• mask-reveal, iris-reveal: legacy combo aliases that still work, but prefer the explicit mask presets above.
• Exit presets (fade-out, slide-out, scale-out, etc.) should leave enough reading time before they begin.

Text nodes can use appearBy: "word" or "line" for headline reveals. Use "char" only for kinetic title moments; non-text nodes must use "block".

Example: