Design Tokens

Design Tokens are design values (colors, sizes, spacing) defined as variables. By referencing token names (--color-primary) instead of raw values (#1E40AF), we ensure consistency and maintainability.

Token Hierarchy

Global Tokens (Raw values)

Lowest level. Defines raw color/size values

--blue-600: #2563EB

Semantic Tokens (Purpose-based)

Abstraction based on meaning/purpose

--color-primary: var(--blue-600)

Component Tokens (Component-specific)

Component-specific tokens applied to component parts

--button-primary-bg: var(--color-primary)

Why Token Hierarchy?

Problem	Solution via Token Hierarchy
"Change blue" → 100 edits	Change Global Token in 1 place
"Change only Primary button color"	Change Component Token, no side effects
"What does this blue mean?"	Semantic Token name conveys intent
"Add dark mode support"	Switch Semantic Tokens by theme

Naming Convention

--{category}-{property}-{variant}-{state}

Part	Description	Example
category	Token category	color, spacing, radius, shadow
property	Specific property	background, border, text
variant	Variation (optional)	primary, secondary, muted
state	State (optional)	hover, active, disabled

Examples:

--color-background          /* category + property */
--color-background-muted    /* + variant */
--color-border-input-focus  /* + state */

Tailwind CSS v4 Integration

Tailwind CSS v4 deeply integrates with CSS custom properties.

Tailwind Class	CSS Variable	Value
bg-background	var(--background)	#FFFFFF
text-foreground	var(--foreground)	#0A0A0A
bg-primary	var(--primary)	#1E3A8A
text-muted-foreground	var(--muted-foreground)	#737373
border-input	var(--input)	#E5E5E5
ring-ring	var(--ring)	#3B82F6