# Design Knowledge: Foundations, Typography & Color

Compiled from deep research across Refactoring UI, Typescale, MDN, Apple HIG, Vercel Geist, Linear Method, Material Design, and award-winning site analysis.

---

## 1. Foundational Design Principles

### Gestalt — Proximity
RULE: When elements are related, place them closer together (8-16px) than unrelated elements (24-48px+) because the brain groups nearby objects automatically. Spacing IS grouping.

### Gestalt — Similarity
RULE: When elements share the same function, apply consistent visual treatment (same color, size, weight, border-radius) because users assume similar-looking things behave the same way.

### Gestalt — Continuity
RULE: When laying out sequential content, align elements along a clear line (vertical or horizontal) because the eye follows continuous paths more easily than scattered elements.

### Gestalt — Closure
RULE: When designing cards or containers, apply subtle borders or background shifts rather than fully enclosing boxes because the brain completes incomplete shapes, and explicit enclosures add visual noise.

### Gestalt — Figure-Ground
RULE: When a modal or overlay appears, apply a semi-transparent backdrop (rgba(0,0,0,0.4-0.5)) to clearly separate foreground content from background because the user must instantly recognize what is interactive.

### Visual Hierarchy — Size Contrast
RULE: When establishing hierarchy, apply a clear size ratio between heading levels (e.g., 48px h1 → 32px h2 → 20px body at desktop) because size is the strongest hierarchy signal.

### Visual Hierarchy — Weight Contrast
RULE: When size cannot change, apply weight contrast (700 for emphasis, 400 for body) because bold text draws attention without changing layout. Never use more than 2-3 weights in a design.

### Visual Hierarchy — Color Contrast
RULE: When directing attention, apply high-contrast color for primary elements and muted color for secondary elements because contrast ratios create natural reading order.

### Visual Hierarchy — Spacing
RULE: When separating sections, apply more whitespace above a heading than below it (e.g., 48px above, 16px below) because this signals the heading belongs to the content that follows.

### Balance
RULE: When a layout feels unstable, apply visual weight balancing — large elements can be balanced by multiple small elements, dark elements by light elements with more whitespace. Symmetry is safe; deliberate asymmetry is memorable.

### Rhythm and Repetition
RULE: When building a page with multiple sections, apply consistent internal spacing (same padding, same gap, same heading-to-content ratio) across all sections because repetition creates rhythm, and rhythm creates cohesion.

### Proportion — Golden Ratio (1.618)
RULE: When dividing space, apply the golden ratio for content/sidebar splits (e.g., main content ~62%, sidebar ~38%) because this proportion is naturally pleasing and prevents equal-split blandness.

### Proportion — Rule of Thirds
RULE: When placing focal elements in a hero, position them at one-third division points (33% or 67% from edges) rather than center because off-center composition creates more dynamic layouts.

### Emphasis — Single Focal Point
RULE: When designing a section, ensure exactly ONE element is the most visually prominent (largest, brightest, highest contrast) because multiple competing focal points create confusion.

### Unity
RULE: When building a multi-section page, apply a consistent color palette, type scale, spacing system, and border-radius across all sections because consistency is what makes separate sections feel like one design.

---

## 2. Typography

### Type Scale Ratios
RULE: When choosing a type scale, apply one of these ratios based on content density:
- **1.067 (Minor Second)** — dense data-heavy UIs with many levels
- **1.125 (Major Second)** — standard UIs, safe default
- **1.200 (Minor Third)** — medium contrast, good for marketing
- **1.250 (Major Third)** — strong contrast, good for landing pages
- **1.333 (Perfect Fourth)** — editorial/content sites
- **1.414 (Augmented Fourth)** — dramatic contrast, hero-heavy pages
- **1.500 (Perfect Fifth)** — very dramatic, use sparingly
- **1.618 (Golden Ratio)** — maximum contrast, single-purpose pages

because the scale ratio controls how dramatically sizes escalate from body to headings.

### Font Pairing
RULE: When pairing fonts, apply contrast in classification (serif with sans-serif, geometric with humanist) while maintaining similar x-height because pairing two similar sans-serifs creates invisible difference, while pairing a display serif with a clean sans creates memorable contrast.

### Font Pairing — Award-Winning Combinations
From Awwwards winners:
- Hedvig Letters Serif + Fragment Mono (editorial + technical)
- Canela + Graphik (warm editorial + clean UI)
- Druk + ABC Diatype (bold display + neutral UI)
- Domaine Display + Favorit (elegant + modern)
- Playfair Display + Source Sans (classic + functional)
- Instrument Serif + Geist Sans (contemporary editorial)

### X-Height and Readability
RULE: When choosing a body font, prefer fonts with large x-height (like Inter, Geist, DM Sans) for UI text because large x-height improves readability at small sizes. For display headings, fonts with smaller x-height (like Playfair, Didot) create elegance.

### Line Height
RULE: When setting line-height, apply 1.5-1.75 for body text (16px base), 1.2-1.4 for medium headings, and 1.0-1.15 for large display headings because larger text needs proportionally less leading — tight leading on large text looks cramped.

### Letter Spacing (Tracking)
RULE: When adjusting letter-spacing, apply negative tracking (-0.02em to -0.05em) for large headings (24px+), zero tracking for body text (14-18px), and positive tracking (0.05em to 0.1em) for uppercase/small caps because tighter tracking on large text improves perceived cohesion.

### Measure (Line Length)
RULE: When setting content width, apply 45-75 characters per line for body text because lines shorter than 45 characters feel choppy and lines longer than 75 characters cause eye fatigue. For optimal readability: 680-760px at 16px body text.

### Weight Hierarchy
RULE: When using font weights, apply maximum 2-3 weights: 400 (body), 500 (emphasis/labels), 600-700 (headings) because using 4+ weights creates visual noise. Use size and color for additional hierarchy, not more weights.

### Responsive Typography
RULE: When scaling typography across breakpoints, apply a fluid scale using `clamp()`: `font-size: clamp(2rem, 5vw, 3.5rem)` for headings because fluid type scales smoothly without breakpoint jumps. Scale headings aggressively (2x from mobile to desktop) but body text conservatively (16px → 18px max).

### Type Classification — When to Use What
- **Grotesque/Neo-grotesque** (Inter, Geist, Helvetica, Univers) — UI text, neutral interfaces, developer tools
- **Humanist** (FF Meta, Source Sans, Lato) — friendly products, education, healthcare
- **Geometric** (Futura, Avenir, DM Sans) — modern tech, startups, minimalism
- **Old Style Serif** (Garamond, Caslon) — editorial, long-form reading, luxury
- **Transitional Serif** (Baskerville, Charter) — traditional editorial, formal
- **Modern/Didone Serif** (Didot, Bodoni, Playfair) — fashion, luxury, display only
- **Slab Serif** (Roboto Slab, Arvo) — bold statements, headlines
- **Monospace** (JetBrains Mono, Fragment Mono, IBM Plex Mono) — code, technical details, timestamps

### Apple HIG Typography Values (Reference)
Desktop: 48px h1, line-height 1.08365, letter-spacing -0.003em, max-width 502px
Tablet: 40px h1, line-height 1.1, letter-spacing 0
Mobile: 32px h1, line-height 1.125, letter-spacing 0.004em
Container: 980px desktop, 692px tablet, 87.5% mobile

---

## 3. Color Theory

### OKLCH Color Space
RULE: When generating palettes programmatically, use OKLCH color space because it provides perceptually uniform lightness (unlike HSL where "50% lightness" varies wildly by hue) and allows mathematical palette generation that actually looks harmonious. In OKLCH: L (lightness 0-1), C (chroma 0-0.4), H (hue 0-360).

### Palette Generation from Seed
RULE: When generating a palette from a project name/category seed:
1. Hash the seed string to a number
2. Map to OKLCH hue (0-360) — this gives unique base color per project
3. Generate 10 shades: vary L from 0.15 to 0.95 in 0.09 increments, keep C and H constant
4. Generate accent: shift H by ±30° (complementary), ±150° (triadic), or ±120° (split-complementary)
because OKLCH ensures all shades maintain perceptual consistency.

### Color Harmony Algorithms
RULE: When deriving accent colors from a base:
- **Complementary**: H ± 180° — maximum contrast, use sparingly for CTAs
- **Split-complementary**: H ± 150° + H ± 210° — contrast with more nuance
- **Triadic**: H ± 120° — vibrant, use for multi-accent systems
- **Tetradic**: H ± 90° + H ± 180° — complex, requires one dominant
- **Analogous**: H ± 30° — harmonious, low contrast, for backgrounds/depth
because mathematical harmony produces better results than "choosing vibes."

### Palette Construction — 60-30-10 Rule
RULE: When distributing color across a page, apply 60% dominant (background), 30% secondary (cards, sections), 10% accent (CTAs, highlights) because this ratio creates visual interest without chaos.

### Neutral Palette
RULE: When generating neutrals, apply a slight hue tint matching the primary color (warm neutrals for warm palettes, cool neutrals for cool palettes) because pure gray (#888) feels dead against saturated colors. Warm neutral: OKLCH L=varies, C=0.01, H=base_hue. Cool neutral: C=0.01, H=base_hue+180.

### Dark Mode Palette
RULE: When constructing dark mode, do NOT invert light mode. Instead: use L=0.15-0.20 for background (not pure black), L=0.90-0.95 for primary text (not pure white), reduce chroma by 20-30% for all colors, and increase padding/spacing by 8-12% because colors appear more saturated on dark backgrounds.

### Contrast Ratios — WCAG
RULE: When applying text colors, ensure:
- Body text (< 18px): minimum 4.5:1 contrast ratio (WCAG AA)
- Large text (≥ 18px bold or ≥ 24px): minimum 3:1
- UI components and graphical objects: minimum 3:1
because lower contrast fails accessibility and reduces readability for everyone.

### Color Psychology (Research-Backed)
RULE: When selecting base hues by category:
- **Technology/Developer tools**: Blue (#0066FF range) — trust, reliability
- **Finance/Fintech**: Green or deep blue — security, growth
- **Health/Fitness**: Green or teal — vitality, health
- **Creative/Design**: Purple or magenta — creativity, distinction
- **Food/Restaurant**: Warm reds/oranges — appetite, warmth
- **Education**: Blue or teal — learning, calm
- **Luxury**: Black, gold, deep burgundy — sophistication
- **Security**: Dark blue, dark gray — trust, authority
because color associations are culturally reinforced, not arbitrary.

### Accent Color Selection
RULE: When choosing an accent from a base, pick the complementary or split-complementary hue with high chroma (C=0.2-0.3 in OKLCH) because the accent must "pop" against both the dominant and neutral colors. The accent should be reserved for CTAs, active states, and key highlights only.

### Refactoring UI Color Rules
RULE: Use HSL (not hex) for reasoning about color because HSL makes relationships visible (same H, different S/L = shades).
RULE: Define 10 shades per color upfront because real interfaces need many variations.
RULE: Increase saturation slightly on lighter shades because lightening washes out color.
RULE: Greys should carry a tint of the primary hue because pure grey feels disconnected.
