Semantic Token Taxonomy
Three-tier token architecture. Primitives name raw values. Semantic tokens name intent. Component tokens are scoped aliases. Components consume only semantic tokens — never primitives, never raw values.
--bh-*--bh-red: #D42020--ds-*--ds-color-agency: var(--bh-red)--ds-btn-*--ds-btn-primary-bg: var(--ds-surface-inverse)Color Tokens
Color communicates meaning, not aesthetics. Three semantic pillars, three outcome levels, one error state.
Three semantic pillars. Color communicates meaning — never decoration. Each pillar has a base, subtle tint, and foreground variant.
| Token | Value | Primitive | Description | |
|---|---|---|---|---|
--ds-color-agency | #D42020 | --bh-red | AI authority, active states, destructive actions, agent-initiated events | copy |
--ds-color-agency-subtle | #FFEBEB | — | Tinted surface behind agency content — badges, banners, hover states | copy |
--ds-color-agency-fg | #FFFFFF | --bh-white | Foreground (text/icon) on agency-colored backgrounds | copy |
--ds-color-temporal | #2B44D4 | --bh-blue | Processing, in-flight, informational, historical, links | copy |
--ds-color-temporal-subtle | #EBEBFF | — | Tinted surface behind temporal content | copy |
--ds-color-temporal-fg | #FFFFFF | --bh-white | Foreground on temporal-colored backgrounds | copy |
--ds-color-validation | #C49A1A | --bh-yellow | Enrichment, quality signals, caution, threshold proximity, confirmation | copy |
--ds-color-validation-subtle | #FFF0C8 | — | Tinted surface behind validation content | copy |
--ds-color-validation-fg | #18181B | --bh-black | Foreground on validation-colored backgrounds (dark for contrast on gold) | copy |
Spacing Tokens
8px base unit. Three axis groups: inset (padding), stack (vertical gap), inline (horizontal gap).
| Token | Value | Primitive | Description | |
|---|---|---|---|---|
--ds-space-inset-xs | 4px | Compact: icon padding, tight badge insets | copy | |
--ds-space-inset-sm | 8px | Small: button padding block, chip insets | copy | |
--ds-space-inset-md | 12px 16px | Default: card padding, panel insets | copy | |
--ds-space-inset-lg | 16px 24px | Spacious: dialog body, section padding | copy | |
--ds-space-stack-xs | 4px | Tight vertical rhythm: label → input | copy | |
--ds-space-stack-sm | 8px | Normal vertical rhythm: form fields | copy | |
--ds-space-stack-md | 16px | Section spacing: groups of controls | copy | |
--ds-space-stack-lg | 24px | Page section spacing | copy | |
--ds-space-stack-xl | 40px | Major page sections, template spacing | copy | |
--ds-space-inline-xs | 4px | Icon + label gap | copy | |
--ds-space-inline-sm | 8px | Button icon + text gap, badge padding | copy | |
--ds-space-inline-md | 16px | Default column gap | copy | |
--ds-space-inline-lg | 24px | Card grid gap | copy |
Typography Tokens
Font families and type scale. Numbers, codes, amounts, and IDs must use the mono font with tabular-nums.
| Token | Value | Primitive | Description | |
|---|---|---|---|---|
--ds-type-display-font | var(--font-inter, system-ui) | Display / heading typeface | copy | |
--ds-type-body-font | var(--font-inter, system-ui) | Body / prose typeface | copy | |
--ds-type-mono-font | var(--font-mono, 'JetBrains Mono') | Monospace: numbers, codes, IDs, amounts | copy | |
--ds-type-label-font | var(--font-inter, system-ui) | Label typeface (uppercase, tracked) | copy | |
--ds-type-size-hero | 40px | Hero headline | copy | |
--ds-type-size-h1 | 36px | Page title | copy | |
--ds-type-size-h2 | 22px | Section heading | copy | |
--ds-type-size-h3 | 17px | Subsection heading | copy | |
--ds-type-size-body | 15px | Body text | copy | |
--ds-type-size-label | 11px | Labels, overlines (min 10px floor) | copy | |
--ds-type-size-caption | 11px | Captions, metadata | copy |
What Changed in v2
Taxonomy refinements, new tokens, and renamed aliases. See the migration guide for codemods and step-by-step upgrade instructions.
Naming Convention
Components must reference --ds-* semantic tokens. Semantic tokens reference --bh-* primitives. Raw hex values and primitive tokens are banned in component CSS. This indirection is what makes theming, dark mode, and white-labeling work.