Tokens

Token Pipeline

Tokens are authored once and compiled into multiple runtime formats. This ensures a single source of truth while supporting both SCSS authoring and runtime theming via CSS variables.

• Tokens are defined in source-tokens.ts.
• A compiler generates theme-specific CSS variables.
• SCSS token variables reference the generated CSS variables.
• Documentation reads live computed values at runtime.

Source of Truth

// src/design-system/scss/tokens/source-tokens.ts

export const baseTokens = {
  "color-primary": {
    value: "#6366f1",
    type: "color",
    group: "Brand",
    label: "Primary"
  },

  "space-4": {
    value: "16px",
    type: "size",
    group: "Spacing"
  }
};

Build Tokens

Whenever token values change, the token compiler must be run to regenerate CSS variables and SCSS token references.

npm run tokens:build

Using Tokens

Application and component styles must consume tokens exclusively through the generated SCSS token variables.

@use "@/design-system/scss/tokens" as tokens;

.button {
  background: tokens.$color-primary;
  border-radius: tokens.$radius-md;
  padding: tokens.$space-2 tokens.$space-4;
}

Governance Rules

• Tokens are the only source of truth for visual values.
• Components must never hardcode colors, spacing, or typography.
• New tokens must be added only when no existing token satisfies the requirement.
• Token values may change, but token names must remain stable.
• Theme overrides must be limited to values that truly differ.