Foundations
Design Tokens
DS0 uses W3C DTCG format design tokens that cascade from core through semantic to theme and brand layers.
Overview
Design tokens are the atomic values that define the visual language of DS0. They replace magic numbers with meaningful names and enable consistent theming, density customization, and multi-platform output from a single source of truth.
Core Tokens
Raw values (gray-500, blue-600)
Semantic Tokens
Mapped meanings (primary, destructive)
Component Tokens
Per-component overrides (button-bg)
Token Architecture
DS0 tokens cascade through four layers, each more specific than the last:
tokens/_core/ → Mathematical foundations (scales, ratios, raw palette)
tokens/_semantic/ → Intent-based mappings (primary, destructive, muted)
tokens/themes/ → Theme overrides (default, enterprise, playful)
tokens/brands/ → Brand-specific overrides (extend a theme)Resolution order: _core → _semantic → theme → brand → component-level override
Layer 1: Core Tokens
Core tokens define the raw values. They have no semantic meaning — blue.500 is just a color, not "primary":
{
"color": {
"blue": {
"500": { "$type": "color", "$value": "#3B82F6" }
}
},
"spacing": {
"4": { "$type": "dimension", "$value": "16px" }
}
}Layer 2: Semantic Tokens
Semantic tokens map core values to intent. This is where "primary" gets its meaning:
{
"color": {
"primary": { "$type": "color", "$value": "{color.blue.500}" },
"destructive": { "$type": "color", "$value": "{color.red.500}" },
"background": { "$type": "color", "$value": "{color.white}" },
"foreground": { "$type": "color", "$value": "{color.gray.950}" }
}
}Layer 3: Theme Tokens
Theme tokens override semantic values. The dark theme flips backgrounds and foregrounds:
{
"color": {
"background": { "$type": "color", "$value": "{color.gray.950}" },
"foreground": { "$type": "color", "$value": "{color.gray.50}" },
"card": { "$type": "color", "$value": "{color.gray.900}" },
"primary": { "$type": "color", "$value": "{color.blue.400}" }
}
}Resolution Example
When a component uses var(--ds0-color-primary):
| Layer | Value | Why |
|---|---|---|
| Core | #3B82F6 | Raw blue.500 |
| Semantic | {color.blue.500} → #3B82F6 | Maps "primary" to blue |
| Default Theme | (no override) | Inherits semantic |
| Dark Theme | {color.blue.400} → #60A5FA | Lighter blue for dark backgrounds |
Token Categories
| Category | Examples | Source File |
|---|---|---|
| Color | color.blue.500, color.primary | color.json, _semantic/color.json |
| Spacing | spacing.4 = 16px | spacing.json |
| Typography | font-size.base = 16px | typography.json |
| Radius | radius.md = 6px | radius.json |
| Elevation | elevation.md | elevation.json |
| Motion | duration.normal = 150ms | motion.json |
Using Tokens in Components
CSS Custom Properties
.my-card {
background: var(--ds0-color-card);
border-radius: var(--ds0-radius-md);
padding: var(--ds0-spacing-4);
box-shadow: var(--ds0-elevation-sm);
}Tailwind Classes
DS0 tokens are available as Tailwind utilities via the preset:
<div className="bg-card text-card-foreground rounded-md p-4 shadow-sm">
Content
</div>JavaScript (for tooling)
import tokens from '@ds0/tokens/json';
console.log(tokens.color.primary); // "#3B82F6"Token Format (W3C DTCG)
All source tokens use the W3C Design Token Community Group format:
{
"color": {
"blue": {
"500": {
"$type": "color",
"$value": "#3B82F6",
"$description": "Primary blue"
}
}
}
}Build Pipeline
Tokens are processed by StyleDictionary into multiple output formats:
- CSS Custom Properties —
@ds0/tokens/css - Dark Mode Overrides —
@ds0/tokens/css/dark-mode.css - Tailwind Theme Preset —
@ds0/tokens/tailwind - React Native Styles —
@ds0/tokens/react-native - Flat JSON —
@ds0/tokens/json
Extending Tokens
To add a custom token:
- Add it to the appropriate JSON file in
tokens/ - Run
pnpm build:tokensto regenerate outputs - Use via
var(--ds0-your-token)in CSS or the Tailwind preset
To create a brand theme:
- Create
tokens/brands/your-brand.json - Override only the semantic tokens you want to change
- Import the generated CSS alongside the base tokens
All Tokens
| Token | Value | Preview |
|---|---|---|
| ColorWhite | #ffffff | |
| ColorBlack | #000000 | |
| ColorGray50 | #f9fafb | |
| ColorGray100 | #f3f4f6 | |
| ColorGray200 | #e5e7eb | |
| ColorGray300 | #d1d5db | |
| ColorGray400 | #9ca3af | |
| ColorGray500 | #6b7280 | |
| ColorGray600 | #4b5563 | |
| ColorGray700 | #374151 | |
| ColorGray800 | #1f2937 | |
| ColorGray900 | #111827 | |
| ColorGray950 | #030712 | |
| ColorBlue50 | #eff6ff | |
| ColorBlue100 | #dbeafe | |
| ColorBlue200 | #bfdbfe | |
| ColorBlue300 | #93c5fd | |
| ColorBlue400 | #60a5fa | |
| ColorBlue500 | #3b82f6 | |
| ColorBlue600 | #2563eb | |
| ColorBlue700 | #1d4ed8 | |
| ColorBlue800 | #1e40af | |
| ColorBlue900 | #1e3a8a | |
| ColorBlue950 | #172554 | |
| ColorRed50 | #fef2f2 | |
| ColorRed100 | #fee2e2 | |
| ColorRed200 | #fecaca | |
| ColorRed300 | #fca5a5 | |
| ColorRed400 | #f87171 | |
| ColorRed500 | #ef4444 | |
| ColorRed600 | #dc2626 | |
| ColorRed700 | #b91c1c | |
| ColorRed800 | #991b1b | |
| ColorRed900 | #7f1d1d | |
| ColorRed950 | #450a0a | |
| ColorGreen50 | #f0fdf4 | |
| ColorGreen100 | #dcfce7 | |
| ColorGreen200 | #bbf7d0 | |
| ColorGreen300 | #86efac | |
| ColorGreen400 | #4ade80 | |
| ColorGreen500 | #22c55e | |
| ColorGreen600 | #16a34a | |
| ColorGreen700 | #15803d | |
| ColorGreen800 | #166534 | |
| ColorGreen900 | #14532d | |
| ColorGreen950 | #052e16 | |
| ColorAmber50 | #fffbeb | |
| ColorAmber100 | #fef3c7 | |
| ColorAmber200 | #fde68a | |
| ColorAmber300 | #fcd34d | |
| ColorAmber400 | #fbbf24 | |
| ColorAmber500 | #f59e0b | |
| ColorAmber600 | #d97706 | |
| ColorAmber700 | #b45309 | |
| ColorAmber800 | #92400e | |
| ColorAmber900 | #78350f | |
| ColorAmber950 | #451a03 | |
| ColorViolet50 | #f5f3ff | |
| ColorViolet100 | #ede9fe | |
| ColorViolet200 | #ddd6fe | |
| ColorViolet300 | #c4b5fd | |
| ColorViolet400 | #a78bfa | |
| ColorViolet500 | #8b5cf6 | |
| ColorViolet600 | #7c3aed | |
| ColorViolet700 | #6d28d9 | |
| ColorViolet800 | #5b21b6 | |
| ColorViolet900 | #4c1d95 | |
| ColorViolet950 | #2e1065 | |
| ColorIndigo50 | #eef2ff | |
| ColorIndigo100 | #e0e7ff | |
| ColorIndigo200 | #c7d2fe | |
| ColorIndigo300 | #a5b4fc | |
| ColorIndigo400 | #818cf8 | |
| ColorIndigo500 | #6366f1 | |
| ColorIndigo600 | #4f46e5 | |
| ColorIndigo700 | #4338ca | |
| ColorIndigo800 | #3730a3 | |
| ColorIndigo900 | #312e81 | |
| ColorIndigo950 | #1e1b4b | |
| ColorCyan50 | #ecfeff | |
| ColorCyan100 | #cffafe | |
| ColorCyan200 | #a5f3fc | |
| ColorCyan300 | #67e8f9 | |
| ColorCyan400 | #22d3ee | |
| ColorCyan500 | #06b6d4 | |
| ColorCyan600 | #0891b2 | |
| ColorCyan700 | #0e7490 | |
| ColorCyan800 | #155e75 | |
| ColorCyan900 | #164e63 | |
| ColorCyan950 | #083344 | |
| ColorTeal50 | #f0fdfa | |
| ColorTeal100 | #ccfbf1 | |
| ColorTeal200 | #99f6e4 | |
| ColorTeal300 | #5eead4 | |
| ColorTeal400 | #2dd4bf | |
| ColorTeal500 | #14b8a6 | |
| ColorTeal600 | #0d9488 | |
| ColorTeal700 | #0f766e | |
| ColorTeal800 | #115e59 | |
| ColorTeal900 | #134e4a | |
| ColorTeal950 | #042f2e | |
| ColorPink50 | #fdf2f8 | |
| ColorPink100 | #fce7f3 | |
| ColorPink200 | #fbcfe8 | |
| ColorPink300 | #f9a8d4 | |
| ColorPink400 | #f472b6 | |
| ColorPink500 | #ec4899 | |
| ColorPink600 | #db2777 | |
| ColorPink700 | #be185d | |
| ColorPink800 | #9d174d | |
| ColorPink900 | #831843 | |
| ColorPink950 | #500724 | |
| ColorOrange50 | #fff7ed | |
| ColorOrange100 | #ffedd5 | |
| ColorOrange200 | #fed7aa | |
| ColorOrange300 | #fdba74 | |
| ColorOrange400 | #fb923c | |
| ColorOrange500 | #f97316 | |
| ColorOrange600 | #ea580c | |
| ColorOrange700 | #c2410c | |
| ColorOrange800 | #9a3412 | |
| ColorOrange900 | #7c2d12 | |
| ColorOrange950 | #431407 | |
| ColorBackground | #ffffff | |
| ColorForeground | #030712 | |
| ColorMuted | #f3f4f6 | |
| ColorMutedForeground | #6b7280 | |
| ColorCard | #ffffff | |
| ColorCardForeground | #030712 | |
| ColorPopover | #ffffff | |
| ColorPopoverForeground | #030712 | |
| ColorPrimary | #2563eb | |
| ColorPrimaryForeground | #ffffff | |
| ColorSecondary | #f3f4f6 | |
| ColorSecondaryForeground | #111827 | |
| ColorAccent | #f3f4f6 | |
| ColorAccentForeground | #111827 | |
| ColorDestructive | #dc2626 | |
| ColorDestructiveForeground | #ffffff | |
| ColorSuccess | #16a34a | |
| ColorSuccessForeground | #ffffff | |
| ColorWarning | #f59e0b | |
| ColorWarningForeground | #451a03 | |
| ColorBorder | #e5e7eb | |
| ColorInput | #e5e7eb | |
| ColorRing | #60a5fa |