Getting started

From an existing React app to locally owned Toucan components.

1. Install the CLI

React and React DOM stay in your application. The CLI is the only Toucan package an app installs. Toucan uses pnpm in its own repository and shows pnpm first, but npm is fully supported for consuming the CLI.

bash
pnpm add -D @toucan-ui/cli

2. Initialise

Initialise once. The command detects the local project and writes the canonical JSON configuration.

bash
pnpm exec toucan init
toucan.config.json
{
  "outDir": "./components/toucan",
  "reset": false
}

3. Build the CSS

Build compiles the CLI's default token preset and responsive rules into one file below your configured Toucan root.

bash
pnpm exec toucan build
globals.css
/* app/globals.css */
@import './components/toucan/_toucan/styles/toucan.css';

4. Eject component source

Eject copies the selected group's React source, CSS, types, interactions, and shared helpers. Generated code imports React and React DOM only; there is no Toucan runtime.

bash
pnpm exec toucan eject button box heading text

5. Import locally

welcome.tsx
import { Box } from '@/components/toucan/box';
import { Button } from '@/components/toucan/button';
import { Heading } from '@/components/toucan/heading';
import { Text } from '@/components/toucan/text';

export function Welcome() {
  return (
    <Box padding="lg" radius="md" elevation={1}>
      <Heading level={1}>Welcome</Heading>
      <Text>Your local design system is ready.</Text>
      <Button>Continue</Button>
    </Box>
  );
}

6. Verify

bash
pnpm exec toucan doctor

Continue with the CLI reference or choose a group from the component reference.