Understanding Design Tokens in Modern Web Development

Design tokens are the foundational building blocks of a consistent, maintainable design system. They store visual design attributes — colors, typography, spacing, shadows — as named, reusable values that can be referenced across your entire application.

Why Design Tokens Matter

Traditional CSS often leads to scattered values: #007bff here, #0069d9 there, maybe 1.5rem in one place and 24px in another. This creates inconsistency and makes rebranding a nightmare.

Design tokens solve this by centralizing every visual decision into a single source of truth. Change one value, and the entire site updates.

Our Approach: CSS Custom Properties + OKLCH

Our template uses two modern CSS technologies:

CSS Custom Properties (Variables): --color-brand: oklch(55% 0.2 265) — defined once, used everywhere.

OKLCH Color Space: A perceptually uniform color space that produces consistently beautiful color palettes. Unlike hex or RGB, OKLCH lets you:

• Adjust lightness predictably
• Create harmonious color scales
• Ensure accessible contrast ratios

Color Derivation with color-mix()

Instead of hardcoding every shade, we derive them:

--color-brand: oklch(55% 0.2 265);
--color-brand-hover: color-mix(in oklab, var(--color-brand), black 15%);
--color-brand-light: color-mix(in oklab, var(--color-brand), white 85%);

This means editing --color-brand alone cascades through every derived token automatically.

The 14 Token Groups

Our design token system is organized into 14 groups:

1. Brand — primary brand color, accent, derived interacts
2. Surface — page background, card, elevated surfaces
3. Text — primary, secondary, muted, inverse
4. Border — default and hover border colors
5. CTA — call-to-action button colors
6. Feedback — success, warning, error, info
7. Social — brand colors for social media links
8. Typography — font families, sizes, line heights
9. Spacing — consistent spacing scale (4px base unit)
10. Radius — border radius scale
11. Shadows — elevation shadows for cards, modals, dropdowns
12. Animation — transition durations and easing functions
13. Z-Index — stacking order for overlays, modals, tooltips
14. Decorative — accent patterns, gradients, dividers

Dark Mode Architecture

Dark mode uses the .dark class selector. When the user's system preference is prefers-color-scheme: dark, or they toggle it manually, the .dark class overrides surface and text tokens while keeping brand colors intact:

.dark {
  --color-surface: oklch(20% 0.01 265);
  --color-text: oklch(90% 0.01 265);
  --color-border: oklch(30% 0.01 265);
}

Rebranding in 60 Seconds

To completely rebrand this template:

1. Open src/styles/tokens.css
2. Change --color-brand, --color-accent, --color-bg, --color-text at the top
3. Adjust --font-sans and --text-hero if needed
4. Done — every derived token, hover state, and component updates automatically

Accessibility Built In

Design tokens are chosen with WCAG 2.1 AA contrast ratios in mind. The OKLCH color space makes it easy to verify that text meets the 4.5:1 contrast ratio requirement, and the token system enforces consistent accessible spacing.

Conclusion

Design tokens transform a static stylesheet into a living design system. By centralizing every visual decision, you gain consistency, maintainability, and the ability to rebrand in minutes instead of days.