Design System Guidelines

This document outlines the systematic design principles for this Eleventy site, inspired by Swiss design methodology (Otl Aicher, Josef Müller-Brockmann), web-native design (Frank Chimero), and typographic clarity (Erik Spiekermann).

Core Principles

1. Systematic over arbitrary - All spacing, typography, and layout decisions follow a mathematical foundation
2. Content-first design - Work with the web's grain, not against it
3. Functional hierarchy - Visual relationships communicate meaning
4. Comfortable, not rigid - Systems serve readability, not academic perfection

Typography

Type Scale

Uses a Minor Second (1.067) ratio - subtle, readable progression.

--type-size-9: 1.793rem    (~28.7px) - Large headlines
--type-size-7: 1.476rem    (~23.6px) - Section headings
--type-size-3: 1.138rem    (~18.2px) - Subheadings
--type-size-1: 1rem        (16px)    - Body text
--type-size-small: 0.878rem (~14px)  - Captions, metadata

Line Heights

• Headlines (h1, h2): 1.2–1.3 (tight, for impact)
• Body text: 1.5 (comfortable reading)
• Small text: 1.4 (maintains readability at smaller sizes)

Key rule: Use unitless line-heights (e.g., 1.5 not 1.5rem) so they scale with font size changes.

Fluid Font Sizing

Base font size scales fluidly with viewport:

font-size: clamp(100%, 2vw, 137.5%);

• Mobile: 16px (100%)
• Scales smoothly with viewport width
• Desktop: ~22px (137.5%)

Optimal Line Length

• Body text: 50ch max (45–75 characters per line)
• Prevents eye fatigue on wide screens
• Natural constraint for readability

Spacing System

All spacing uses multiples of a base unit system for visual consistency.

Spacing Scale

--space-3xs: 0.25rem   (4px)   - Micro adjustments
--space-2xs: 0.5rem    (8px)   - Tight coupling
--space-xs:  0.75rem   (12px)  - Close relationships
--space-s:   1rem      (16px)  - Related content
--space-m:   1.5rem    (24px)  - Default rhythm (baseline)
--space-l:   2rem      (32px)  - Section spacing
--space-xl:  2.5rem    (40px)  - Larger sections
--space-2xl: 3rem      (48px)  - Major breaks
--space-3xl: 4rem      (64px)  - Page sections
--space-6xl: 8rem      (128px) - Page regions

Spacing Classes

Modern (recommended for new work)

<div class="flow">        <!-- Default 1.5rem spacing -->
<div class="flow-tight">  <!-- 0.5rem - tight coupling -->
<div class="flow-s">      <!-- 1rem - related content -->
<div class="flow-l">      <!-- 2rem - section spacing -->

Legacy (backward compatibility)

<div class="stack-xs">    <!-- 0.5rem / 8px -->
<div class="stack-s">     <!-- 1rem / 16px -->
<div class="stack-m">     <!-- 1.5rem / 24px -->
<div class="stack-l">     <!-- 2rem / 32px -->

Spacing Hierarchy Rules

Tight coupling (0.5–1rem) - Elements that belong together:

• Heading → immediately following content
• Label → form input
• Icon → label text

Medium spacing (1.5–2rem) - Related but distinct:

• Paragraph → paragraph
• List items
• Form fields

Large spacing (3–4rem) - Section breaks:

• Major content blocks
• Article sections
• Page regions

Visual example:

Heading                    ← Title
↕ 0.5rem (tight)          ← Belongs to heading
Content starts here...     ← Content

↕ 1.5rem (medium)         ← Paragraph separation

Next paragraph here...     ← Related content

↕ 4rem (large)            ← Section break

## New Section               ← Distinct topic

Grid & Layout

Container

• Max width: 55rem (~880px at 16px base, ~1210px at 22px)
• Padding: 1rem (16px) mobile, maintains consistency
• Centered: Auto margins for central alignment

Content Measure

• Text blocks constrained to 50ch for readability
• Prevents excessively long lines
• Applied to headings, paragraphs, list items

Grid System

12-column grid for complex layouts:

.grid {
    display: grid;
    grid-template-columns: repeat(12, 1fr);
    column-gap: 1.5rem;
    row-gap: 2.5rem;
}

• Mobile: Full width (12 columns)
• Tablet: Half width (6 columns)
• Desktop: Thirds or quarters (4/3 columns)

Vertical Rhythm

Article Spacing

article > * + *           → 3rem (48px) - Default article spacing
article > p + p           → 1.5rem (24px) - Paragraph flow
article > h2 + *          → 1rem (16px) - Heading to content (tight)
article > p + h3          → 2rem (32px) - Content to heading (space)

Why this matters:

• Large spacing between major elements creates breathing room
• Tight spacing after headings shows visual belonging
• Medium spacing between paragraphs maintains flow without breaking rhythm

Section Spacing

.main > section + section → 5rem mobile, 8rem desktop

Clear visual breaks between major page regions.

Color System

Semantic Naming

--color-text:           #141f0a  - Primary text
--color-text-secondary: #374d21  - Links, accents
--color-text-muted:     #000000  - Secondary text
--color-border:         #d5d5d5  - Borders, separators
--color-surface:        #FAF9F7  - Cards, backgrounds
--color-canvas:         #FFFEFC  - Page background

Legacy Aliases (for compatibility)

--color-100 → --color-text
--color-70  → --color-text-muted
--color-30  → --color-border
--color-10  → --color-surface

Design note: Semantic names (text, border, surface) are clearer than numeric scales (100, 70, 30).

Breakpoints

Three systematic breakpoints cover most responsive needs:

--bp-sm: 40rem   (640px)  - Tablet
--bp-md: 60rem   (960px)  - Small desktop
--bp-lg: 80rem   (1280px) - Large desktop

Why only three?

• Fewer breakpoints = simpler maintenance
• Content-driven, not device-driven
• Covers: mobile → tablet → desktop

Avoid:

• Arbitrary pixel values (479px, 401px, 699px)
• Device-specific breakpoints (iPhone 12, iPad Pro)
• Too many breakpoints (6+)

Component Patterns

Cards

<div class="card">
    <!-- Consistent padding: 2.5rem/1rem mobile, 3.5rem/2.5rem desktop -->
</div>

Buttons

<button class="button">Primary</button>
<button class="button secondary">Secondary</button>
<button class="button button-small">Compact</button>

• Minimum touch target: 44px height (accessibility)
• Consistent padding: 1rem horizontal
• Clear hover states

Forms

<form class="form-horizontal">
    <!-- Stack vertically on mobile, horizontal on tablet+ -->
</form>

Accessibility Considerations

Focus States

:focus-visible {
    outline: 2px solid var(--focus-color);
    outline-offset: 0.25em;  /* Visible gap */
}

Touch Targets

• Minimum 44×44px (iOS/Android guidelines)
• Achieved through padding, not just element size

Motion Preferences

@media (prefers-reduced-motion: reduce) {
    * {
        animation-duration: 0.01ms !important;
        transition-duration: 0.01ms !important;
    }
}

Design Philosophy References

Otl Aicher (1972 Munich Olympics)

• Systematic grids (8-unit base)
• Functional typography
• Color as information, not decoration

Applied here: Spacing scale based on mathematical progression, not arbitrary values.

Erik Spiekermann (Stop Stealing Sheep)

• Line height: 1.4–1.5× font size for body text
• Optimal line length: 45–75 characters
• Systematic type scales

Applied here: 50ch max width, unitless line-heights, minor second scale.

Frank Chimero (The Web's Grain)

• Design with web-native patterns
• Embrace fluidity, don't fight it
• Content determines form

Applied here: Fluid font sizing with clamp(), flexible grids, rem-based spacing.

37signals (Getting Real)

• Simplicity and purpose over decoration
• Clear hierarchy
• Functional design

Applied here: Minimal color palette, clear spacing hierarchy, purposeful components.

Common Patterns

Heading + Content

<section class="stack-xs">
    <h3>Section Title</h3>
    <p>Tight coupling (0.5rem) shows relationship</p>
</section>

Related Content

<article>
    <p>First paragraph</p>
    <!-- 1.5rem spacing (automatic in article) -->
    <p>Second paragraph flows naturally</p>
</article>

Major Sections

<main>
    <section>First major section</section>
    <!-- 5rem mobile / 8rem desktop spacing -->
    <section>Second major section</section>
</main>

Migration Notes

From Original to Proposed System

What changed:

• Replaced .stack-* with .flow-* (but kept .stack-* for compatibility)
• Added semantic color names (but kept numeric aliases)
• Added systematic spacing scale
• Improved component organization

What stayed the same:

• Minor second type scale
• Fluid font sizing with clamp()
• 55rem container width
• 50ch text measure
• All existing components work identically

Backward compatible: All existing classes still work. New classes are additions, not replacements.

Quick Reference

Typography

• h1: 1.793rem, line-height 1.2
• h2: 1.476rem, line-height 1.3
• h3: 1.138rem, line-height 1.4
• body: 1rem, line-height 1.5
• small: 0.878rem, line-height 1.4

Common Spacing

• Tight: 0.5rem (heading → content)
• Medium: 1.5rem (paragraphs)
• Large: 3rem (article sections)
• XLarge: 5–8rem (page sections)

Breakpoints

• Mobile: < 40rem (640px)
• Tablet: 40rem–60rem (640–960px)
• Desktop: > 60rem (960px+)

Last updated: 2025-10-08