Design Language
This site follows a Swiss/International Style approach: systematic design with restraint. Every visual choice is intentional. No arbitrary decisions, no "magic numbers."
The design system is built on design tokens—named values that encode all visual decisions. Using tokens instead of raw values ensures consistency and makes updates trivial.
Core principles
Systematic
Every value derives from a mathematical system. Typography uses the Golden Ratio. Spacing uses powers of 2. Colors use OKLCH for perceptual uniformity.
Restrained
Use the minimum visual treatments necessary. Let content speak. Reduce, don't add. When in doubt, remove.
Accessible
WCAG AA minimum (4.5:1 text contrast, 3:1 UI components). No information conveyed by color alone. Clear focus states.
Color system
The palette is deliberately limited: black, white, and one accent color. This constraint creates a clean, professional appearance and makes the accent color more impactful when used.
Semantic colors
Rather than using colors directly, components use semantic tokens that adapt to light and dark modes:
| Token | Purpose |
|---|---|
--color-text | Primary text color |
--color-text-muted | Secondary text (less emphasis) |
--color-text-subtle | Tertiary text (captions, hints) |
--color-surface | Base background |
--color-surface-muted | Recessed areas (less prominent) |
--color-surface-raised | Elevated elements (cards, modals) |
--color-border | Standard borders |
--color-border-muted | Subtle dividers |
--color-link | Link text |
--color-link-hover | Link hover state |
Using accent colors
The accent color is reserved for:
- Interactive elements that need emphasis
- Current navigation state
- Important calls to action
- Errors and warnings (with appropriate color adjustments)
Don't overuse it. The power of an accent comes from its scarcity. If everything is accented, nothing is.
Dark mode
The site respects the user's system preference (prefers-color-scheme) and provides
a manual toggle. Semantic tokens automatically adapt—you never need to write conditional color
logic.
Dark mode isn't "inverted light mode." It's designed specifically for low-light reading with appropriate contrast ratios that don't strain the eyes.
Spacing system
Spacing uses a base-4 grid. The fundamental unit is 4px, and all spacing values are multiples of this unit.
| Token | Value | Typical use |
|---|---|---|
--space-1 | 4px | Tight internal spacing |
--space-2 | 8px | Small gaps, inline spacing |
--space-3 | 12px | Medium-tight spacing |
--space-4 | 16px | Base rhythm, gutter (1rem) |
--space-6 | 24px | Standard section spacing |
--space-8 | 32px | Large component spacing |
--space-12 | 48px | Section breaks |
--space-16 | 64px | Major section gaps |
--space-24 | 96px | Large section gaps |
Semantic spacing
For common patterns, use semantic tokens:
--gutter— Standard margin/padding (16px)--section-gap— Between major sections (64px)--section-gap-large— Hero to content transition (96px)
Layout tokens
Container widths
| Token | Value | Use |
|---|---|---|
--width-narrow | 576px | ~60ch, narrow reading column |
--width-normal | 672px | ~72ch, standard content |
--width-wide | 768px | ~80ch, wide content |
--width-full | 1280px | Full-width layouts |
Border radius
Corners are slightly rounded to soften the appearance. The site uses a restrained approach—not too sharp, not too pill-shaped.
--radius-sm— 4px, subtle rounding--radius-md— 8px, standard components--radius-lg— 16px, cards, large elements--radius-full— Pills, circular elements
Shadows
Shadows are subtle and used sparingly. They indicate elevation (raised elements) rather than decoration.
--shadow-sm— Subtle lift, buttons--shadow-md— Cards, dropdowns--shadow-lg— Modals, popovers
Transitions
Animations use consistent easing and duration for a cohesive feel.
--transition-fast— 150ms, hover states, small elements--transition-base— 200ms, most interactions--transition-slow— 300ms, larger state changes
All transitions use cubic-bezier(0.4, 0, 0.2, 1)—a smooth ease-out curve that feels
natural and responsive.
Z-index scale
Layer ordering uses a defined scale to prevent z-index wars:
| Token | Value | Use |
|---|---|---|
--z-base | 0 | Default stacking |
--z-dropdown | 1000 | Dropdown menus |
--z-sticky | 1100 | Sticky headers |
--z-fixed | 1200 | Fixed position elements |
--z-modal | 1300 | Modal dialogs |
--z-popover | 1400 | Popovers, tooltips over modals |
--z-tooltip | 1500 | Tooltips (always on top) |
Implementation
All tokens are defined in src/styles/00-settings/_tokens.css. When building
components or layouts:
- Always use tokens, never raw values
-
Use semantic tokens (
--color-text) over raw colors (--color-gray-900) - Test in both light and dark modes
- Verify contrast ratios meet WCAG AA