Tokens

762 CSS custom properties across three tiers. Browse the full token inventory.

How the Cascade Works

Tokens flow through three tiers with strict referencing direction. Raw tokens hold primitive values. Alias tokens (the base theme) add semantic meaning. System tokens bind to specific components. All three tiers ship as foundation CSS with @toucan-ui/core.

css
/* Colors — alias tokens used directly in atom CSS */
Raw:    --color-neutral-900: #171717
Alias:  --color-primary: var(--color-neutral-900)    ← base theme default
CSS:    .tcn-button[data-variant="primary"] { background-color: var(--color-primary) }

/* Structure — system tokens add component-specific tuning */
Raw:    --radius-md: 0.5rem
System: --button-radius: var(--radius-md)
CSS:    .tcn-button { border-radius: var(--button-radius) }

Custom tokens remap at the alias tier by pointing semantic roles to different raw values. Colors flow directly from alias to atom CSS. Structural properties (sizing, spacing, radius) route through system tokens for per-component tuning.

Colors

Primitive color scales. No semantic meaning — just values.

Blue
--color-blue-50
--color-blue-100
--color-blue-500
--color-blue-600
--color-blue-700
Neutral
--color-neutral-0
--color-neutral-50
--color-neutral-100
--color-neutral-200
--color-neutral-300
--color-neutral-400
--color-neutral-500
--color-neutral-600
--color-neutral-700
--color-neutral-800
--color-neutral-900
--color-neutral-950
Red
--color-red-50
--color-red-100
--color-red-500
--color-red-600
--color-red-700
Green
--color-green-50
--color-green-100
--color-green-500
--color-green-600
--color-green-700
Amber
--color-amber-50
--color-amber-100
--color-amber-500
--color-amber-600
--color-amber-700
Cyan
--color-cyan-50
--color-cyan-100
--color-cyan-500
--color-cyan-600
--color-cyan-700

Scale

Unified spatial scale for spacing, sizing, and gaps. Key × 4 = pixels.

--scale-0(0px)
--scale-0-25(1px)
--scale-0-5(2px)
--scale-1(4px)
--scale-2(8px)
--scale-3(12px)
--scale-4(16px)
--scale-5(20px)
--scale-6(24px)
--scale-7(28px)
--scale-8(32px)
--scale-9(36px)
--scale-10(40px)
--scale-11(44px)
--scale-12(48px)
--scale-16(64px)

Layout

Layout-scale tokens for larger dimensions — widths, max-widths, breakpoints. Key × 4 = pixels.

--layout-20(80px)
--layout-40(160px)
--layout-45(180px)
--layout-50(200px)
--layout-60(240px)
--layout-70(280px)
--layout-80(320px)
--layout-120(480px)
--layout-140(560px)
--layout-192(768px)
--layout-240(960px)
--layout-256(1024px)
--layout-300(1200px)
--layout-320(1280px)

Other Raw Categories

Typography (11 font sizes, 4 weights, 3 families, 4 line heights), Radius (5 steps), Shadow (4 levels), Border widths, Z-index, Opacity, Motion, and Letter spacing.

Color Aliases

Semantic color roles that reference raw values. The base theme fills every slot with neutral defaults. Branded themes override these to express a different identity.

Primary
--color-primary
--color-primary-hover
--color-primary-active
--color-on-primary
Surface
--color-surface-default
--color-surface-muted
--color-surface-raised
On Surface
--color-on-surface-default
--color-on-surface-muted
Border
--color-border-default
--color-border-strong
--color-border-focus
Semantic
--color-danger
--color-danger-surface
--color-success
--color-success-surface
--color-warning
--color-warning-surface
--color-info
--color-info-surface
State
--color-disabled
--color-on-disabled
--color-backdrop

Typography Aliases

Font family, weight, and sizing tokens for text, headings, and display text.

--text-font-family(see computed value)
--text-font-family-mono(see computed value)
--heading-font-weight(see computed value)
--heading-letter-spacing(see computed value)
--display-font-family(see computed value)
--display-font-weight(see computed value)
--display-letter-spacing(see computed value)
--display-line-height(see computed value)
--body-font-weight(see computed value)
--body-font-size(see computed value)
--body-line-height(see computed value)
--body-letter-spacing(see computed value)

Component Tokens

System tokens handle structural properties — sizing, spacing, radius, font weight — giving each component its own tuning knobs. For colors, atom CSS references alias tokens directly so customisations cascade without extra indirection.

ButtonInputTextareaSelectCheckboxToggleRadioSurfaceTextBadgeAlertAvatarSeparatorSkeletonProgressBreadcrumbTableTabsTooltipPopoverDropdownDialogFocus

Example: Button Tokens

Structural system tokens consumed by button atom CSS:

css
--button-radius       → var(--radius-md)
--button-font-weight  → var(--font-weight-medium)
--button-gap          → var(--spacing-sm)
--button-border-width → var(--border-width-thin)
--button-sm-height    → var(--sizing-md)
--button-sm-padding-x → var(--spacing-md)
--button-md-height    → var(--sizing-lg)
--button-md-padding-x → var(--spacing-lg)
--button-lg-height    → var(--sizing-xl)
--button-lg-padding-x → var(--spacing-xl)

Colors reference alias tokens directly in atom CSS:

css
.tcn-button[data-variant="primary"] {
  background-color: var(--color-primary);
  color: var(--color-on-primary);
}

Example: Surface Tokens

css
--surface-background    → var(--color-surface-default)
--surface-border        → var(--color-border-default)
--surface-border-width  → var(--border-width-thin)
--surface-elevation-0   → var(--shadow-none)
--surface-elevation-1   → var(--shadow-sm)
--surface-elevation-2   → var(--shadow-md)
--surface-elevation-3   → var(--shadow-lg)
--surface-radius-sm     → var(--radius-sm)
--surface-radius-md     → var(--radius-md)
--surface-radius-lg     → var(--radius-lg)