a2ui

<div align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="examples/brand/wordmark-dark.png"> <img src="examples/brand/wordmark-light.png" width="560" alt="A2UI Catalog"> </picture>

The vocabulary layer for A2UI — useful for humans · declarative for agents.
The model names an atom. The renderer compiles the HTML, CSS, SVG, and animation.

<!-- readme-badges:start -->

<!-- readme-badges:end -->

Independent, unofficial catalog — not affiliated with or endorsed by Google. A2UI is Google's protocol; the official spec lives at a2ui.org.

</div>

---

The idea

Rather than asking an agent to generate custom UI every turn — expensive, fragile, unpredictable — give it a stable vocabulary of atoms and let it compose from those.

The model names an atom; the renderer expands it into the full HTML server-side, and that expansion never re-enters the model's context window — so the tokens spent describing a UI are a fraction of the tokens in the rendered result.

Work in progress. The atom vocabulary itself is stable; what it's for is still being explored. The live catalog and this repo are the vocabulary and its renderers — applying that vocabulary to new use cases (rendering a CLI's own output, for instance, in a sibling project not yet published) is ongoing, not finished.

---

Connect an agent

The catalog is consumable three ways, no signup for any of them — BYO by design: renders happen in your environment, your data never touches us.

| Channel | Endpoint | What an agent gets | |---|---|---| | MCP server | a2uicatalog.ai/mcp | Tools to browse catalogs, validate/compose payloads, emit render URLs, and render live views on MCP Apps hosts | | ARD manifest | /.well-known/ard.json | Agentic Resource Discovery — every atom as a crawlable, typed entry | | Machine catalog | a2uicatalog.ai/spec.json | The full schema in one fetch — types, fields, surface compatibility, degradation notes |

5-minute quickstarts: Claude (Desktop / claude.ai) · Gemini Enterprise (BYO-MCP)

As an agent skill — this repo ships a SKILL.md, so any agent using the skills ecosystem can pick up the catalog's when-to-use guidance directly:

npx skills add a2uicatalog/a2ui@a2ui-atomic-catalog

A few atoms, live on the site — click through to a full spec + fields table for each:

<table> <tr> <td align="center"><a href="https://a2uicatalog.ai/atoms/glowing_stat/"><img src="examples/atom-glowing-stat.png" width="240" alt="glowing_stat atom preview"></a><br><a href="https://a2uicatalog.ai/atoms/glowing_stat/"><code>glowing_stat</code></a></td> <td align="center"><a href="https://a2uicatalog.ai/atoms/stat_card/"><img src="examples/atom-stat-card.png" width="240" alt="stat_card atom preview"></a><br><a href="https://a2uicatalog.ai/atoms/stat_card/"><code>stat_card</code></a></td> </tr> <tr> <td align="center"><a href="https://a2uicatalog.ai/atoms/before_after/"><img src="examples/atom-before-after.png" width="390" alt="before_after atom preview"></a><br><a href="https://a2uicatalog.ai/atoms/before_after/"><code>before_after</code></a></td> <td align="center"><a href="https://a2uicatalog.ai/atoms/annotated_code/"><img src="examples/atom-annotated-code.png" width="390" alt="annotated_code atom preview"></a><br><a href="https://a2uicatalog.ai/atoms/annotated_code/"><code>annotated_code</code></a></td> </tr> </table>

Browse all 450+ atoms →

---

Google Apps Script renderer — try it live

450+ atoms running natively in Google Apps Script. No CDN, no dependencies, no server. Paste a JSON block list, get a rendered page.

{
  "title": "Hello A2UI",
  "theme": "light",
  "blocks": [
    { "type": "heading", "level": 1, "text": "My first A2UI page" },
    { "type": "callout", "icon": "💡", "text": "Built with 450+ atoms in Google Apps Script." },
    { "type": "chartjs_bar", "title": "Quick chart", "bar_color": "#6366f1",
      "data": [{ "label": "A", "value": 80 }, { "label": "B", "value": 45 }, { "label": "C", "value": 62 }] }
  ]
}

What's in the GAS renderer

| Feature | Detail | |---|---| | 450+ atoms, growing | Apps Script surface — superset of the web article renderer | | CSS-only interactions | Tabs, carousel, gallery lightbox, modals, accordions — zero JS required | | Inline SVG charts | Bar, line, pie, donut, heatmap, punch card, sankey, cohort retention, GitHub activity grid | | 8 form input types | text, email, select, radio, checkbox, switch, slider, date — native HTML controls | | Animation fallbacks | 32 motion atoms degrade to readable content cards | | No CDN | Works inside GAS sandboxed iframes with no external requests | | Large payload support | Automatically switches to POST for schemas too large for a URL |

Deploy your own renderer (recommended)

The renderer is fully open source. Deploy your own instance — you own the URL, you own the deployment, no dependency on the catalog's demo endpoint.

git clone https://github.com/a2uicatalog/a2ui
cd a2ui/apps-script-surface/gas-schema-renderer
clasp login
clasp create --type webapp --title "My A2UI Renderer"
clasp push
clasp deploy
# → Your renderer is live at https://script.google.com/macros/s/YOUR_ID/exec

Call it with any payload from the catalog (illustrative — encode() stands in for gzip + base64url of the JSON, see scripts/make_url.py for the exact encoding):

function doGet() {
  const blocks = [
    { type: "stat_card", value: "1,234", label: "Daily users", delta: "+12%", is_up: true },
    { type: "progress_bar", value: 75, label: "Q2 target" }
  ];
  const url = "https://script.google.com/macros/s/YOUR_ID/exec";
  return HtmlService.createHtmlOutput(
    `<script>window.location="${url}?p=${encode(blocks)}"</script>`
  );
}

The catalog's "Try it live" button uses a shared demo instance of the same renderer. For anything beyond exploration, deploy your own.

---

What's in this repo

| Directory | Contents | |---|---| | atoms/ | Atom schema definitions (schema.yaml) | | renderers/ | Surface renderers — web_article.py is the canonical web renderer | | apps-script-surface/ | GAS renderer — atom.gs + atom files (450+ atoms, no CDN) | | components/ | Lit Web Components for the meet-stage surface | | scripts/ | Build pipeline — atom pages, spec.json, MCP bundle, README compat matrix, link/brand checks | | vendors/ | Landscape analysis of 9 UI libraries mapped to A2UI atoms | | benchmarks/ | Token comparison study (BENCHMARK.md) | | spec/ | Internal state/action contracts (gdm-v0.2, a2ui-state-v1) — the A2UI v1.0 candidate spec itself lives at a2ui.org, not vendored here | | examples/ | Playbook YAML examples | | knowledge-catalogue/ | Curriculum-to-atom pipeline — schema-validated curriculum markdown (Brevet 2026, NIST AI RMF) compiled into A2UI payloads. Separate concern from the atom vocabulary itself. |

---

450+ atoms across 8 surfaces

Atoms declare which surfaces they support at the schema level. An agent picks an atom by name, supplies parameters, and the renderer handles the rest.

[{
  "type": "stat_card",
  "label": "Atoms published",
  "value": "450+",
  "delta": "+12 this week"
}]

Agents never write HTML. They compose from the vocabulary.

---

Surface compatibility

Every atom declares, at the schema level, which of the 8 surfaces it works on and where it degrades (with a note explaining the caveat). The matrix below is generated straight from public/spec.json — the same file agents consume — so this README can no longer drift from the catalog.

<details> <summary><strong>View full compatibility matrix (all atoms × 8 surfaces)</strong></summary> <!-- compat-matrix:start -->

500 atoms · generated from public/spec.json by scripts/gen_compat_matrix.py — do not edit by hand.

| Atom | web | gas-web | gas-panel | meet | chat | mcp-apps | email | pdf | Source · license | |---|---|---|---|---|---|---|---|---|---| | abbr_tooltip | ✅ | ✅ | — | ⚠️ | — | ✅ | ⚠️ | — | a2uicatalog · MIT | | accordion_item | ✅ | ✅ | — | ✅ | — | ✅ | — | — | a2uicatalog · MIT | | achievement_badge | ✅ | ✅ | — | ✅ | ⚠️ | ✅ | ✅ | ✅ | a2uicatalog · MIT | | action_items | ✅ | ✅ | — | — | — | ✅ | — | ✅ | a2uicatalog · MIT | | action_required_card | ✅ | ✅ | — | ✅ | ✅ | ✅ | ⚠️ | — | a2uicatalog · MIT | | actual_vs_estimate | ✅ | ✅ | — | — | — | ✅ | ⚠️ | — | a2uicatalog · MIT | | adsb_feed | — | ✅ | — | — | — | — | — | — | a2uicatalog · MIT | | agenda_block | ✅ | ✅ | — | — | — | ✅ | — | — | a2uicatalog · MIT | | ai_build_trace | — | ✅ | — | — | — | ✅ | — | — | a2uicatalog · MIT | | airspace_command_deck | — | ✅ | — | ✅ | — | ✅ | — | — | a2uicatalog · MIT | | alert_banner | ✅ | ✅ | — | ✅ | ⚠️ | ✅ | — | — | UIverse.io community · MIT | | ambient_gradient | ⚠️ | ✅ | — | — | — | ✅ | — | — | a2uicatalog · MIT | | anchor_list | ✅ | ✅ | — | ✅ | ⚠️ | ✅ | ✅ | ✅ | a2uicatalog · MIT | | animated_beam | ✅ | ✅ | ⚠️ | ✅ | ⚠️ | ✅ | — | ⚠️ | a2uicatalog · MIT | | animated_border | ✅ | ✅ | ✅ | ✅ | — | ✅ | — | — | a2uicatalog · MIT | | animated_border_card | ✅ | ✅ | — | ✅ | ⚠️ | ✅ | — | ⚠️ | a2uicatalog · MIT | | animated_counter | ✅ | ✅ | — | ⚠️ | — | ✅ | — | ⚠️ | a2uicatalog · MIT | | annotated_code | ✅ | ✅ | — | ✅ | — | ✅ | — | ⚠️ | a2uicatalog · MIT | | annotation_highlight | ✅ | ✅ | — | ✅ | — | ✅ | — | — | a2uicatalog · MIT | | api_param_table | ✅ | ✅ | — | ⚠️ | ⚠️ | ✅ | ⚠️ | — | shadcn/ui · MIT | | api_reference | ✅ | ✅ | — | ✅ | ⚠️ | ✅ | ⚠️ | ✅ | a2uicatalog · MIT | | article_hero | ✅ | ✅ | — | — | ⚠️ | ✅ | ⚠️ | — | a2uicatalog · MIT | | article_series_nav | ✅ | ✅ | — | — | ⚠️ | ✅ | ⚠️ | — | a2uicatalog · MIT | | atom_anatomy | ✅ | ✅ | — | — | — | ✅ | — | — | a2uicatalog · MIT | | `audio_