Toucan

How the Cascade Works

Tokens flow through three tiers with strict referencing direction. Raw tokens hold primitive values. Alias tokens add semantic meaning. System tokens bind to specific components.

css

Raw:    --color-blue-500: #3b82f6
Alias:  --color-primary: var(--color-blue-500)
System: --button-primary-surface-default: var(--color-primary)
CSS:    .tcn-button-primary { background: var(--button-primary-surface-default) }

A theme overrides at the system tier by picking different raw values. The component CSS never changes.

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. Themes remap these.

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 bind to specific components using the surface/on-surface convention. Each component has tokens for background, text color, border, and size variants.

ButtonInputTextareaSelectCheckboxToggleRadioSurfaceTextBadgeAlertAvatarSeparatorSkeletonProgressBreadcrumbTableTabsTooltipPopoverDropdownDialogFocus

Example: Button Tokens

css

--button-primary-surface-default     → var(--color-primary)
--button-primary-surface-hover       → var(--color-primary-hover)
--button-primary-on-surface-default  → var(--color-on-primary)
--button-secondary-surface-default   → var(--color-surface-default)
--button-ghost-surface-default       → transparent
--button-radius                      → var(--radius-md)
--button-sm-padding                  → var(--scale-1) var(--scale-3)
--button-md-padding                  → var(--scale-2) var(--scale-4)
--button-lg-padding                  → var(--scale-3) var(--scale-6)

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)