Toucan

Directory contract

Directory	Role	Contains
`raw/`	Primitive values	Colour palettes, scale, layout, typography, shadow, opacity, z-index, and breakpoints.
`alias/`	Semantic roles	Primary, surfaces, text, borders, focus, sizing, spacing, radius, elevation, and typography roles.
`system/`	Component bindings	Component-specific dimensions and structural decisions consumed by copied CSS.
`dark/`	Mode overrides	Optional values compiled under [data-mode="dark"].

The raw, alias, and system directories are required. Dark is optional.

DTCG shape

Every leaf uses a $value and an appropriate $type. References use brace notation.

json

{
  "color": {
    "brand": {
      "600": { "$value": "#2563eb", "$type": "color" }
    },
    "primary": { "$value": "{color.brand.600}", "$type": "color" }
  }
}

Reference direction

text

raw      concrete values only
alias    may reference raw
system   may reference raw or alias
dark     overrides active values for dark mode

The CLI fails the build when system references cannot be resolved or the tier contract is invalid.

Breakpoints

Responsive components require all four keys, one shared unit, positive values, and strictly increasing widths.

raw/breakpoint.json

{
  "breakpoint": {
    "sm": { "$value": "640px", "$type": "dimension" },
    "md": { "$value": "768px", "$type": "dimension" },
    "lg": { "$value": "1024px", "$type": "dimension" },
    "xl": { "$value": "1280px", "$type": "dimension" }
  }
}

Use custom tokens

toucan.config.json

{
  "tokens": "./tokens",
  "outDir": "./components/toucan",
  "reset": false
}

Application code still uses the CLI. Direct access to the published JSON preset is only for advanced design-token tooling; see token tooling.