design-system

name	design-system
description	Manage and audit design system consistency — color palettes, typography scales, spacing systems, accessibility (WCAG contrast checks), and component inventory. Use when the user asks to "check contrast ratios", "audit my design system", "create a color palette", "generate a type scale", "check accessibility", "WCAG compliance", or "review design consistency".

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

Level	Normal Text (< 18px)	Large Text (>= 18px bold or >= 24px)
AA	4.5:1 minimum	3:1 minimum
AAA	7:1 minimum	4.5:1 minimum
UI components	3:1 minimum	3:1 minimum

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

Background	Text Color	Ratio	AA Normal	AA Large
#FFFFFF	#111827 (gray-900)	18.4:1	Pass	Pass
#FFFFFF	#374151 (gray-700)	10.3:1	Pass	Pass
#FFFFFF	#6B7280 (gray-500)	5.0:1	Pass	Pass
#FFFFFF	#9CA3AF (gray-400)	3.0:1	Fail	Pass
#FFFFFF	#3B82F6 (blue-500)	3.4:1	Fail	Pass
#FFFFFF	#2563EB (blue-600)	4.6:1	Pass	Pass
#111827	#FFFFFF	18.4:1	Pass	Pass
#1F2937	#D1D5DB (gray-300)	8.2:1	Pass	Pass

Typography Scale

Modular Scale

Common ratios for type scales:

Ratio	Name	Scale
1.067	Minor Second	Very tight
1.125	Major Second	Tight, good for UI
1.200	Minor Third	Balanced
1.250	Major Third	Popular default
1.333	Perfect Fourth	Generous
1.500	Perfect Fifth	Very dramatic

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

Context	Recommended Spacing
Inline elements (icon + text)	4-8px
Form field internal padding	8-12px
Between form fields	12-16px
Card internal padding	16-24px
Between cards	16-24px
Section padding	32-64px
Page margins	16-24px (mobile), 32-64px (desktop)

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