Design agent playbook

Token-efficient loop for editing pages, chrome, and components via MCP/API.

Verify loop

1. get_* with mode=summary to see block ids/types/propsKeys (and anchorId when set).
2. Patch with update_* ops (set/insert/remove/move by blockId + prop path). Prefer ops over full content replace.
3. Slim update responses return changedBlockIds, contentLocale, and hasWarnings—not the full document.
4. If hasWarnings is true, call get_design_warnings for details (schema + routePageId checks; no DOM overflow).
5. get_* with blockId for one subtree, or full get only when you need the whole document.

Block-id ops

Ops shape: set {blockId, path, value}, insert {parentBlockId, slot?, index, block}, remove {blockId}, move {blockId, parentBlockId, slot?, index}. Use blockId “root” (or path starting with root.) for root props. Pass either content or ops—not both. Errors include design.block_not_found, design.op_bad_path, design.ops_or_content, design.json_parse.

Breakpoints and layout

get_layout / update_layout manage maxContentWidthPx and breakpoints. Block props often key styles by breakpoint id; after changing breakpoints, re-check those maps. Prefer ModalBlock + buttons for mobile nav patterns.

Cache timing

Saving chrome, pages, or components invalidates preview chrome cache and public page-by-route cache. Public pages should reflect component/chrome changes after a successful save without a manual cache clear.

Anchors / outline

Summary mode includes anchorId when a block has anchorId or anchorKey. Map those to blockId for targeted patches. DOM id conventions follow the block’s anchor fields in the design schema.