Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.buildbetter.ai/llms.txt

Use this file to discover all available pages before exploring further.

The AI design agent is the system that turns your prompts into visual edits. It reads the DOM, applies changes, and reports back. This page covers what it can and can’t do, the built-in quick prompts, and how to phrase requests for the best results.

​
What the Agent Does

The agent is configured to act as a design assistant editing a captured static mockup. It can:
  • Read any part of the DOM with a CSS selector
  • Modify styles, attributes, and text content on existing elements
  • Insert new HTML before / after / inside an element
  • Remove elements
It can’t:
  • Execute JavaScript — captures are static, and scripts in inserted HTML are silently ignored
  • Reach outside the prototype’s iframe
  • Persist changes that didn’t go through its tools (e.g., it can’t “edit your CSS file”)

​
Quick Prompts

The Quick prompts dropdown (below the composer) inserts pre-written prompts for common transformations. Clicking inserts the prompt into the composer for review before you send.
LabelDescription
Clear content, keep frameIdentifies the page’s primary content region (the area holding page-specific content, not the app shell), removes its inner contents, and preserves the container element.
Convert to dark modeApplies a dark theme: near-black backgrounds (e.g., #0b0b0e), darker card surfaces, updated text colors for readability. Preserves accent colors when possible.
Make it mobile-friendlyReflows for a ~375px viewport: stacks columns, reduces padding/font sizes, ensures 44px tap targets, collapses horizontal nav.
Add empty + loading statesFinds the most prominent data region; inserts sketches for a loading state (skeleton placeholders) and empty state (friendly message + CTA) below the existing populated state.
Quick prompts are tuned phrasing — they give the agent specific instructions about scope and preservation, which tends to produce more predictable edits than ad-hoc requests.

​
The Agent’s Tools

Every visual change goes through one of four tools. Tool calls render in the chat as cards so you can see exactly what the agent did.

​
query_dom

Reads the DOM with a CSS selector. Returns up to 50 matched elements (default 10). For each match, you get:
  • Tag name, id, class list
  • Text preview (truncated to 160 chars)
  • Outer HTML preview (truncated to 600 chars)
The agent uses this first when a request is vague, or to inspect structure before editing.

​
modify_element

Changes one or more existing elements matching a selector.
  • Styles — CSS properties (camelCase or kebab-case accepted)
  • Attributes — HTML attributes (href, class, data-*, etc.)
  • Text content — replaces text
All matches are updated in one call.

​
insert_element

Adds new HTML relative to a matched element. Position options:
  • before — as a previous sibling
  • after — as a following sibling
  • inside-start — prepend as first child
  • inside-end — append as last child
Scripts in the inserted HTML are silently ignored.

​
remove_element

Deletes every element matching a selector. Returns the count removed.

​
How to Phrase a Request

Vague prompts get vague results. Specific prompts get specific edits. Less effective:
Make this page better.
More effective:
Reduce the hero section’s vertical padding by half, change the headline to “Ship faster with BuildBetter,” and replace the CTA button with a primary-styled “Start free trial” button.
The agent can do all three changes in one turn. It runs up to 12 steps per response (queries + edits + verifications), which is enough for complex multi-edit asks without forcing you to chat through each step.

​
When to Use Click-to-Select

If a request applies to a specific visual element and the CSS selector is hard to describe (“the third card in the second row”), use the Select element toolbar mode. Click the element, then send a message. The selector is prepended automatically.

​
When to Use a Quick Prompt

For broad, well-known transformations (dark mode, mobile reflow, content clearing) — quick prompts apply consistent rules that ad-hoc phrasing can miss.

​
What Persists

Every successful agent edit is added to the current version’s patch log and saved automatically. Failed tool calls (e.g., a selector that matched no elements) are surfaced in the chat but not added to the patch log — replaying the patches on reload would diverge from what you saw.

​
Limits

  • 12 steps per response — the agent stops after 12 tool calls in one streaming turn. If your request would take more, it’ll stop and let you continue in a follow-up.
  • No script execution — even if the agent inserts a <script> tag, it won’t run.
  • No cross-iframe access — the agent works on the prototype’s iframe; it can’t read or modify anything outside.
The agent honors your existing design tokens. If your captured page uses CSS custom properties (e.g., --brand-primary), the agent will usually update those variables rather than overriding individual elements — keeping the design system intact.