a2uicatalog · Vol. 22 LIVE_ARTIFACT

A2UI: How basic is the basic catalog?

2026-11-13 6 min read series a2uicatalog · Vol 22 build caa512e

After the official A2UI launch we went back to basics. The SDK makes macros very interesting: a model writes one short call, the server expands it into ordinary components, and the client needs no new code. So we asked how far the Basic catalog can be pushed, and with it how varied macros can get.

A note on scope: in the upstream macros guide, macros are not limited to the Basic catalog. They can expand into components from the Basic catalog, your own custom catalogs, or both. What Basic gives you is reach, because every client already has it.

How we got here

We did not start from a plan to push Basic as far as it goes. Each step came from the result of the one before. The numbers are from our noughts-and-crosses comparison of 5 November: one game, the official React renderer (0.15.0), headless Chromium, and they were not re-run for this article.

  1. Could a real game run on the official renderer with only Basic components? Yes: Column, Row, Button and Text, with the referee and the search on the agent side.
  2. Could it look good? We redrew it with gradient tiles and banners as inline SVG images. It looked modern, but each message grew from 3.2 KB to 12.8 KB on create, and from 0.7 KB to 7.3 KB on the largest update. Basic gave us no control over colour, font or spacing, so the look came from pictures and not from components.
  3. What would our own catalogue add? We built the same game with custom components for the board, the result and the status, registered in the host. The messages shrank to 1.4 KB and 0.3 KB, and the board became a real grid with one Tab stop, real headings, and motion that respects reduced motion. The host pays for it: 10.5 KB of extra code (3.6 KB gzipped) on top of a 621 KB renderer, and it has to register our catalogue. We also compared it with a plain HTML version: 6.6 KB in one file, no dependencies, and the same moves and results as the agent-driven game in every legal line of play (measured earlier). It is a separate app and not an agent-driven UI.
  4. What happens to a host that does not have our catalogue? Our own lowering to Basic failed badly: the board was dropped and no move could be played. A single surface has one component tree, so it cannot hold our version and a Basic version of the same screen at once. The agent has to choose. What worked was for the agent to read the host's supported catalogues and send the plain Basic design to a host that lacks ours.
  5. Where does Basic itself run out? We built a second game with more state, Connect Four. It needed a drawn board, so a macro draws it as an Image.
  6. How should things move? We compared sending animation frames against letting the client animate, at the protocol level (synthetic cases, one author, bytes only). Streaming frames lost by 30 to 100 times. Version 1.0 has no animation message, so today an animation has to live in a component or inside the picture itself. That is rung 5 of the ladder below.
  7. What does each choice cost? The message sizes are in the table below.

The capability ladder

Each rung is one thing you can do with only stock Basic components, on the official renderer, with no custom component. The pictures are real renders from the published React renderer (0.15.0), made for this article. Rungs 1 and 2 are Basic as it was designed. Rung 3 is where it levels up: a macro draws a picture on the server, and the client only has to show an Image. Rungs 4 and 5 are what that one trick unlocks. With Basic, our code stays on the server and the host renders only stock components.

What Basic gives you, in six lines. From the 1.0 Basic catalogue definition (18 components and 14 functions):

  • Show content: Text, Image, Icon, Video and AudioPlayer.
  • Arrange content: Row, Column, List, Card, Tabs, Modal and Divider. Row, Column and List can repeat their children from a data list.
  • Take and check input: Button, TextField, CheckBox, ChoicePicker, Slider and DateTimeInput. All six accept validation checks.
  • Bind to live data: any property can take a data binding or a function call.
  • React to the user: a Button fires an action.
  • Compute and format: and, or, not; formatCurrency, formatDate, formatNumber, formatString, pluralize; email, length, numeric, regex, required; and openUrl.
RungWhat it adds, and the evidenceRendered on the stock renderer
Basic as designed
1. Plain componentsText, Column, Row, Card and Button.A grey card titled Weekly report with one line of text and two buttons, Approve and Review
2. A whole atom reduced to BasicOf our 573 published atoms, 551 have a Basic case: the atom's example, reduced to Basic components only. We re-ran them on 15 November 2026 with v0.9 messages, and 539 of the 551 paint on React 0.15.0, 541 on Lit 0.15.0 and 540 on Angular 0.14.0. Each renderer was run once, and the other 22 published atoms have no Basic case yet. Paints means the case shows something, not that it looks right. (Corrected 15 November 2026: an earlier version of this row said "our 670-atom catalogue" and quoted 656, 658 and 657 from an 8 November run. Those figures count 670 cases, which include atoms that are not published, so they were not counts of published atoms.) This one is our pricing tier card.A pricing tier card reduced to Basic components: a Recommended label, Plan name, USD 29 a month, three ticked features and a Call to action button
Basic levelled up: draw a picture on the server
3. A drawn picture level upA macro draws an SVG on the server and returns it as a Basic Image. This is the rung that raised the ceiling, because Basic has no chart or board component. Rendered here: a treemap from our d3 pack.A treemap titled Cloud spend with coloured blocks for Compute, Storage, Network and Data, inside a Basic card
4. State and movesButtons send an action, the server answers with one data-model update, and the picture is redrawn from the state. This is Connect Four after three moves.A Connect Four board after three moves by each side, with seven column buttons underneath and a New game button
Pro level Basic catalog: mind blown, motion with no custom component
5. Motion inside the pictureThis is the real payload, rendered on the official renderer: one Express line expanded by a macro into 15 stock components, 28.6 KB of messages, the animation inside one Image (measured, our 7 November test: the pixels differ between 4 s and 25 s, no errors, no network requests, React only). Limits: reduced motion is not honoured inside an image, and the animation is not accessible beyond its alt text.

Not used here, but it works: we have also driven this same route with RFC 6902 patches, in our isometric pipeline and scene-kit demos. The agent sends patch operations, and an adapter turns them into data-model updates, because stock A2UI has no patch message: its agent messages create surfaces, update components, update the data model and delete surfaces, and in v1.0 call functions, but none of them applies a patch. The Image url is built from references into the data model, so a patch changes only a few values. In the run shown the two patches were 365 and 345 bytes of messages. Each patch reloads the whole Image, so the smooth motion between patches still comes from the CSS animation inside the picture (measured earlier, 10 November, one environment, React only).
An animated architecture diagram, A2UI from prompt to native UI, drawn as one SVG inside a Basic Image. The highlight moves from one step to the next.

A side note on rung 3. A drawn picture reaches any host that shows a Basic Image and accepts an SVG as a data URL. We measured that on the official React renderer. We have not tested whether native renderers such as Flutter or Jetpack Compose decode an SVG inside an Image, so they may need an extra decoder for it. Where an SVG does not draw, there are two ways round it. The macro can return a PNG instead, which every image decoder shows, at the cost of more bytes and a fixed resolution. Or the agent can fall back to plain Basic components, as in the noughts-and-crosses fallback below.

The same game, four ways, and where Basic stops

One game, noughts and crosses against an agent, on the official React renderer. Every version has the same contract: nine squares that send a play action, a New game control, and a status line. The first three are shown mid-game. In the plain and image versions you press Tab to move and Enter to play. In the custom version one Tab stop takes you to the board and the arrow keys move between squares. The numbers are from our comparison script on 5 November (headless Chromium 153, one scripted game of four messages) and were not re-run for this article.

Noughts and crosses on plain Basic components, mid-game
Plain Basic
Noughts and crosses on Basic components with gradient image tiles, mid-game
Basic with gradient images
Noughts and crosses on our custom catalogue, mid-game
Our custom catalogue
What a stock host drew when our emitter lowered the custom game to Basic: lines of text such as Text: /status and Shown: /result/shown, and only a New game button
Custom game on a host without the catalogue
VersionCreate messageLargest updateOne gameExtra code in the hostKeyboard
Plain Basic3,194 B719 B5,063 BNone10 Tab stops, no arrow keys
Basic with gradient images12,754 B7,305 B33,807 BNone10 Tab stops, no arrow keys
Our custom catalogue1,363 B297 B2,222 B10.5 KB minified (3.6 KB gzipped), on a 621 KB rendererOne Tab stop for the board, arrow keys move
Custom game on a host without the catalogue1,628 BNone1,628 BNoneNo squares to play

Plain Basic is playable and ships no code. The gradient images look best but cost the most bytes. The custom catalogue has the smallest messages and the best keyboard behaviour, and it costs the host extra code and an agreement to register it. The last row is what happens when the host has not: the board is gone.

We also wrote the same game as one plain HTML page, which you can play here. It is 6.6 KB (2.9 KB gzipped), has no dependencies and makes no network requests, and its nine squares and New game control are real, named buttons that work with Enter and Space (measured earlier on 5 November, not re-run). It is a separate app and not an agent-driven UI, so it is not a row in the table.

A bigger game

Rung 4 of the ladder was Connect Four, played against an agent on stock components: one Image drawn on the server, seven Basic Buttons and the game state in the data model.

Did we break the ceiling?

No. We raised it, and we can say where it now stops.

Row Basic alone With the drawn Image Still out of reach
Forms, text, layout Yes
Charts, boards, diagrams No Yes, as a static picture Hover, zoom, partial updates
A game No Yes, with Buttons and server state Pieces as real, accessible elements
Motion No CSS animation in an SVG, on React Reduced-motion support inside the image

Which route should you pick?

The ways we built the same noughts-and-crosses game, side by side. Read it as a menu and not a league table: the first and last rows are not A2UI at all, and every figure is from our 5 November comparison (measured earlier, one machine, not re-run).

Approach Agent-driven? Code the host needs Messages (create / largest update) Keyboard Where it works
Plain HTML page No The page itself, 6.6 KB None Enter and Space, real buttons Any browser, but not inside a chat host
Plain Basic Yes None 3,194 B / 719 B 10 Tab stops, no arrow keys Any host with the Basic catalogue
Basic with drawn images Yes None 12,754 B / 7,305 B 10 Tab stops, no arrow keys Hosts that draw an SVG in an Image: measured on the React renderer, other platforms untested
A custom catalogue: ours (a2uicatalog) or your own Yes Ours: 10.5 KB minified, on a 621 KB renderer, plus registering it. Yours depends on what you build 1,363 B / 297 B One Tab stop for the board, arrow keys move Hosts that register the catalogue; without it the board is dropped
An MCP App Not an A2UI payload An HTML app in a sandboxed iframe Not built Not measured Hosts that support MCP Apps; untested by us

Pick Basic when you cannot change the host. Pick a custom catalogue, ours or your own, when you can, and the board must be a real, keyboard-friendly component. The custom-catalogue figures in the table are for ours, so yours will differ. The drawn Image sits between them: it needs no host code and costs the most bytes.

Which route to pick: a decision tree7 boxes. Does an agent need to drive the UI? If No: A plain HTML page - or an MCP App, if it must live in a chat host (not built). If Yes: Can you change the host? - Register a catalogue, ship our code. If Yes: A custom catalogue - ours or your own: small messages, best keyboard; the host carries the code. If No: Does the screen need more than Basic can draw? - a chart, a board, an animation. If No: Plain Basic - no host code; works on any host that has the Basic catalogue. If Yes: Basic with a drawn Image - needs a host that draws an SVG; tested on React only, others untested.Does an agent need todrive the UI?A plain HTML pageor an MCP App, if it mustlive in a chat host (notbuilt)Can you change the host?Register a catalogue, shipour codeA custom catalogueours or your own: smallmessages, best keyboard;the host carries the codeDoes the screen need morethan Basic can draw?a chart, a board, ananimationPlain Basicno host code; works on anyhost that has the BasiccatalogueBasic with a drawn Imageneeds a host that draws anSVG; tested on React only,others untestedNoYesYesNoNoYes
A starting point, not a verdict. Reach, accessibility and message size pull in different directions. The figures behind each answer are in the table above (measured earlier, not re-run), and the drawn-Image route is measured only on the React renderer; other platforms are untested.
Text version of the decision tree
  1. Does an agent need to drive the UI?
    1. If No: A plain HTML page - or an MCP App, if it must live in a chat host (not built)
    2. If Yes: Can you change the host? - Register a catalogue, ship our code
      1. If Yes: A custom catalogue - ours or your own: small messages, best keyboard; the host carries the code
      2. If No: Does the screen need more than Basic can draw? - a chart, a board, an animation
        1. If No: Plain Basic - no host code; works on any host that has the Basic catalogue
        2. If Yes: Basic with a drawn Image - needs a host that draws an SVG; tested on React only, others untested

What we are not saying

This is not faster or better than a custom atom, and we have not compared speeds against a named baseline. a2uicatalog is independent and unofficial, and is not affiliated with Google or the A2UI project.

Updated 15 November 2026: an earlier version of this post had a section on Gemini Enterprise and referred to it in several places. We removed it. A specific follow-up is coming soon.