Overview

This tracking issue covers the integration of design tokens into Blueprint, replacing hardcoded Sass variables with CSS custom properties to enable improved theming flexibility and consistency across the design system.

Design tokens provide a single source of truth for Blueprint's visual language—colors, spacing, typography, shadows, and more—defined as JSON and compiled to CSS custom properties (prefixed --bp-). This enables consistent theming across different color schemes without duplicating style logic in each component.

Goals

• Theming flexibility: Enable light/dark mode switching and custom theme support through CSS custom properties
• Consistency: Establish a shared vocabulary of semantic tokens across all components
• Modern CSS: Leverage CSS relative color syntax (oklch(from ...)) for dynamic color derivations
• Standards compliance: Follow the Design Tokens Community Group (DTCG) specification

Token Architecture

Tokens are organized into semantic categories:

Source files are located in packages/core/src/design-tokens/tokens/:

• base/ — Core token definitions (palette, intent, surface, typography, emphasis)
• themes/dark/ — Dark mode overrides

Tokens are built using Style Dictionary with custom transforms for Blueprint-specific features like color derivation.

Key Technical Decisions

• Color space: OKLCH for color interpolation, providing perceptually uniform color mixing
• Relative color syntax: Dynamic color derivations using oklch(from var(...) l c h / alpha) for hover/active states
• Intent tokens: Map semantic meaning (primary, success, warning, danger) to interaction states (rest, hover, active, disabled)
• Surface layers: Composable background layers using linear-gradient() trick for stacking semi-transparent tints
• Dark mode: Theme-specific token overrides rather than duplicated component logic

Browser Compatibility

Relative color syntax requires:

Implementation Progress

Completed

• Token infrastructure and build system
• Core token definitions (palette, intent, surface, typography, emphasis)
• Dark mode token overrides -- Dark mode token overrides #7830
• Button component migration — [core] Integrating design tokens into core for buttons #7727

In Progress

• Tag/CompoundTag component migration — [core] Integrating design tokens into tag #7817

Planned

• Additional core components (Card, Callout, Dialog, etc.)
• Form components (Input, Select, Checkbox, etc.)
• Documentation and migration guide

Visual Changes

Components migrated to design tokens may have subtle visual differences due to:

• OKLCH color space interpolation vs. RGB
• Relative color syntax for hover/active states
• Unified token-based derivations replacing component-specific calculations

These changes maintain the overall Blueprint aesthetic while ensuring consistency across the design system.

Related Links

• Documentation: packages/core/src/design-tokens/README.md
• Usage guide: packages/core/src/design-tokens/USAGE.md