A2ui

A2UI blocks

A reply is Markdown. Where a decision, a set of inputs, a procedure or a structure 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.

Do not use a block for:

• a plain answer, a one-line fact, a yes/no;
• a conversational or emotional turn ("thanks", "sorry about that", "how was it?");
• a decision you can take yourself from the context — take it and say so;
• padding: a callout around an ordinary sentence, a diagram with two boxes, a form with one field (use a question).

Keep to one or two blocks per reply and at most two questions (choice/form). More than that is a questionnaire, not a conversation.

The catalog in brief

The full reference, every field and its limits, a valid example of each type and the common mistakes: references/components.md beside this file. Read it the first time you write a block, and whenever the checker rejects one.

The fence is ```a2ui (or ```a2ui json); one JSON object per fence; strict JSON (double quotes, no comments, no trailing commas). An unknown type or a missing required field is an error; an unknown field is ignored with a warning.

Interaction

• A choice or a form ends the reply. Nothing follows it — no closing sentence, no second question. Write what the reader needs to decide BEFORE the block; the block is the question.
• Every block is introduced by a sentence right before it ("Which store do you want?", "The request passes through three stages."). A block that arrives unexplained is a warning.
• The pick comes back as the user's next message in plain text: for a choice, the option's value (default: its label), several picks joined with 、 or ", "; for a form, one line per field, label: answer. The user can edit that text before sending, or ignore the block and type anything. Read it as you would read any user message; never expect a marker.
• allowOther: true adds an "Other…" control that just focuses the composer. Use it when your options may not cover the answer.
• Blocks in older turns are read-only; only the latest reply is interactive. Do not refer to "the buttons above" in a later turn.

Writing rules — 80% of ASD-STE100

Apply these to the prose of every reply, zh and en. They are what makes model output readable; the checker enforces the measurable ones as warnings.

1. One instruction per sentence, in the imperative: "Stop the service." / 「停止服务。」 Not "The service should be stopped first and then…".
2. Active voice. Say who does what: "The loader reads plugin.json" rather than "plugin.json is read by the loader". The checker flags be-verb + past participle in English.
3. Short sentences. English: at most 20 words in a procedure, 25 in explanation. Chinese: at most 40 characters in a procedure, 60 in explanation. One idea per sentence; split at the commas.
4. Short paragraphs. At most 5 sentences; a list when the items are a list; never a wall of text.
5. One term per concept. Pick "session" or "conversation", not both; "目录" or "文件夹", not both.
6. No vague words. Not "etc.", "and so on", "various", "appropriate", "stuff", "things"; not 「等等」「之类」「相关的」「进行」「某种程度上」. Name the items or the exact action: 「安装」, not 「进行安装」.
7. Numbers as digits. "3 files", 「3 个文件」.
8. Warnings before the step they protect, in the step's warning/caution, never after the harm.
9. Lists at most two levels deep. Deeper nesting is a sign the text wants headings or a steps block.