Mental Model

If you start by thinking about buttons, cards, or CSS, you are already one layer too low.

Start with the core idea:

ToonUI is a contract for UI intent between the model and your application.

The one-sentence model

The model describes the interface.

Your app decides what that interface means.

That is the whole system.

The three layers

Why this matters

Without this separation, AI apps tend to collapse concerns together:

• prompt rules start carrying product logic
• rendering becomes tightly coupled to one demo
• user actions become hard to normalize
• trust boundaries become blurry

ToonUI exists to keep those layers separate ON PURPOSE.

The public objects to teach first

toon.catalog

The language contract.

Use it to understand:

• available components
• valid variants
• supported field types
• the shape of the language itself

toon.events

The interaction factory.

Use it to create normalized:

• reply payloads
• submit payloads

toon.messages

The reinjection layer.

Use it to convert interaction payloads into:

• model-friendly content
• UI-friendly display content
• chat message objects

toon.parse() and toon.validate()

The inspection and safety layer.

Use them when you need to:

• debug generation
• validate fixtures
• verify output before trusting it

toon.extractBlocks()

The separation layer.

Use it when you want to split:

• normal markdown
• structured ToonUI blocks

The key boundary

ToonUI is NOT an application framework.

It does not own:

• tools
• persistence
• authorization
• mutations
• workflows
• business rules

It gives you a typed language for interface intent and a clean path back into your application loop.

Practical example

If the model emits:

button secondary "Open details" reply="open:customer-42"

Then:

• ToonUI knows how to parse and render that
• ToonUI knows how to create the interaction payload
• your app decides whether that action fetches data, opens a modal, checks auth, or gets rejected

That is a clean architecture boundary.

What to remember

If you forget everything else, remember this:

ToonUI helps the model paint the interface, not run the product.

Next step

1. Boundaries
2. Syntax
3. Node Reference