Deeper Architecture
Package Architecture
Understand how the ToonUI packages fit together and which one to adopt first.
ToonUI is split by responsibility, not by marketing.
That is a GOOD thing.
It keeps server concerns, rendering concerns, and tooling concerns from bleeding into each other.
Package map
| Package | Responsibility | Best for |
|---|---|---|
@toon-ui/core | Protocol, catalog, parser, validation, prompts, events, messages | Server-side contract |
@toon-ui/toon-ui | Main client package with default adapter | Fastest integration path |
@toon-ui/react | Explicit React runtime and adapter APIs | Design-system ownership |
@toon-ui/prompts | Prompt helpers only | Custom prompt composition |
@toon-ui/cli | Validation and AST tooling | CI, fixtures, debugging |
Default architecture
Most teams should start here:
server -> @toon-ui/core
client -> @toon-ui/toon-uiWhy:
- minimal setup
- clean defaults
- fast path to a real product integration
Explicit architecture
Use this when the frontend team needs full rendering control:
server -> @toon-ui/core
client -> @toon-ui/react
adapter -> your componentsWhy:
- explicit adapter ownership
- tighter design-system integration
- stricter coverage guarantees
How to choose
Choose @toon-ui/toon-ui if you want speed
Best when:
- you want a working system quickly
- the default adapter is acceptable
- you may customize only a few components later
Choose @toon-ui/react if you want control
Best when:
- your team already owns a component system
- rendering standards matter a lot
- missing coverage should be explicit
Architecture principle
The package split reflects the actual system design:
- the server teaches the language
- the client renders the language
- the host app owns behavior
- tooling validates the language
That is the real architecture.