Design System

Design System

Tools and patterns for building, managing, and auditing design systems. Covers color, typography, spacing, accessibility, and component consistency.

When to Use

• User wants to create or extend a color palette
• User wants to check WCAG contrast compliance
• User asks about typography scales or spacing systems
• User wants to audit design consistency across a project
• User wants to generate a design system from scratch

When NOT to Use

Color Systems

Generating a Color Palette

Given a primary color, generate a full scale (50-950):

// HSL-based palette generation
function generatePalette(baseHue, baseSat) {
  return {
    50:  `hsl(${baseHue}, ${baseSat}%, 97%)`,
    100: `hsl(${baseHue}, ${baseSat}%, 93%)`,
    200: `hsl(${baseHue}, ${baseSat}%, 85%)`,
    300: `hsl(${baseHue}, ${baseSat}%, 72%)`,
    400: `hsl(${baseHue}, ${baseSat}%, 60%)`,
    500: `hsl(${baseHue}, ${baseSat}%, 50%)`,
    600: `hsl(${baseHue}, ${baseSat}%, 42%)`,
    700: `hsl(${baseHue}, ${baseSat}%, 34%)`,
    800: `hsl(${baseHue}, ${baseSat}%, 26%)`,
    900: `hsl(${baseHue}, ${baseSat}%, 18%)`,
    950: `hsl(${baseHue}, ${baseSat}%, 10%)`,
  };
}

Semantic Color Mapping

primary   → Main brand color, CTAs, links
secondary → Supporting brand color
neutral   → Text, backgrounds, borders
success   → #10B981 family — confirmations, positive states
warning   → #F59E0B family — caution, pending states
error     → #EF4444 family — errors, destructive actions
info      → #3B82F6 family — informational messages

Accessibility — WCAG Contrast

Contrast Ratio Requirements

Calculating Contrast Ratio

function luminance(r, g, b) {
  const [rs, gs, bs] = [r, g, b].map(c => {
    c = c / 255;
    return c <= 0.03928 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
  });
  return 0.2126 * rs + 0.7152 * gs + 0.0722 * bs;
}

function contrastRatio(rgb1, rgb2) {
  const l1 = luminance(...rgb1);
  const l2 = luminance(...rgb2);
  const lighter = Math.max(l1, l2);
  const darker = Math.min(l1, l2);
  return (lighter + 0.05) / (darker + 0.05);
}

// Usage
const ratio = contrastRatio([255, 255, 255], [59, 130, 246]); // white on blue
// Returns ~3.44 — passes AA for large text, fails for normal text

Common Accessible Combinations

Typography Scale

Modular Scale

Common ratios for type scales:

Standard UI Type Scale (Major Third)

xs:   12px  — Captions, labels, helper text
sm:   14px  — Secondary text, table cells
base: 16px  — Body text (root)
lg:   18px  — Lead paragraphs, subheadings
xl:   20px  — Section headings (H4)
2xl:  24px  — Page subheadings (H3)
3xl:  30px  — Page headings (H2)
4xl:  36px  — Hero headings (H1)
5xl:  48px  — Display headings

Line Height Guidelines

• Headings (>= 24px): line-height: 1.2 – 1.3
• Body text (14-18px): line-height: 1.5 – 1.6
• Small text (< 14px): line-height: 1.6 – 1.8
• Single-line UI (buttons, inputs): line-height: 1

Spacing System

4px Grid (Recommended)

0:  0px      8:  32px
1:  4px      10: 40px
2:  8px      12: 48px
3:  12px     14: 56px
4:  16px     16: 64px
5:  20px     20: 80px
6:  24px     24: 96px

Spacing Usage Guidelines

Design Audit Checklist

When auditing any design or codebase for design system compliance:

1. Color consistency

   • Are all colors from the defined palette?
   • Are there one-off colors not in the system?
   • Do text colors meet WCAG AA contrast requirements?

2. Typography consistency

   • Are all text sizes from the type scale?
   • Are fonts limited to the defined font families?
   • Are font weights from the defined set?

3. Spacing consistency

   • Do padding/margins align to the spacing grid (4px or 8px)?
   • Is spacing consistent across similar components?

4. Component usage

   • Are instances used instead of detached copies?
   • Are there duplicate or near-duplicate components?
   • Are component names following naming conventions?

5. Accessibility

   • Contrast ratios for all text/background combinations
   • Touch targets >= 44x44px for interactive elements
   • Focus states defined for all interactive components

Tips

• Build the palette from a single primary hue and derive the rest systematically
• Always test contrast ratios at the actual font sizes used in the design
• Spacing should follow a consistent grid (4px is the industry standard)
• When in doubt about a color's accessibility, darken it — it's better to be safe