Overview

What ToonUI is

ToonUI is a UI language plus rendering runtime for AI products.

It gives the model a constrained way to describe interface intent inside chat or assistant flows.

That means the model can express:

cards
forms
buttons
option lists
guided next steps
structured summaries

But it does not mean the model owns the application.

Why ToonUI exists

Most AI products hit the same wall:

plain text is too weak for good UX, but letting the model generate arbitrary UI code is too risky and too coupled.

That creates a gap.

ToonUI exists to fill that gap with a middle layer:

structured enough to render reliably, simple enough to teach in prompts, and constrained enough to keep product boundaries clean.

The mental model

Think of ToonUI as a contract between the model and your application.

Layer	Responsibility	Owned by
Language	What the model is allowed to describe	`@toon-ui/core`
Rendering	How that description becomes React UI	`@toon-ui/react` or `@toon-ui/toon-ui`
Behavior	What happens after the user clicks or submits	Your app

What ToonUI is NOT

ToonUI is NOT:

an agent framework
a tool executor
a backend workflow engine
runtime React generation for production
a replacement for your design system
a way to move business logic into prompts

This boundary matters.

The model paints the interface.

Your app keeps the keys.

Why use ToonUI?

If you are comparing options, this is the question that matters most.

Use ToonUI because it gives your AI product a better interface layer without breaking ownership boundaries.

Better than plain text when interaction matters

Use ToonUI when the assistant should do more than explain.

Examples:

compare options
ask the user to choose
present a short form
show next actions clearly
guide a decision without making the decision for the user

Safer than generated React at runtime

If the model generates React, you now have code generation concerns mixed with product, security, and rendering concerns.

ToonUI keeps the output at the intent layer.

That makes it easier to:

validate
render predictably
keep design system ownership
preserve application boundaries

More teachable than raw JSON contracts

Raw JSON can work, but it often becomes too verbose and too low-level for prompt design.

ToonUI is purpose-built for AI-native UI, so it is easier to teach, inspect, and reason about.

Package overview

Package	What it does	Best for
`@toon-ui/core`	Protocol, catalog, parser, validation, prompts, events, messages	Server-side contract and language rules
`@toon-ui/react`	Explicit React runtime and adapter APIs	Full rendering ownership
`@toon-ui/toon-ui`	Main public client package with default adapter	Fastest path to integration
`@toon-ui/prompts`	Prompt helpers only	Custom prompt composition
`@toon-ui/cli`	CLI validation and AST inspection	CI, debugging, and tooling

Recommended learning path

If you are new, do NOT branch yet.

Use this order:

This gives you a beginning, a middle, and an end.

Read the deep reference pages only AFTER this path.

What to read later

Once the core path is clear, then go deeper:

Fastest working path

Create a protocol on the server with createToonProtocol().
Inject toon.prompt into your system prompt.
Create a client runtime with createToonClient() or createToonReactRuntime().
Render assistant output with ToonMessage or ToonRenderer.
Reinject interactions with toon.messages.toUIMessage(payload) or toon.messages.toModelMessage(payload).

This does NOT force you to use Vercel AI SDK. That is only one possible host-loop integration.

What success looks like

After the quickstart, you should have:

a model that can emit ToonUI blocks
a client that can render them
typed reply and submit payloads
a host app that still owns behavior
a cleaner AI user experience than plain text alone

Next step

Go to Start Here.

On this page