Getting Started

Installation

Install the React primitives plus the CSS packages you import from your app. The React package depends on Toucan's shared types, interactions, and component styles; your app imports token and responsive CSS once at the global level.

npm install @toucan-ui/react @toucan-ui/tokens @toucan-ui/styles

Import the CSS

Import the default token foundation once in your global stylesheet. Add the shared responsive CSS if you use responsive Grid or Flex props. Individual component entries import their own shared component CSS.

@import '@toucan-ui/tokens/default.css';
@import '@toucan-ui/styles/responsive/default.css';

// Components — each entry imports its shared component CSS
import { Button, Input, Box } from '@toucan-ui/react';

Package Map

Most React apps install @toucan-ui/react, @toucan-ui/tokens, and @toucan-ui/styles. Add @toucan-ui/patterns only when you want larger composed sections, and add @toucan-ui/cli as a dev dependency when compiling custom token sets or ejecting local source.

# Optional pattern package
npm install @toucan-ui/patterns

/* globals.css */
@import '@toucan-ui/patterns/css';

@toucan-ui/types and @toucan-ui/interactions are first-party dependencies used by React and the CLI. App code usually does not import them directly.

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:

*,
*::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.

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 CSS uses neutral system fonts and a balanced colour palette. To customise your tokens, install the CLI as a dev dependency and use the Wiz'rd to generate custom tokens, or create your own DTCG JSON files and point your config at them:

npm install -D @toucan-ui/cli
npx toucan build --tokens ./my-tokens --out ./css/toucan

@import './css/toucan/toucan.css';

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

Full-Ownership Ejection

Package imports are the normal path. If you want editable local source for a component, use toucan eject. The CLI copies the React component source plus only the local Toucan dependencies that component needs.

npm install -D @toucan-ui/cli
npx toucan eject button
npx toucan eject select --out ./src/components --force

Ejected components still need token CSS once per app. They should not import from @toucan-ui/react after ejection.

What You Get

Next Steps

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