AI Authoring Rules

This is the shortest correct mental model:

The AI writes normal markdown plus valid toon-ui blocks, using ONLY the official catalog and canonical syntax.

If the model is uncertain, it must simplify. It must NOT improvise.

Quick path

1. Write normal markdown when plain prose is enough.
2. Add a fenced toon-ui block when the user needs structured UI.
3. Use only official components, official variants, and canonical syntax.
4. If unsure, fall back to a smaller safe subset like card, text, table, form, confirm, or list.

Hard rules

• Output markdown + optional toon-ui fenced blocks only
• Never output React
• Never output HTML
• Never output CSS
• Never output JavaScript
• Never output component JSON
• Never invent components
• Never invent props
• Never emit raw HTML or scripts inside text
• Never execute business actions directly

Official components only

Allowed today:

• text
• heading
• separator
• card
• form
• field
• button
• confirm
• list
• item
• badge
• alert
• table
• empty
• tabs
• accordion
• dialog
• sheet
• popover
• tooltip
• progress
• loading
• toast
• breadcrumb
• pagination
• menu
• command
• chart

Structural child nodes are ALSO part of the canonical language, but only inside the correct parent:

• crumb inside breadcrumb
• action inside menu and command
• tab inside tabs
• section inside accordion
• series inside chart
• point inside series

Never invent pseudo-components like:

• header
• footer
• subtitle
• description
• input
• modal
• stack
• grid
• divider

Canonical syntax

text "Visible text"
heading <1-6> "Visible text"
separator
separator horizontal
separator vertical
card "Title" [description="..."]:
form "Title" [description="..."]:
field <name> <fieldType> "Label" [placeholder="..."] [helper="..."] [required] [options="A|B"] [min=<number>] [max=<number>] [step=<number>] [value="..."]
button <variant> "Label" reply="Value"
button <variant> "Label" submit
confirm <variant> "Title" [trigger="..."] [description="..."]:
list "Title":
item "Title" [description="..."]:
badge "Label" <variant>
alert <variant> "Title" [description="..."]:
table "Title":
empty "Title" [description="..."]:
tabs "Title":
tab "Label":
accordion "Title":
section "Title":
dialog "Title" [trigger="..."] [description="..."]:
sheet "Title" [trigger="..."] side="left|right|top|bottom":
popover "Title" [trigger="..."]:
tooltip "Visible text" [trigger="..."]
progress "Label" value=<number> max=<number>
loading "Visible text"
toast <variant> "Visible text"
breadcrumb:
crumb "Label" [reply="Value"]
pagination page=<number> totalPages=<number>
menu "Title":
action "Label" reply="Value"
action "Label" submit
action "Label" reply="Value" variant="secondary"
command "Title" [trigger="..."]:
action "Label" reply="Value"
action "Label" submit
chart <type> "Title" [description="..."] [x="..."] [y="..."]:
series "Label":
point "Label" <number>

Required rules by component

Quoted titles

These nodes always require a quoted title:

• card
• form
• confirm
• list
• item
• alert
• table
• empty
• tabs
• accordion
• dialog
• sheet
• popover
• menu
• command
• chart

Required structure

Fields are data-capture controls. They belong inside form.

Wrong:

dialog "Contact customer" description="Send a message to the customer.":
  field message textarea "Message" required
  button primary "Send" submit

Correct:

dialog "Contact customer" description="Send a message to the customer.":
  form "Customer message" description="Write the message before sending.":
    field message textarea "Message" required
    button primary "Send" submit

If a submit is incomplete, do not rebuild the full original form. Ask only for the missing or invalid fields and preserve the valid submitted values in conversation state.

description rule

Use description="..." ONLY on:

• card
• form
• alert
• confirm
• dialog
• item
• empty
• chart

Do NOT invent description for other nodes.

Variants and families

Button variants

• primary
• secondary
• danger
• ghost
• outline

Badge variants

• success
• warning
• danger
• neutral
• info

Alert variants

• info
• success
• warning
• danger

Confirm variants

• neutral
• info
• warning
• danger
• success

Chart types

• bar
• line
• area
• pie

Field types

• text
• email
• number
• password
• date
• time
• textarea
• select
• checkbox
• radio
• switch
• combobox
• otp
• slider
• multiselect

Table rules

Tables must use:

• columns:
• row:

And every column and cell should be quoted. This matters MOST when values contain commas, currency, or large numbers.

Correct example:

table "Sales":
  columns: "Date", "Sale number", "Total", "Status"
  row: "May 14", "177877222574876", "$ 387.45", "Completed"

UI decision rules

Prefer ToonUI instead of plain markdown when the user needs to:

• choose
• confirm
• complete structured data
• view structured results
• compare values
• navigate options

Decision defaults:

• if 2 or more structured inputs are needed, use form
• if there are multiple results, prefer table or list
• if one entity needs a next action, prefer card plus buttons
• if the action is destructive, prefer confirm danger
• if the action is risky but not destructive, prefer confirm warning

Never ask “do you want me to build a UI?” when it is already obvious that UI is the right response.

Composition rules

• Prioritize useful UI, not explanation about UI
• Prefer one focused ToonUI block per intent
• Keep actions close to the data they affect
• Prefer simple trees over unnecessary nesting
• Use empty for empty states
• Use chart only for trend/comparison analysis
• If syntax confidence drops, fall back to simpler valid nodes

What NOT to do

These anti-patterns are important because AI systems often copy visible patterns literally.

Do NOT invent components

Wrong:

header "Customer"
grid:
  text "Name"

Why it is wrong:

• header and grid are not official ToonUI nodes

Do NOT omit explicit actions

Wrong:

button primary "Create product" "start-create-product"
action "Open reports" "open-reports"

Correct:

button primary "Create product" reply="start-create-product"
action "Open reports" reply="open-reports"

Why it is wrong:

• button and action require reply="..." or submit

Do NOT use structural child nodes outside their parent

Wrong:

tab "Summary":
  text "Active"

Correct:

tabs "Customer profile":
  tab "Summary":
    text "Active"

Why it is wrong:

• tab, section, crumb, action, series, and point are structural child nodes
• they only work inside their valid parent

Do NOT create incomplete containers

Wrong:

form "Create product":
  field name text "Name"

Why it is wrong:

• form needs at least one field
• form also needs a submit button

Wrong:

alert "Low stock"

Why it is wrong:

• alert needs a variant, a quoted title, optional description="...", :, and nested children

Do NOT use unquoted field defaults

Wrong:

field active switch "Active" value=true
field score slider "Score" min=0 max=10 step=1 value=7

Correct:

field active switch "Active" value="true"
field score slider "Score" min=0 max=10 step=1 value="7"

Why it is wrong:

• the parser reads field defaults from quoted value="...", and @toon-ui/react uses that value as the initial rendered input value

Do NOT leave table cells ambiguous

Risky:

row: May 09, $ 8,155.35, Completed

Correct:

row: "May 09", "$ 8,155.35", "Completed"

Why it is wrong:

• commas inside values can break parsing intent
• quote every table column and cell

Do NOT ask prose questions when UI is obvious

Bad:

Do you want me to build a form for this?

Better:

form "Create product":
  field name text "Name" required
  field price number "Price" required
  button primary "Create product" submit

Why it is wrong:

• when structured input is already needed, ToonUI should reduce back-and-forth

Language rule

Prompt instructions may be in English, but visible UI copy should follow the user's language:

• labels
• titles
• button text
• field labels

Related docs

1. Syntax
2. Catalog
3. Prompt API