a2ui

A2UI blocks

A reply is Markdown. Where a decision, a set of inputs, a procedure, a structure or a few readings would read better as a component than as prose, write one as a fenced block: ```a2ui holding ONE JSON object, or ```mermaid holding a diagram. The Web App renders the block with its own components and theme; the CLI and the messaging channels show the same block as readable text; nothing is lost on a surface that cannot render it. You never write HTML, scripts or styles — you name a component from the catalog and fill its fields.

Before you send a reply that carries a block, run the checker (see "Check before you send"). It is the test suite for this skill: it rejects what would not render, warns about what would be hard to read, scores the draft and prints the questions a reviewer would ask.

Before you start

This skill changes how you write replies; it needs no setup. If a message only names the skill without a task — "use a2ui", "show me the blocks" — ask what the user wants to decide, enter or understand, then answer that with the fitting block. Do not demonstrate every component at once: one block that serves the question is the demonstration.

When to use a block, and when not

Use a block when it saves the reader work:

• choice — the conversation needs ONE decision from the user and you can name the realistic options (2–7, ideally 2–5). Mark one recommended when you have a view.
• form — you need SEVERAL answers at once (1–6 fields) and asking them one by one would take turns.
• steps — the user will perform a procedure by hand. One instruction per step; a warning or caution sits on the step it applies to and is rendered above it.
• callout — one thing the reader must not miss: a warning, a caution, a tip, a note. Not for ordinary paragraphs.
• mermaid — a structure or a flow with more than three parts: a pipeline, a state machine, a sequence of calls, a data model.
• weather — the user asks about the weather somewhere. Run scripts/weather.mjs <place> (see "Get real data"), paste the block it prints, and write one sentence before it.
• clock — the user asks the time somewhere, or a meeting spans time zones: one to four zones.
• countdown — a deadline or an event at a fixed instant.
• metrics — a few readings at a glance: a system snapshot (scripts/sysinfo.mjs), a quota or budget left, the progress of a job, figures with their change. Put them in ONE metrics block, never one block per number. kind says how to read a tile: reading, used, remaining or progress. worse says which way is bad (default low for remaining, else high). warn and danger colour the tile once the value passes them.