Tool Reference

Create a new session. Returns a URL the user opens in their browser. Once connected, all design tools execute in real-time. Only one session is active at a time.

// Create a session
create_session({ label: "Landing page design" })
// → Returns { designUrl: "https://efecto.app/design?session=abc123" }

Blocks until the browser opens the design URL and pairs with the session. Call after create_session to ensure the browser is ready before executing tools.

Check if the browser is connected, pending calls, etc.

Close the active session. Disconnects the browser and cleans up.

Returns the full document as JSX-like markup. Each element has a data-id for referencing in other tools. Always call this before modifying an existing design.

Returns the currently selected nodes with serialized JSX subtrees. Use to understand user context before making edits.

Lists all artboards with IDs, names, dimensions, and positions.

Search for nodes by name, text content, type, tag, className, exact class, or inline style.

Returns JSX for a specific node or artboard subtree (faster than get_document for one section).

Creates a new artboard. Set className to "flex flex-col" for vertical layout.

create_artboard({
  name: "Desktop",
  width: 1440,
  height: 900,
  className: "flex flex-col",
  backgroundColor: "#ffffff"
})

Adds a complete section from JSX-like markup. Most efficient for complex layouts.

add_section({
  parentId: "artboard-1",
  jsx: `<section className="flex flex-col items-center justify-center py-24 px-8 bg-black text-white">
  <h1 className="text-6xl font-bold tracking-tight mb-4">Build faster</h1>
  <p className="text-xl text-gray-400 max-w-2xl text-center">Ship beautiful products with AI-powered design.</p>
  <div className="flex items-center gap-2 mt-8 px-8 py-3 bg-white text-black rounded-full font-medium">
    <span>Get Started</span>
    <svg icon="arrow-right" className="w-4 h-4" />
  </div>
</section>`
})

// Icons: use <svg icon="name" className="w-5 h-5" />
// Common: arrow-right, heart, check, star, envelope, user, gear
// Libraries: phosphor (default), lucide, heroicons, radix
// Weights: <svg icon="star" iconWeight="fill" />

Adds a single node to the document tree.

Replaces an existing node with new JSX content in-place. Preserves position in parent.

Updates properties of an existing node. Only specified properties are changed.

update_node({
  nodeId: "node-abc123",
  textContent: "New heading text",
  className: "text-4xl font-bold text-white"
})

Updates only the className of a node. Replaces existing className entirely.

Updates multiple nodes in a single call. Efficient for bulk changes.

batch_update({
  updates: [
    { nodeId: "node-1", textContent: "Updated" },
    { nodeId: "node-2", className: "text-red-500" },
    { nodeId: "node-3", link: { type: "url", url: "https://example.com" } },
  ]
})

Updates artboard properties (resize, rename, change background).

Sets the fill (background) of a node or artboard. Supports solid colors, gradients, and images. Handles dual-write automatically.

Moves a node to a new parent or reorders within current parent.

Duplicates a node and all its children. Inserted after the original.

Duplicates an entire artboard with all content. Creates a deep copy with fresh IDs. Optionally resize the duplicate.

// Duplicate Desktop artboard as Mobile version
duplicate_artboard({
  artboardId: "artboard-1",
  newName: "Mobile",
  width: 375,
  height: 812
})

Groups selected nodes into a new frame container.

Ungroups a frame container, moving its children up to the parent.

Changes z-order: "front" = bring to top, "back" = send to bottom.

Deletes one or more nodes and all their children.

Deletes an artboard and all its contents.

Creates a new blank document, replacing the current one. Discards unsaved changes.

Renames the document.

Undoes the last action (Cmd+Z).

Redoes the last undone action (Cmd+Shift+Z).

Zooms the viewport to fit all artboards. Useful after creating multiple artboards.

Zooms the viewport to fit a specific artboard.

Selects nodes on the canvas to highlight for the user. Empty array deselects all.

Deselects all currently selected nodes.

Shows or hides a node. Hidden nodes remain in the tree but are not rendered.

Aligns multiple nodes along a shared axis.

Distributes nodes evenly with equal spacing.

Repositions an artboard on the canvas. Use to lay out multi-screen flows (e.g. Desktop at 0,0, Tablet at 1540,0).

Sets the viewport zoom level and/or pan position. Zoom 1.0 = 100%.

Exports an artboard or node as an image (PNG, JPEG, WebP, SVG). Returns base64 data URL. Use thumbnail: true for a small preview suitable for AI agents.

Audits the current design against professional quality rules: typography (scale, weight contrast, sizing), color (neutral consistency, pure black, known low-contrast combos), spacing (4pt grid, touch targets), and AI slop detection (monotonous layouts). Returns issues with severity (warning/info) and actionable suggestions.

// Audit everything
audit_design()

// Audit one artboard, only typography and spacing
audit_design({
  artboardId: "artboard-1",
  checks: { typography: true, spacing: true, color: false, slop: false }
})

Applies safe, deterministic fixes to common design issues: adds missing w-full on top-level sections, converts arbitrary Tailwind values to inline styles, replaces pure black with zinc-950, bumps small touch targets to 44px, adds placeholder images to empty image nodes, and fills empty text content. Run after audit_design to auto-fix warnings.

// Auto-repair all artboards
repair_design()

// Preview fixes without applying
repair_design({ dryRun: true })

// Repair one artboard
repair_design({ artboardId: "artboard-1" })

Returns the current document theme including all modes and their tokens. Use this to understand the active design system before creating content.

get_theme()
// → { id, name, modes: { light: {...}, dark: {...} }, activeMode: "light", activeTokens: {...} }

Sets the document theme. Three options: (1) presetId — apply a built-in preset, (2) css — import raw CSS with :root {} and .dark {} blocks containing --background, --primary, etc. variables, (3) modes — provide token objects directly per mode.

// Apply a preset
set_theme({ presetId: "blue" })

// Import CSS from any source
set_theme({ css: ":root { --background: #ffffff; --primary: #2563eb; }\n.dark { --background: #0a0a0a; --primary: #60a5fa; }" })

Switches the active theme mode. All artboards update to show the new mode colors. Standard modes are "light" and "dark" but custom modes are supported too.

set_theme_mode({ mode: "dark" })

Removes the document theme entirely, returning to raw Tailwind colors with no semantic tokens.

Returns the active brand system for the current document, including brand identity (company name, tagline, values, voice), color palette (semantic tokens for light/dark modes), typography (heading/body/mono fonts + type scale), icon preferences, and AI directives. Returns null if no brand system is active. Always call this at the start of any design task.

get_brand_kit()
// → { identity: { companyName, tagline, ... }, colors: { light: {...}, dark: {...} }, typography: {...}, icons: {...}, aiGuidelines: "..." }

Apply an existing brand system to the current document by ID. Sets the document theme to the brand's colors and stores the brand reference.

Lists all brand systems available to the user. Returns summaries with id, name, primary color, and company name.

Create a new brand system from scratch and apply it to the current document. Provide a company name and optionally identity fields.

create_brand_kit({ companyName: "Acme Corp" })

Detaches the active brand system from the document. Current theme colors are preserved as a standalone theme, but the brand reference is removed.

Duplicate an existing brand system. Creates a copy with " (Copy)" appended to the name.

Update the active brand system's identity fields: company name, tagline, description, industry, target audience, brand values, voice & tone, AI directives.

Update colors in the active brand system (which IS the document theme). Provide a mode ("light" or "dark") and the token values to change.

update_brand_colors({
  mode: "light",
  tokens: { primary: "#2563eb", accent: "#f59e0b" }
})

Update the AI guidelines markdown document for the active brand system — the "brand bible" that tells AI how to design for this brand.

Export the active brand system in a given format: "css" (CSS variables), "tailwind" (Tailwind v4 config), "style-dictionary" (Style Dictionary tokens), "figma" (Figma Variables), or "package" (complete JSON).

export_brand_system({ format: "tailwind" })

Save selected node(s) as a reusable brand component in the active brand system. Can be inserted later via insert_brand_component.

List all saved brand components and templates in the active brand system.

Insert a saved brand component or template into the design. Creates a fresh copy with new IDs.

Delete a saved brand component or template from the active brand system.

Save selected node(s) as a reusable brand template (section/page layout). Templates use semantic tokens so they re-theme automatically.

Get curated brand images and Lummi seed IDs from the active brand system. Returns image URLs that define the brand's visual style.

Audit the design for brand system compliance violations. Checks: hardcoded colors, wrong fonts, wrong icon library/weight, non-semantic tokens.

audit_brand_compliance()
// → { violations: [{ type: "hardcoded-color", nodeId: "...", message: "..." }] }

Search for free, high-quality stock images (powered by Lummi). Returns image URLs that can be used with add_node (type: 'image') or set_fill (type: 'image'). No session required.

search_images({ query: "team working", orientation: "horizontal" })
// → [{ url: "https://...", width: 1920, height: 1080, alt: "..." }, ...]