Toucan

Installation

Install the core packages with your package manager. The tokens package provides CSS custom properties and atom styles. The core package provides React components.

bash

pnpm add @toucan-ui/tokens @toucan-ui/core

Two Imports

Every application starts with two imports: tokens (the visual foundation) and components (the structure).

app.tsx

// 1. Base tokens + atom CSS (ground zero)
import '@toucan-ui/tokens/css';

// 2. Components (structure + accessibility)
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>
  );
}

Theming

Themes override tokens via a data-theme attribute on any ancestor element. See the Themes guide for details on creating custom themes.

What You Get

Tokens762 CSS custom properties across 3 tiers

Components37 accessible React primitives

Patterns36 theme-agnostic layout patterns

ThemingToken override model with data-theme selectors

Tests1,035 unit tests passing

Next Steps

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