Design Tokens Overview

HELIX uses a three-tier design token system with CSS custom properties. Tokens are generated using a custom build pipeline (generate-css.ts) that reads tokens.json and outputs production CSS.

Three-Tier Architecture

┌────────────────────────────────────────────┐
│         Component Tokens (Tier 3)          │
│  --hx-button-bg, --hx-card-padding        │
│  Component-specific, references Semantic   │
├────────────────────────────────────────────┤
│          Semantic Tokens (Tier 2)          │
│  --hx-color-text-primary, --hx-body-bg    │
│  Semantic meaning, references Primitive    │
├────────────────────────────────────────────┤
│         Primitive Tokens (Tier 1)          │
│  --hx-color-primary-500, --hx-space-4     │
│  Raw values, brand-agnostic               │
└────────────────────────────────────────────┘

Token Categories

Category	Count	Example	Purpose
Color	8 ramps + semantic	--hx-color-primary-500	Brand, status, surface, text, border
Space	20	--hx-space-4	Padding, margins, gaps
Font	family, size, weight	--hx-font-size-lg	Font families, sizes, weights
Line Height	5	--hx-line-height-normal	Text line heights
Letter Spacing	6	--hx-letter-spacing-tight	Tracking
Border	radius + width	--hx-border-radius-md	Border radii and widths
Shadow	7	--hx-shadow-lg	Box shadows for elevation
Duration	6	--hx-duration-fast	Animation/transition durations
Easing	7	--hx-easing-default	Timing functions
Transition	3	--hx-transition-normal	Shorthand transitions
Focus	6	--hx-focus-ring-width	Focus ring styling
Z-Index	9	--hx-z-index-modal	Stacking layers
Opacity	10	--hx-opacity-disabled	Transparency levels
Size	16	--hx-size-touch-target	Fixed dimensions
Container	6	--hx-container-lg	Layout widths
Breakpoint	5	--hx-breakpoint-md	Responsive breakpoints

Theme Support

HELIX ships with three built-in themes:

1. Light — Default theme for standard usage
2. Dark — Dark mode with adjusted contrast, surfaces, and shadows
3. High Contrast — Accessibility mode for users who require enhanced contrast ratios

Themes are applied via attributes on the document root or automatically via media queries:

• Dark: data-theme="dark" or @media (prefers-color-scheme: dark)
• High Contrast: data-hx-contrast="high" or @media (prefers-contrast: more)

Build Pipeline

Tokens are defined in tokens.json and processed by generate-css.ts to output:

• :root CSS with all light-mode tokens
• @media (prefers-color-scheme: dark) overrides
• [data-theme="dark"] manual override block
• @media (prefers-contrast: more) high-contrast overrides
• [data-hx-contrast="high"] manual high-contrast block
• Lit CSSResult for shadow DOM consumption

Next Steps

• Token Tiers — Understanding each tier
• Theming — How to apply themes
• Customization — Overriding tokens for your brand