AI & Developer Experience
Three kinds of agent work with Urbicon UI: the coding agent that writes your app, the assistant inside your app, and assistants such as Claude that call the tools of your MCP server.
| Situation | Reach for |
|---|---|
| Your coding agent writes or changes your app's code. | The urbicon CLI |
| Your app's own assistant needs an answer, a choice or a confirmation from the user. | A2UIView |
| An assistant such as Claude calls a tool on your MCP server, and the tool should answer with a view instead of text. | @urbicon-ui/mcp-app |
The urbicon CLI
One dev-dependency, @urbicon-ui/design, gives your agent the full design surface: component discovery, recipes, patterns,
principles and the token reference — all pinned to the library version you installed. The same
package runs the loop: generated markup is gated by urbicon validate (an edit-time hook and a CI gate), judged against a scoring rubric, and design intent survives sessions
in a design.manifest.md in your repo. One measurement, so you can size the claim: Haiku 4.5, one task, CLI and gate against
neither. Reading the installed package on its own it shipped 373 findings, mostly raw Tailwind colours
and hand-written dark: patches; wired, validate came out clean. The design itself scored alike either way — this buys token discipline, not taste.
Setup
# One dev-dependency wires your agent into the design system
# (already there if you set the project up with `sv add @urbicon-ui`):
bun add -d @urbicon-ui/design
# Insert the agent context block (AGENTS.md), scaffold design.manifest.md
# and wire the edit-time gate (add --ci for the CI workflow too):
bunx urbicon init --hook
# Done — the next agent session reads AGENTS.md and takes over.Two commands, then hands-off. The context block
tells your agent which commands exist and when to run them — so the commands below are what the agent executes, not a workflow you learn. Your touchpoints afterwards are
reviews, not operations: the decisions the agent records in design.manifest.md show up in your git diff, and a red design gate shows up in CI.
What your agent runs
# Knowledge — version-matched to the library you installed:
urbicon find "date input" # fuzzy catalog search
urbicon get-component date-picker # real API: props, variants, examples
urbicon recipe login # production-ready Svelte 5 recipes
urbicon icons calendar # icon discovery
urbicon pattern dashboard # composition patterns per page archetype
urbicon principles --topic theming # design heuristics + paradigm profiles
urbicon css-reference intents # the token truth: naming, dark mode, overrides
# The design loop — generate → validate (the gate) → judge (advisory):
urbicon validate src/ # lint tokens, dark:/focus:, z-index; 0–100 scores
urbicon principles --rubric # 8-criterion rubric to judge a generated UI
urbicon context # read the project's design memory
urbicon record-decision --title … # write a decision the next session will seeVersion-matched knowledge
Discover: find, get-component, icons, recipe · Design knowledge: pattern, principles,
css-reference · What the CLI answers is true of the code in your node_modules — not of whatever shipped last week.
10 design verbs · gated correctness
Verbs: onboard, adopt, compose, redesign, polish,
critique, fix, retheme, audit, migrate — each a recipe over the design loop (urbicon verb <name>) · Enforcement: PostToolUse hook + CI gate via urbicon init.
llms.txt
Every component has its own llm.txt file with structured documentation. Agents can fetch it from the docs site, and urbicon get-component --section serves the same sections locally to minimize token usage.
LLM Documentation
# llms.txt (quick reference)
# llms-full.txt (complete API for every component)
# Per-component docs with 5 sections:
# overview | examples | variants | api | slots
# e.g. /primitives/button/llm.txtHow It Works
JSDoc annotations in component source files are the single source of truth. One edit automatically updates the documentation site, llms.txt files, and the version-pinned knowledge bundle the CLI reads.
A2UI: forms your assistant sends
When your assistant needs a date, a choice or a yes from the user, it can describe a form in A2UI, an open protocol for agent-generated UI, instead of
asking in prose. A2UIView from @urbicon-ui/blocks draws that form with Urbicon components. Your assistant sends a description, never code, and only
components the catalog lists reach the page.
On the server, a2uiSystemPrompt() and a2uiFencedTransportSection() write the part of your assistant's system prompt that names the components it may use and tells
it to send a form inside an ```a2ui fence in its reply. In the chat, A2uiStreamSplitter turns the streamed reply into text and form parts, A2UIView draws each form part, and its onAction fires when the user presses one of the form's buttons; a2uiActionMessage(event) turns that into your assistant's next user turn.
- The A2UI recipe builds the whole chat with all of these, including a later turn that updates a form your assistant sent earlier.
- The A2UIView page renders live forms and shows the prompt and the view's wiring in code.
- The A2UI guide covers how a form behaves over a conversation: why
typing in a field sends your assistant nothing, how to gate a button on the form's data, and
which parts of A2UI 1.0 the view refuses. Your coding agent reads it with
urbicon guide a2ui.
MCP Apps: a view for your tool
In a host that supports MCP Apps, such as Claude, a tool can answer with an HTML view instead
of text. The host is the assistant your users already chat with; your part is the MCP server
and the view, and @urbicon-ui/mcp-app covers both. It does not turn your own chat into a host: for a form in your own chat, use A2UIView.
Install
bun add @urbicon-ui/mcp-app- On the server (
@urbicon-ui/mcp-app/server, Node or Bun),createViewCataloglists your views and serves their HTML, andcreateDispatcheranswers the host's JSON-RPC requests. Your tools, credentials and HTTP route stay yours, and the server needs no MCP SDK. - In the view (
@urbicon-ui/mcp-app/view),startViewconnects to the host, hands your code the tool's arguments and result, and passes on the host's light or dark theme. The view renders with any framework. buildViews(@urbicon-ui/mcp-app/vite) builds each view into one HTML file. Urbicon components in a view built this way follow the host's theme; another build can compile theirlight-dark()colours into a form the host's theme no longer switches.@urbicon-ui/mcp-app/testingchecks your messages against the MCP SDK's schemas, and its/hostsubpath drives your server from a test host.
The walkthrough builds one view, from the
server to a card in Claude. The reference covers every entry point, including the peer packages the build and test entries need. Your coding
agent reads them with urbicon guide mcp-app-walkthrough and urbicon guide mcp-app.