Design Tokens

Design tokens are the visual source of truth for spacing, typography, color, radii, and shadows.

Token Strategy

ShockStack uses layered token sources:

  • base primitives for shared values
  • multiple built-in theme palettes
  • custom overrides for project-specific changes

This keeps the design language consistent while still allowing local customization.

Build Flow

pnpm tokens:build

The token build generates:

  • CSS variables for runtime theming
  • JavaScript/TypeScript exports for app usage
  • JSON artifacts for tooling and integrations

Frontend Integration

Generated tokens are imported into global styles and mapped to semantic utilities.
Components then consume semantic classes rather than hardcoded color values.

Theme Switching

Theme switching is controlled through a root data-theme attribute.

Because utilities map to semantic token names, the UI can switch themes without changing component markup.

Customization Workflow

  1. Update token sources
  2. Rebuild tokens
  3. Verify styles in both themes
  4. Commit generated outputs with source changes

Treat token updates like API changes for the design system: prefer semantic naming and avoid one-off values.