Design UI with an AI Agent in DesignJS

Walk through a complete AI-assisted design session: start the canvas, connect your agent, and iterate on a hero section from prompt to polished UI.

DesignJS gives your AI agent direct read/write access to a live HTML/CSS canvas, so you can describe what you want in plain language and the agent builds it visually — no copy-paste between code and a browser preview required. This guide walks through a complete workflow: starting the canvas, connecting an agent, adding a hero section, and iterating until the design looks right.

Prerequisites

• DesignJS repository cloned and dependencies installed (pnpm install)
• An MCP-compatible agent configured — Claude Code, Cursor, or VS Code with the MCP extension
• If you haven’t run designjs init yet, see the quickstart

---

The workflow

1. Start the canvas

   Run the dev server from the repo root:

   pnpm dev
   

   The canvas opens at http://localhost:3000. The WebSocket bridge starts automatically on 127.0.0.1:29170. You’ll see a connection indicator in the top-right corner of the editor shell — it turns green when at least one peer (your agent’s MCP server) is connected.

   Keep the browser window visible while working with an agent. You’ll review changes in real time without needing to manually refresh.

2. Verify the agent is connected

   In your agent session, call ping before doing anything else. It’s a zero-argument health check that confirms the MCP server has an active WebSocket route to the canvas:

   // Tool call
   {
     "tool": "ping",
     "params": {}
   }
   
   // Expected response
   {
     "pong": true,
     "at": 1713456789012
   }
   

   If ping times out or returns an error, the canvas WebSocket bridge isn’t reachable. Check that pnpm dev is still running and the browser tab is open.

3. Capture the current canvas state

   Before adding anything, have the agent take a screenshot to understand the current layout. This is the visual baseline the agent will build on:

   // Tool call
   {
     "tool": "get_screenshot",
     "params": {
       "scale": 2,
       "format": "png"
     }
   }
   
   // Response
   {
     "dataUrl": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
     "width": 1280,
     "height": 800
   }
   

   scale: 2 returns a high-DPI screenshot at twice the CSS pixel dimensions — useful for seeing fine typographic detail. The agent embeds dataUrl as an image in its context and can reason about what’s on the canvas before making any changes.

   You can also scope a screenshot to a single artboard by passing artboardId. Use list_artboards first to get the id.

4. Describe what you want

   Tell the agent what to build. Be specific about layout, content, and tone — the more concrete the prompt, the fewer revision cycles you’ll need:

   “Add a full-width hero section with a dark navy background (#0f172a), a bold white headline that reads ‘Ship design and code together’, a one-line subheadline in slate-400, and a primary CTA button that says ‘Get started free’ in indigo.”

   The agent translates this into an add_components call with raw HTML and Tailwind classes.

5. Agent adds the component

   The agent calls add_components with the HTML it generates. The target parameter is optional — omit it to append to the canvas root, or pass a parent componentId to nest the new content inside an existing section:

   // Tool call
   {
     "tool": "add_components",
     "params": {
       "html": "<section class=\"w-full bg-[#0f172a] py-24 px-8 flex flex-col items-center text-center gap-6\"><h1 class=\"text-5xl font-bold tracking-tight text-white\">Ship design and code together</h1><p class=\"text-lg text-slate-400 max-w-xl\">DesignJS gives AI agents visual awareness of your HTML/CSS canvas. Describe, iterate, and export — no translation gap.</p><a href=\"#\" class=\"inline-flex items-center gap-2 rounded-lg bg-indigo-600 px-6 py-3 text-sm font-semibold text-white hover:bg-indigo-500 transition-colors\">Get started free</a></section>"
     }
   }
   
   // Response
   {
     "componentIds": ["comp-a1b2c3"]
   }
   

   Save the returned componentId — you’ll use it in the next steps to scope refinements to this specific element.

   Tailwind v4 classes resolve natively in the canvas iframe (loaded via CDN), so arbitrary values like bg-[#0f172a] and responsive variants work without any configuration.

6. Agent verifies the result visually

   After inserting the component, the agent captures another screenshot to confirm the visual output matches the intent:

   // Tool call
   {
     "tool": "get_screenshot",
     "params": {
       "scale": 2,
       "format": "png"
     }
   }
   

   If the layout, color, or typography looks off, the agent can read the current CSS for the component before making targeted adjustments:

   // Tool call — read CSS for the hero section specifically
   {
     "tool": "get_css",
     "params": {
       "componentId": "comp-a1b2c3"
     }
   }
   
7. Agent refines styles

   When the agent identifies a specific property to tweak — such as adding more vertical spacing or softening the button border radius — it uses update_styles to target the component directly by id:

   // Tool call — increase vertical padding and round the button
   {
     "tool": "update_styles",
     "params": {
       "componentId": "comp-a1b2c3",
       "styles": {
         "padding-top": "7rem",
         "padding-bottom": "7rem"
       }
     }
   }
   
   // Response
   {
     "styles": {
       "padding-top": "7rem",
       "padding-bottom": "7rem"
     }
   }
   

   For compound refinements — like adjusting multiple nested elements — it’s often faster to have the agent call get_html on the component, revise the HTML string in context, and use add_components with target to replace the section rather than chaining many update_styles calls.

8. Review in the browser

   Switch to the browser tab with the canvas open. Everything the agent just added and refined is rendered live — you’re looking at real HTML and CSS, not a preview approximation.

   If something still needs adjusting, you can either:

   • Tell the agent — describe the change in natural language and continue the loop
   • Edit directly — click the component in the canvas, use the style panel on the right, and the agent can re-read the state with get_screenshot or get_html on the next turn

   Your changes and the agent’s changes converge on the same GrapesJS component model. Press Cmd+S (or Ctrl+S) to save the canvas to .designjs.json.

---

Targeting components precisely

When the canvas has multiple sections, you want the agent to operate on the right element rather than the entire document.

Use get_selection to target whatever is clicked:

Select a component in the canvas editor (click it in the canvas or the layers panel), then ask the agent to call get_selection:

// Tool call
{
  "tool": "get_selection",
  "params": {}
}

// Response
{
  "componentIds": ["comp-a1b2c3"]
}

Pass that id directly to update_styles, get_html, get_css, or get_jsx. This is the fastest way to tell the agent “work on this exact thing.”

Use get_tree for structural context:

If the agent needs to understand the component hierarchy before deciding where to insert content, get_tree returns the full recursive component tree:

// Tool call
{
  "tool": "get_tree",
  "params": {
    "depth": 3
  }
}

Limiting depth keeps the response concise for large documents.

---

Working with artboards

If your canvas has multiple artboards (for example, a desktop and mobile layout), scope get_screenshot to a specific frame to avoid ambiguity:

{
  "tool": "get_screenshot",
  "params": {
    "artboardId": "artboard-desktop-01",
    "scale": 2,
    "format": "png"
  }
}

Use list_artboards to enumerate artboard ids and dimensions before scoping any tool call.

---

Next steps

Export to React

Convert your finished canvas design to a .tsx component using get_jsx.

Manage design tokens

Use get_variables and set_variables to maintain a consistent color and spacing system across your canvas.