Toucan

Installation

Install the core package and a token preset. Core ships accessible React components and co-located atom CSS. Tokens provide the JSON values that the CLI compiles into CSS.

bash

npm install @toucan-ui/core @toucan-ui/tokens

Configure & Build Tokens

Add a toucan.config.json to your project root:

toucan.config.json

{
  "tokens": "@toucan-ui/tokens/presets/default",
  "outDir": "./css"
}

Then run the CLI to compile your tokens into CSS:

bash

npx toucan build

The CLI also supports .js, .mjs, and .ts config files (e.g. toucan.config.ts). CLI flags like --tokens and --out override config values.

Import the CSS

Import the compiled foundation tokens and component styles into your global stylesheet:

globals.css

/* Tokens + component CSS — compiled by `npx toucan build` */
@import './css/toucan.css';

app.tsx

// Components — each import includes its co-located CSS
import { Button, Input, Box } from '@toucan-ui/core';

Recommended App Globals

Toucan doesn't ship a CSS reset — that's your app's concern. We recommend adding these baseline styles to your global stylesheet:

globals.css

*,
*::before,
*::after {
  box-sizing: border-box;
}

body {
  margin: 0;
  font-family: var(--text-font-family);
  -webkit-font-smoothing: antialiased;
  -moz-osx-font-smoothing: grayscale;
}

Toucan components work without these, but box-sizing: border-box and the token-based font family ensure consistent rendering across your entire app.

Your First Component

With the CSS imported, every component is automatically styled through the token cascade. No className wiring, no style props, no theme provider.

app.tsx

function App() {
  return (
    <Box padding="lg" radius="md" elevation={1}>
      <Heading level={1}>Welcome</Heading>
      <Text>Your design system is ready.</Text>
      <Button variant="primary">Get started</Button>
    </Box>
  );
}

Custom Tokens

The default preset uses neutral system fonts and a balanced colour palette. To customise your tokens, use the Wiz'rd to generate custom tokens, or create your own DTCG JSON files and point your config at them:

bash

npx toucan build --tokens ./my-tokens --out ./css/toucan

See the architecture docs for details on the token tier model and the themes guide for customising your design system.

What You Get

Tokens762 CSS custom properties across 3 tiers

Components37 accessible React primitives

Patterns36 theme-agnostic layout patterns

ThemingJSON-to-CSS pipeline via the Toucan CLI

Tests1,035 unit tests passing

Next Steps

Explore the architecture to understand the three-tier token model, browse the token reference, or dive into the component docs.