a2ui-catalog

Picking A2UI atoms

The catalog is deliberately not loaded all at once: 480 atoms is too much context for most tasks, and the wrong field name is a validation error, not a broken render — so this skill is about narrowing down to the right slice and reading its real contract, not guessing.

1. Narrow to a catalog slice

list_catalogs (MCP tool) or GET /catalogue/index.json (REST) returns every catalog with a one-line when-to-use, e.g. a2ui-atoms-v1 (the base vocabulary, always resolved), a2ui-learning-v1 (quizzes, flashcards, course UI), state/data-source extension catalogs. Pick the slice the task actually needs — do not pull the whole vocabulary into context for a one-chart request.

2. Read the real field contract

get_catalog(catalog) returns that slice's atoms with type + a one-line description — enough to confirm an atom EXISTS and roughly what it does, not enough to fill it in.

Before authoring any atom you haven't used before, call get_atom_schema(types) (MCP) or fetch /catalogue/atoms-json-schema.json (REST, strict per-atom JSON Schema — also useful as a response_format/grammar constraint so a model literally cannot emit an invalid atom). This is the step that prevents the single most common failure: guessing a prop name that doesn't exist, which either renders empty or gets silently normalised away.

required_catalogs(payload) is the reverse lookup — given a payload you already have, it returns exactly which catalog URIs it needs, deterministically (pure function of the atoms used, not a guess).

3. Common mistakes this skill exists to prevent

• Inventing a generic block type. There is no text or button atom. Every block names a real, typed atom from the vocabulary — check get_catalog first.
• Guessing a field name instead of calling get_atom_schema. An unrecognised or malformed field doesn't error loudly; it's caught and the block renders as a visible "unknown atom" notice, or the field is just dropped. Silent-wrong is worse than a hard error, so don't skip this step.
• Loading the full 480-atom vocabulary for a small task. Pick the catalog slice via list_catalogs first; it costs nothing and keeps the working context small.
• Assuming every atom renders everywhere. Per-surface support (web, Google Meet stage, Apps Script, Google Chat, MCP Apps, email, PDF) is declared PER ATOM. An atom that can't work on a target surface says so rather than degrading silently — check works_on / degraded_on / incompatible_on in the catalog entry before assuming portability.