Building Harness Design System

Export-Tokens: Design Token Transformation Documentation

Overview

The packages/core-design-system/scripts folder contains the essential build system that transforms our design tokens into CSS custom properties (variables). This conversion process is critical for making our design system accessible to the front-end implementation.

flowchart LR
    A["Token Sources (Core, Brand, Mode)"] --> B["Token Transformation"]
    B --> C["Build System (Style Dictionary & @token-studio)"]
    C --> D["Output (CSS/TypeScript)"]
    D --> E["UI Packages & Applications"]

Loading

Key Components

Build System Files

• build.js: The main orchestration script that processes design tokens and converts them to CSS variables. It leverages Token Studio's transformation capabilities and Style Dictionary to generate the appropriate CSS files.

• sd-file-generators.js: Utility module that defines file generation strategies for different token types. It contains two main functions:

  • generateCoreFiles(): Creates CSS files for core design tokens (typography, spacing, etc.)
  • generateThemeFiles(): Creates CSS files for theme-specific tokens (light mode, dark mode, etc.)

• sd-filters.js: Contains filtering functions that determine which tokens should be included in specific output files. These filters help organize tokens by category:

  • Core tokens filter
  • Color tokens filter
  • Breakpoint tokens filter
  • Component tokens filter
  • Semantic tokens filter

• constants.js: Centralizes configuration values such as:

  • Output file paths for generated CSS files
  • CSS variable prefix (DESIGN_SYSTEM_PREFIX variable contains the value)
  • Design system root directory paths

• complete-log.js: Helper utility for consistent logging during the build process.

Technical Implementation

The build process uses two primary npm packages:

1. @tokens-studio/sd-transforms: Extends Style Dictionary with Token Studio's transformation capabilities, allowing for advanced token processing and permutation of themes.

2. style-dictionary: The foundational library that handles token transformation across platforms. Our implementation focuses on the CSS output format.

Generated Output

The build system generates several CSS files in the src/styles/ directory:

• core.css: Contains base design tokens like typography, spacing, and dimensions
• colors.css: Contains all color tokens transformed from LCH format
• breakpoint.css: Contains responsive design breakpoint tokens
• components.css: Contains component-specific design tokens

Theme based files:

• oss.css: Entry point that imports all themes for OSS edition.
• enterprise.css: Entry point that imports all themes for enterprise edition (Harness).

Each file contains CSS custom properties with the prefix --cn- followed by the token path.

Usage

To transform design tokens into CSS variables:

1. Run the build command:

pnpm build

2. This command:

• Clears the existing design system CSS files
• Executes the build.js script
• Processes all tokens from the design-tokens folder
• Generates new CSS files with proper CSS variable declarations

3. The generated CSS variables can then be imported and used throughout the UI components.

Build Process Flow

1. Read the $themes.json configuration file
2. Generate theme permutations based on configuration
3. Identify theme-specific and core tokensets
4. Process tokens using Style Dictionary and Token Studio transforms
5. Apply appropriate filters to categorize tokens
6. Generate CSS output files using the defined file generators
7. Create an index file that imports all generated CSS files

Best Practices

• Always run pnpm build after updating changes to design tokens
• Do not update the design tokens manually. The UX team will handle all token updates themselves.
• Use the generated CSS variables in components. Hardcoded/Arbitrary values should not be used.
• When adding new token types, update the appropriate filter in sd-filters.js

⚠️ IMPORTANT NOTE:

Do not update the design tokens manually. The UX team will handle all token updates themselves. The build process (pnpm build) should only be run after the UX team has made their changes to the design tokens.