design-system-guide

Design System Guide

This skill provides systematic design guidance for building cohesive, production-grade interfaces. It complements (does not replace) the official frontend-design skill — use frontend-design for creative generation, use this for design system decisions and consistency.

When to Use This vs frontend-design

Scenario	Use This Skill	Use frontend-design
"Pick fonts for my SaaS app"	Yes	No
"Build me a landing page"	No	Yes
"Create a color system"	Yes	No
"Make this look better"	No	Yes
"Set up design tokens"	Yes	No
"Review design consistency"	Yes	No

Typography System

Font Pairing Strategy

Choose a display font (headings) and a body font (text). They should contrast in style but share visual weight.

Pairing archetypes:

Archetype	Display	Body	Vibe
Modern SaaS	Satoshi, General Sans	Inter, DM Sans	Clean, professional
Editorial	Playfair Display, Fraunces	Source Serif 4, Lora	Authoritative, refined
Geometric	Space Grotesk, Outfit	Work Sans, Nunito	Technical, approachable
Humanist	Bricolage Grotesque, Cabinet Grotesk	Atkinson Hyperlegible, Lexend	Warm, accessible
Mono-first	JetBrains Mono, Berkeley Mono	IBM Plex Sans, Geist	Developer, technical
Expressive	Clash Display, Zodiak	Switzer, Plus Jakarta Sans	Bold, startup

Type Scale

Use a modular scale. For most UIs, a 1.25 ratio (Major Third) works:

:root {
  --text-xs: 0.64rem;    /* 10.24px */
  --text-sm: 0.8rem;     /* 12.8px  */
  --text-base: 1rem;     /* 16px    */
  --text-lg: 1.25rem;    /* 20px    */
  --text-xl: 1.563rem;   /* 25px    */
  --text-2xl: 1.953rem;  /* 31.25px */
  --text-3xl: 2.441rem;  /* 39px    */
  --text-4xl: 3.052rem;  /* 48.8px  */
}

For more dramatic headlines, use 1.333 (Perfect Fourth) or 1.5 (Perfect Fifth).

Line Height & Spacing

• Body text: line-height: 1.5-1.7
• Headings: line-height: 1.1-1.3
• Letter spacing for headings: -0.02em to -0.04em (tighten)
• Letter spacing for small caps/labels: 0.05em to 0.1em (open up)

Color System

Building a Palette

1. Pick 1 brand color — your primary action color
2. Generate semantic scale — 50 through 950 shades
3. Add neutrals — warm gray, cool gray, or true gray depending on brand warmth
4. Define semantic tokens:

:root {
  /* Surface hierarchy */
  --bg-primary: var(--neutral-50);
  --bg-secondary: var(--neutral-100);
  --bg-tertiary: var(--neutral-200);

  /* Text hierarchy */
  --text-primary: var(--neutral-900);
  --text-secondary: var(--neutral-600);
  --text-tertiary: var(--neutral-400);

  /* Interactive */
  --accent: var(--brand-500);
  --accent-hover: var(--brand-600);
  --accent-subtle: var(--brand-50);

  /* Feedback */
  --success: #16a34a;
  --warning: #d97706;
  --error: #dc2626;
  --info: #2563eb;
}

Color Contrast

• Body text on background: minimum 4.5:1 (WCAG AA)
• Large text (18px+ bold, 24px+ regular): minimum 3:1
• UI elements (borders, icons): minimum 3:1
• Use tools like contrast-ratio.com or browser DevTools to verify

Dark Mode Strategy

Don't just invert. Instead:

• Reduce overall contrast slightly (dark backgrounds shouldn't be pure black)
• Use --neutral-950 or --neutral-900 as base, not #000
• Increase component elevation with subtle lighter backgrounds
• Reduce saturation of accent colors by ~10%

Spatial Composition

Spacing Scale

Use a consistent spacing scale based on 4px or 8px:

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

Layout Principles

• Section padding: Use generous vertical padding (--space-12 to --space-16 between sections)
• Container max-width: 1200-1400px for content, with side padding of --space-4 to --space-6
• Content width: Limit prose to 65-75 characters per line (max-width: 65ch)
• Component spacing: Related items closer, unrelated items further (Gestalt proximity)

Motion Design

Timing Functions

:root {
  --ease-in-out: cubic-bezier(0.4, 0, 0.2, 1);
  --ease-out: cubic-bezier(0, 0, 0.2, 1);
  --ease-in: cubic-bezier(0.4, 0, 1, 1);
  --ease-spring: cubic-bezier(0.34, 1.56, 0.64, 1);
}

Duration Guidelines

Action	Duration	Example
Micro-interaction	100-200ms	Button press, toggle
State change	200-300ms	Hover effects, accordion
Enter/appear	300-500ms	Modal open, page element
Exit/leave	150-250ms	Modal close, dismiss
Page transition	300-600ms	Route change

Animation Principles

• Exit faster than enter — dismissals should feel snappy
• Stagger children — 50-100ms delay between list items
• Use transform/opacity only — for smooth 60fps animations
• Respect prefers-reduced-motion — always provide a reduced-motion fallback

Design Review Checklist

When reviewing a UI, check:

• Typography hierarchy — Clear h1 > h2 > h3 progression, consistent font usage
• Color consistency — Using design tokens, not ad-hoc hex values
• Spacing rhythm — Consistent spacing scale, no magic numbers
• Interactive states — hover, focus, active, disabled for all interactive elements
• Responsive behavior — Tested at 375px, 768px, 1024px, 1440px breakpoints
• Dark mode — If supported, verified all colors and contrasts
• Loading states — Skeleton screens or spinners for async content
• Empty states — Meaningful empty state for lists, tables, search results
• Error states — Form validation, API errors, 404/500 pages
• Accessibility — Color contrast, focus rings, screen reader text

Reference Files

• references/design-tokens.md — Common token structures for Tailwind, CSS variables, and Figma