Architecture

A narrow public boundary: CLI in, local CSS and source out.

The application boundary

Input

One CLI

The application installs @toucan-ui/cli as a development dependency.

Build

Canonical assets

The CLI carries token data, CSS inputs, component source, types, and interactions.

Output

Local ownership

The app receives one CSS file and editable source with no Toucan runtime imports.

One-way flow

text
@toucan-ui/cli
  ├─ toucan build  → components/toucan/_toucan/styles/toucan.css
  └─ toucan eject  → components/toucan/<group> + shared _toucan source

application
  ├─ imports toucan.css once
  └─ imports components from local group barrels

This boundary is deliberate. Internal authoring packages are not application APIs, and the documentation never asks consumers to install or import them.

Token flow

DTCG JSON references flow in one direction: raw primitives to semantic aliases to system bindings. The compiler validates that direction before producing CSS variables.

text
raw/color.json
  color.blue.600 = #2563eb

alias/color.json
  color.primary = {color.blue.600}

system/button.json
  button.radius = {radius.md}

Responsive contract

Responsive props use the fixed mobile-first keys sm, md, lg, and xl. Their values come from the active raw/breakpoint.json and are regenerated by every build.

Source ownership

bash
pnpm exec toucan eject select

Ejection computes the selected group's dependency closure, rewrites internal imports to local paths, copies component CSS, and protects changed files. Once copied, that code is part of the application and can diverge intentionally.