token-system

name

token-system

description

OUDS design token system rules and architecture. Use this skill when working with tokens, adding new component tokens, debugging undefined token errors, working on dark mode, editing _variables.scss, or touching any file in packages/*/scss/tokens/. Covers the 3-tier hierarchy (raw→semantic→component), CSS custom property bridge for dark mode, auto-generated file protections, import order, and the color-mode mixin. For deep architecture details, read references/architecture.md.

Token System

Why tokens matter

The token system makes one codebase serve 3 brands. Component SCSS uses token variables → each brand provides different values → same SCSS produces different visual output. Breaking the token contract breaks multi-brand.

---

Token hierarchy

Raw ($core-ouds-*)       → never use in components
  ↓
Semantic ($ouds-space-*) → use for non-color values
  ↓
Component ($ouds-btn-*)  → preferred when available
  ↓
CSS custom props (--bs-color-*) → use for ALL colors (dark mode)

---

Rules

1. Component tokens first, then semantic

// ✓ component token
@include border-radius($ouds-button-border-radius-default);

// ✓ no component token → semantic fallback
@include border-radius($ouds-border-radius-default);

2. CSS custom properties for ALL colors

Colors come in light/dark pairs → exposed as CSS custom props → runtime switching.

// ✓
color: var(--#{$prefix}color-content-default);

// ✗ locked to one mode
color: $ouds-color-content-default-light;

3. Never use raw tokens

$core-ouds-*, $core-orange-*, $core-sosh-* — no semantic meaning, breaks on redesign.

4. Never edit auto-generated files

Read-only per brand: _raw.scss, _semantic.scss, _component.scss, _*-custom-props.scss

Only _composite.scss is hand-editable (elevation, fonts, SVG icons, Sass maps).

5. Import order is critical

_raw → _semantic → _semantic-colors-custom-props → _composite → _component-colors-custom-props → _component

6. New tokens → all 3 brands

Add to all: packages/orange/, packages/sosh/, packages/orange-compact/. Each brand can have different values. Temporary fallbacks go in scss/_variables.scss with // TODO:.

7. Use color-mode() for theme declarations

@include color-mode(light, true) {
  --#{$prefix}color-action-enabled: #{$ouds-color-action-enabled-light};
}
@include color-mode(dark) {
  --#{$prefix}color-action-enabled: #{$ouds-color-action-enabled-dark};
}

---

Naming convention

Layer	Pattern	Example
Raw	$core-ouds-{cat}-{scale}	$core-ouds-border-radius-200
Semantic	$ouds-{cat}-{variant}	$ouds-border-radius-default
Component	$ouds-{comp}-{cat}-{variant}	$ouds-button-border-radius-default
CSS prop	--{$prefix}{cat}-{name}	--bs-color-action-enabled

---

Deep reference

For the full pipeline (Figma → DTCG → Style Dictionary → SCSS), layer-by-layer explanation, and color flow diagrams, read references/architecture.md in this skill directory.