compose-ui-builder
Design or edit a screen or Wear widget in the Compose UI Builder over MCP. Use only for a UI Builder URL (…/ui-builder/…), a .uid design file, or an explicit request to design or author a screen or Wear widget in the UI Builder, explore design alternatives, or turn an approved builder design into Compose code.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-15
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- compose-ui-builder
- description
- Design or edit a screen or Wear widget in the Compose UI Builder over MCP. Use only for a UI Builder URL (…/ui-builder/…), a .uid design file, or an explicit request to design or author a screen or Wear widget in the UI Builder, explore design alternatives, or turn an approved builder design into Compose code.
02 资源文件 10
- 参考文档references/access-and-editing.md9.5 KB
- 参考文档references/collaboration.md9.3 KB
- 参考文档references/documents-and-vocabulary.md10.4 KB
- 参考文档references/gotchas.md1.6 KB
- 参考文档references/local-design-to-code.md4.1 KB
- 参考文档references/local-host.md7.9 KB
- 参考文档references/m3-catalog.md27.3 KB
- 参考文档references/remote-m3-catalog.md14.2 KB
- 参考文档references/review-and-compare.md10.7 KB
- 参考文档references/wear-m3-catalog.md14.3 KB
03 SKILL.md 正文
Compose UI Builder
The UI builder is an authoring surface served by compose-preview serve: a
design is a document of catalog components, edited by an operation log, and
exported as Compose Kotlin (or PNG/SVG). A person edits it in the browser at
/ui-builder/<catalog>/<designId>; you edit the same live document over the
server's MCP endpoint. Both land in one revision log, so you and a designer can
work on the same design at the same time.
A design can also live in a checked-in .uid file. For a repository design,
inspect its schema and follow the local design-to-code workflow:
edit the canonical file, compare real design renders with references, adapt
exported Kotlin into the application, then render the affected @Previews.
Use compose-preview alongside this skill when a composable already exists.
The server ships from
compose-preview-server;
people start at https://ui.coo.ee/start (longer guide:
docs/UI_BUILDER_GETTING_STARTED.md).
The public host's MCP endpoint is https://preview.coo.ee/mcp: configure only
that URL (mcp.md § Which MCP server).
Firm collaboration contract
These rules apply before the creation and editing recipes below:
- Work at the recorded home. For an existing server design, start with
ui_builder_get_designand read itshome. For a checked-in.uid, read the file and its recorded home first; a server lookup is not required. A server-homed design is edited on that server; a repo-homed design is edited at its recorded.uidpath. Do not export a server design, edit the copy locally, and re-import it. Servers recordhomesince compose-preview-server v3.76.0; if the response has none (an older host, or a design created before then), say that the canonical home cannot be verified. Do not infer or rewrite it. - Keep discussion at the home. For a server-homed design, call
ui_builder_list_commentsbefore the first edit, reply and resolve there, and check again before finishing. For a repo-homed design, use its linked PR or issue. Link to that discussion withui_builder_set_links; do not split it across chat, an issue, and server comments. - Use typed operations and validation. Prefer
ui_builder_applyand the tool schemas over editing document JSON. Callui_builder_check_design(which runsui_builder_validateplus accessibility checks) before showing or finishing, orui_builder_validateon a host that has only that. If validation or a required schema is not available, say so; an export diagnostic is useful but is not a substitute for document validation. If hand-editing is unavoidable, validate before saving and render again afterwards. - See the editor after each visible step. Call
ui_builder_view(compose-preview-server v3.89.0 and later): it draws the canvas as a person sees it, with selection, reference overlay and comment pins. On a host that does not advertise it, inspect PNG/SVG or native output, label it as not the editor viewport, give the browser URL, and never infer selection, overlays, or comment pins from JSON or an export. - Close temporary copies. A local copy may be used for a compile check or offline experiment only. Announce its path and purpose, keep its recorded home pointing at the canonical design, and save the result back to that home or discard the copy before finishing. Moving a design between server and repo homes requires explicit approval.
Before finishing, run ui_builder_check_design, look at the final editor view
and the device grid, and check for unread or unacknowledged comments at the
design's home. Hand back the link, the revision and whether a person has
approved it (Approval and handoff to code).
Report any capability that prevented one of those checks.
Viewer, prompts, and interactive decisions
The MCP Apps viewer, prompts and elicitation depend on the host as much as on
the server. Discover them from tools/list and the client's capabilities, and
use the text fallbacks in the
catalog MCP reference
when they are absent.
Core creation loop
This compact example shows the core creation calls; the home, comment, validation, and editor-view checks above still apply:
// 1. request_access — capabilities, not scope (see "Getting in")
{"capabilities": ["ui-builder-read", "ui-builder-write", "ui-builder-export"],
"ttlSeconds": 14400,
"label": "add a header row to the settings screen"}
// → show approveUrl + userCode to your human, then poll_access
// 2. ui_builder_create_design — a whole document; the starter below is known-good
{"designId": "settings-v2", "document": { …see references/documents-and-vocabulary.md… }}
// 3. ui_builder_apply — insert a column and a text into it, one operation
{"designId": "settings-v2", "operationId": "op-1", "baseRevision": 0, "operations": [
{"type": "insertNode",
"node": {"id": "col", "componentId": "layout/column", "slots": {"children": []}},
"location": {"parent": {"nodeId": "root", "slot": "content"}}},
{"type": "insertNode",
"node": {"id": "title", "componentId": "m3/text",
"properties": {"text": {"type": "string", "value": "Settings"}}},
"location": {"parent": {"nodeId": "col", "slot": "children"}}}]}
// → {"outcome":{"type":"accepted","committedRevision":1, …}} ← next baseRevision
// 4. ui_builder_check_design — schema, catalog/export gate and accessibility in one
{"designId": "settings-v2"}
// → {"summary": "…", "ok": false, "findings": [{"nodeId": "title", …}]} ← fix with apply
// pass "operations" (+ "baseRevision") instead to dry-run a batch before applying it
// a `skipped` reason of "no native render was available" may hide a failed
// compile on older hosts: call ui_builder_render_native to find out
// 5. ui_builder_render_design_matrix — every device the screen claims, one picture
{"designId": "settings-v2", "themes": ["light", "dark"], "fontScales": [1, 2]}
// 6. ui_builder_export — the Kotlin, or diagnostics saying why not
{"designId": "settings-v2", "format": "compose"}
// 7. tell your human where it is
// https://<host>/ui-builder/<catalogSystemId>/settings-v2
Read each reply's summary first; it is written to be enough on its own. Step 4
replaces a separate validate and accessibility pass, though not the editor
view: run it before you show a design to anybody, and fix its findings by nodeId through
ui_builder_apply. The device grid in step 5 is where a navigation rail that
never collapses, or text that clips at 200% font scale, shows up. Look at it
before calling the screen done.
Send that browser URL as soon as the design exists, then keep sending the current revision, what just changed, the comment state, and the next action. Do not make a person infer progress from a silent series of MCP calls. A useful update is: “Desktop reference is at revision 4; the header and rails are in; there are no open comments; next I am comparing it with the attached reference.”
Before creating or editing anything, orient yourself:
- Look for an existing design or checked-in fixture with the requested name.
Call
ui_builder_get_design, read its recorded home and links, and read the discussion at that home before deciding to edit or create. Do not copy an existing design merely to avoid working at its home. - Open the canonical path URL returned by the design identity:
https://<host>/ui-builder/<catalogSystemId>/<designId>. Do not invent an old query-string URL; the path carries both the catalog and design. - If the request names or attaches a visual reference, check whether one is
already attached (
ui_builder_compare_reference, or Frame, density and reference in the browser). The full reference workflow is under Compare with a reference. - Report the link, revision, open-comment count, and the first planned part before editing. This is the point where the person can correct the target while the correction is still cheap.
Getting in
The ui_builder_* tools are gated on capabilities — ui-builder-read,
ui-builder-write, ui-builder-export — not implied by the
preview / live / playground scope ladder. The handshake is the ordinary agent-grant one
(server-access.md,
catalog-mcp.md), plus:
- Ask for all three capabilities at once, and
previewscope, which costs nothing. - Ask for enough time once:
ttlSeconds: 14400when the task includes reference comparison or live feedback. - Pass the token as each tool's
tokenargument; a token approved mid-session cannot become a header. - Make the approve link one click: the
userCodeon one line, the bareapproveUrlon its own line below it. - Collect approval in the background: call
poll_accesseverypollIntervalSecondsuntil approved, denied, expired or unknown. Never spin, and never make the person come back and say “done”.
Grants live in memory: a redeploy drops yours mid-task. Ask again the same way. The full flow is in access-and-editing.md § Getting in.
The edit loop
ui_builder_apply is the workhorse and the only cheap call:
- Batch.
operationsis an array; a scaffold, its column and three texts are one call, one revision, one undo step for the designer watching. operationIdis yours and makes a retry idempotent — a replay answersidempotentReplay: truerather than inserting twice.baseRevisionis the revision you last saw. The reply'scommittedRevisionis your next one; track it locally rather than re-reading the design. A stale base is not automatically refused — the service rebases what does not collide and reports what does inconflicts, so check that array rather than assuming a rejection.- A batch is atomic. One refused operation lands none of them, so a container and the child a slot requires can safely be inserted together.
- A rejection is a normal reply, not an error:
rejected, with acode,nodeIdandfieldprecise enough to fix without a re-read.
Drive from apply, not snapshots, one part of the screen per call (shell,
header, list, footer). After each part, do the contract's visual check and read
the comments. Detail and the common rejections:
access-and-editing.md § The edit loop.
Reference index
Read only what the task needs.
| Task | Read |
|---|---|
What to insert: ids, slots, required properties, enums. Read these rather than calling ui_builder_list_catalogs, the authority when something is missing |
m3-catalog.md, wear-m3-catalog.md (Wear app), remote-m3-catalog.md (Wear widget) |
A checked-in .uid design, implemented in the app |
local-design-to-code.md |
No host: run ui-builder --no-project, attach MCP, shell verbs |
local-host.md |
| Known-good starter documents, the vocabulary, export as a check | documents-and-vocabulary.md |
| Full grant flow, edit-loop detail, Material and gap-reporting habits | access-and-editing.md |
| Look at the design, compare with a reference, review design guidelines | review-and-compare.md |
| Comments and a designer, branches, approval and handoff to code, keeping a design | collaboration.md |
| Something behaves oddly | gotchas.md |
04 同仓库更多 Skills
harness-notes
Use whenever you change Compose UI code (composables, @Preview functions, themes) or render or review Compose previews, catalog components or UI Builder designs. Carries the mandatory cross-harness agent rules (R1–R4) and per-host notes for these tools.
compose-preview-setup
Run right after the compose-preview plugin is installed, or when a render fails because the CLI is missing or the project is "not prepared". Checks the compose-preview CLI, prepares the current Gradle project once, and renders one preview so the person sees it working.
compose-catalogs-setup
Run right after the compose-catalogs plugin is installed, or when the hosted catalog server cannot be reached or asks for access. Checks the hosted preview.coo.ee catalog server, completes the access grant, and shows one catalog so the person sees it working.
antigravity-viewer-card
Show a render of the person's own Compose previews in Antigravity — one render_preview call with preview=<FunctionName> on the local compose-preview-mcp server, a look at the PNG, then the card and a few bullets.
spike-p2
Use when the user says 'spike check'.
spike-p1
Use when the user says 'spike check'.