Design Systems

A design system is a single source of truth for an interface's reusable design decisions — colours, spacing, typography, and component styles — and in CSS it is commonly built from design tokens stored as custom properties ( var(--token) ) so the whole product stays consistent and easy to re-theme.

Part of the free HTML & CSS course at LearnCodingFast — hands-on lessons with examples you run in your browser, plus practice exercises and a quick quiz.

What You'll Learn

💡 Think of It Like This

A design system is like a LEGO set — each brick (token) has a specific size, color, and shape. Instead of sculpting every element from scratch, you assemble consistent UIs by snapping tokens together. Changing a token is like swapping the color of a LEGO brick: every structure using it updates at once.

Understanding Design Systems

A design system is a collection of reusable decisions — colors, spacing, typography, component patterns — encoded as CSS custom properties (also called "design tokens"). Instead of scattering #1976D2 across 50 files, you define it once as --color-primary and reference it everywhere.

This approach has three major benefits: consistency (every button uses the same blue), maintainability (change the blue once, everything updates), and theming (swap all tokens at once for dark mode or branding).

Design tokens are organized in layers. Primitive tokens are raw values like --blue-500: #1976D2 . Semantic tokens give them meaning: --color-primary: var(--blue-500) . Component tokens scope to specific elements: --btn-bg: var(--color-primary) . This layering makes large codebases manageable.

Token Naming Convention

Layer

Example

Purpose

When to Use

Primitive

--blue-500

Raw color value

Never directly in components

Semantic

--color-primary

Role-based reference

In most CSS rules

Component

--btn-bg

Scoped to a component

For complex component variants

Spacing

--space-4

Consistent whitespace

All padding, margin, gap values

Step 1: Define Your Tokens

Start by defining all your visual decisions in :root . This includes colors, spacing, typography, and border radii. The editor below shows a complete token set with a visual swatch grid.

Step 2: Build Components with Tokens

Once tokens are defined, every component references them instead of hardcoded values. Notice how .btn-primary uses var(--color-primary) and .card uses var(--color-surface) . If you change --color-primary from blue to purple, every button and accent updates automatically.

Step 3: Establish a Spacing Scale

A spacing scale eliminates "magic numbers" — those arbitrary pixel values like padding: 13px that creep into CSS. Instead, every spacing value comes from a predefined scale (4, 8, 12, 16, 24, 32, 48, 64px). This creates visual rhythm and makes your layouts feel cohesive.

Step 4: Add Theme Switching

The ultimate payoff of a token-based system is effortless theming . By overriding tokens inside a [data-theme] attribute selector, you can switch every color in your UI with a single attribute change. No class toggling, no JavaScript manipulation of individual elements — just change the data attribute and the cascade does the rest.

When to Use Design Systems

• Any project with more than one page — Even small sites benefit from centralized tokens for consistency.
• Team projects — Tokens are a shared vocabulary that prevents "which blue?" conversations.
• Products with theming needs — Dark mode, white-label branding, or seasonal themes become trivial.
• Not needed for: One-off prototypes or single-page experiments where speed matters more than maintainability.

⚠️ Common Mistakes

• Too many tokens too early — Start with 10–15 core tokens. Add more only when you notice repetition across 3+ places.
• Using raw values in components — Always reference tokens: color: var(--color-primary) , never color: #1976D2 .
• Forgetting fallbacks — var(--color-primary, blue) prevents breakage if a token is missing.
• Inconsistent naming — Pick one convention and stick with it. Don't mix --clr-primary and --color-main .
• Skipping the spacing scale — Without it, every developer invents their own padding values, creating visual inconsistency.
• Not documenting tokens — Create a reference page (like the swatch grid above) so the team knows what's available.

🎉 Lesson Complete

• ✅ Design tokens centralize all visual decisions in :root
• ✅ Primitive → Semantic → Component is the standard token layering
• ✅ A spacing scale (4, 8, 16, 24, 32…) eliminates magic numbers
• ✅ Components use only tokens, making themes a simple override
• ✅ [data-theme] attribute enables instant multi-theme switching
• ✅ Start small: 10-15 tokens cover most projects initially
• ✅ Always provide fallback values with var(--token, fallback)
• ✅ Document your tokens visually so the team has a shared reference

Practice quiz

Continue this course

• Previous: Advanced Selectors Deep
• Next: Responsive Images