Theming

Your DTCG tokens are the theme; the CLI turns them into application CSS.

Start with the default

With no tokenspath configured, build uses the CLI's default preset. It includes light and dark values, responsive breakpoints, semantic aliases, and every system binding required by the component CSS.

bash
pnpm exec toucan build

Create a custom theme

Copy or author a token root with raw, alias, and systemdirectories, then point the config at it. Keep the full system tier unless you intend to redefine every required component binding.

toucan.config.json
{
  "tokens": "./tokens/my-theme",
  "outDir": "./components/toucan",
  "reset": false
}

Brand changes belong in aliases

Add brand palettes at the raw tier, then map roles such as primary, surfaces, text, and borders in alias files. Use system overrides only when one component needs a structural exception.

alias/color.json
{
  "color": {
    "primary": { "$value": "{color.brand.600}", "$type": "color" },
    "primary-hover": { "$value": "{color.brand.700}", "$type": "color" },
    "on-primary": { "$value": "{color.neutral.0}", "$type": "color" }
  }
}

Dark mode

Add dark/*.json overrides. The CLI scopes the compiled values to [data-mode="dark"]; set that attribute on the document or a subtree.

ts
document.documentElement.dataset.mode = 'dark';

Rebuild, do not re-eject

Token and breakpoint edits only change generated CSS. Run build again; locally owned component source remains untouched. Review the token contract before replacing the preset.