Episode 1 — Fundamentals / 1.6 — CSS Core Fundamentals

1.6.h — Design Systems

In one sentence: A design system is a shared vocabulary of constraints, patterns, and components that ensures visual and functional consistency across a product — CSS is the enforcement layer, custom properties and tokens are the bridge between design and code.

Navigation: ← 1.6.g — CSS Variables · 1.6.i — Design Tokens →

1. What is a design system?

A design system is more than a component library. It typically includes:

LayerWhat it contains
Design principlesBrand values, tone, accessibility commitments
Design tokensPrimitive values: colors, spacing, typography, radii, shadows
Component patternsButtons, cards, modals, forms — with states, variants, and a11y
Layout conventionsGrid system, container widths, spacing rhythm
DocumentationUsage guidelines, do/don't examples, code snippets

Goal: any designer or developer can build a new page that feels native to the product without inventing new styles.

2. Why design systems matter for CSS

Without a system, CSS codebases accumulate:

  • 200 shades of gray — each developer picks slightly different values
  • Inconsistent spacing — 12px here, 15px there, 1.2rem somewhere else
  • Specificity wars — one-off overrides pile up
  • Brittle components — styling tied to page structure, not reusable

A design system constrains choices to a finite palette of tokens — your CSS becomes predictable, reviewable, and maintainable.

3. Anatomy of a design system (CSS perspective)

Color system

:root {
  /* Primitives */
  --blue-500: #2563eb;
  --blue-600: #1d4ed8;
  --gray-100: #f1f5f9;
  --gray-900: #0f172a;

  /* Semantic aliases */
  --color-primary: var(--blue-500);
  --color-primary-hover: var(--blue-600);
  --color-bg: var(--gray-100);
  --color-text: var(--gray-900);
}

Primitives are the raw palette; semantic tokens map them to roles (primary, danger, surface). Components use semantic tokens — when the brand changes, you update the mapping, not every component.

Typography scale

:root {
  --font-sans: system-ui, -apple-system, sans-serif;
  --font-mono: ui-monospace, 'Cascadia Code', monospace;

  --text-xs: 0.75rem;     /* 12px */
  --text-sm: 0.875rem;    /* 14px */
  --text-base: 1rem;      /* 16px */
  --text-lg: 1.125rem;    /* 18px */
  --text-xl: 1.25rem;     /* 20px */
  --text-2xl: 1.5rem;     /* 24px */
  --text-3xl: 1.875rem;   /* 30px */

  --leading-tight: 1.25;
  --leading-normal: 1.5;
  --leading-relaxed: 1.75;
}

Spacing scale

:root {
  --space-1: 0.25rem;    /* 4px */
  --space-2: 0.5rem;     /* 8px */
  --space-3: 0.75rem;    /* 12px */
  --space-4: 1rem;       /* 16px */
  --space-6: 1.5rem;     /* 24px */
  --space-8: 2rem;       /* 32px */
  --space-12: 3rem;      /* 48px */
  --space-16: 4rem;      /* 64px */
}

Consistent rhythm: multiples of a base unit (4px or 8px) keep vertical and horizontal spacing harmonious.

4. Component-level patterns

A well-designed component uses system tokens, not hardcoded values:

.button {
  font-family: var(--font-sans);
  font-size: var(--text-sm);
  font-weight: 600;
  padding: var(--space-2) var(--space-4);
  border-radius: var(--radius-md);
  background-color: var(--color-primary);
  color: var(--color-on-primary);
  border: none;
  cursor: pointer;
  transition: background-color 150ms ease;
}

.button:hover {
  background-color: var(--color-primary-hover);
}

.button:focus-visible {
  outline: 2px solid var(--color-focus);
  outline-offset: 2px;
}

Benefits: changing the primary color or spacing scale updates every button automatically.

5. Design system anti-patterns

Anti-patternProblem
Using design system tokens + hardcoded values in the same componentInconsistency; tokens lose their purpose
Too many tokens (1000+ named colors)Decision fatigue; might as well not have a system
No semantic layer (using --blue-500 directly in components)Brand change requires touching every component
Building components in isolation without token constraintsDrift; components don't compose visually
Design system as "set and forget"Systems need maintenance — evolve tokens as the product evolves

6. Popular design systems (awareness)

SystemOrganizationNotes
Material DesignGoogleComprehensive spec, component libraries for multiple frameworks
Ant DesignAnt GroupEnterprise-focused, React ecosystem
CarbonIBMAccessibility-first, detailed token documentation
PrimerGitHubOpen-source, integrates with their design tokens
Chakra UICommunityReact component library with token-based theming

Study these for patterns, not to copy — your product's design system should reflect your brand and constraints.

7. Key takeaways

  1. A design system is principles + tokens + components + documentation.
  2. Tokens replace magic numbers — finite palette of colors, spacing, type.
  3. Components reference semantic tokens, not raw values — enables theming and brand evolution.
  4. Consistency reduces cognitive load for users and developers.
  5. Design systems are living — they evolve with the product.

Explain-It Challenge

Explain without notes:

  1. Why using var(--color-primary) in components is better than hardcoding #2563eb.
  2. The difference between a primitive token (--blue-500) and a semantic token (--color-primary).
  3. What problem a spacing scale (4px / 8px rhythm) solves in practice.

Navigation: ← 1.6.g — CSS Variables · 1.6.i — Design Tokens →