ADR 0004: Design System & Component Tokens

Status: ✅ Accepted
Date: 2025-12-11
Owner: Delivery Lead (Design/UX)

Context

The brand guidelines (0002-brand-guidelines) set the visual direction, but we still need a concrete design system that drives development. This document defines the tokens, typography, spacing, and reusable component patterns that power the site and make future work measurable against the Spec Kit checklist (spec-kit/checklist.md:7-9).

Tokens

Colors

Token	Value	Role
`color-background`	`#0A0A0A` (dark), `#FFFFFF` (light)	Canvas
`color-surface`	`#1A1A1A` / `#F5F5F5`	Cards, panels
`color-border`	`#2A2A2A` / `#E5E5E5`	Dividers
`color-text-primary`	`#FFFFFF` / `#1A1A1A`	Body copy
`color-text-secondary`	`#CCCCCC` / `#666666`	Subheadings, metadata
`color-touchable`	`#8B5CF6`	Primary CTA, accents
`color-success`	`#10B981`	Positive status
`color-warning`	`#F59E0B`	Attention
`color-error`	`#EF4444`	Errors, critical

Sizing & Spacing

Token	Value	Usage
`space-1`	`4px`	Tight gutters
`space-2`	`8px`	Compact spacing
`space-3`	`12px`	Card padding
`space-4`	`16px`	Blocks / default
`space-5`	`24px`	Sections
`space-6`	`32px`	Wide layout
`space-7`	`48px`	Footer / hero

Typography

Scale	Size	Weight	Line Height
Display	72px	700	1.1
H1	48px	700	1.2
H2	36px	700	1.3
H3	24px	600	1.4
Body	16px	400	1.6
Body Small	14px	400	1.5

Font stack: 'Inter', system-ui, -apple-system, sans-serif. Monospaced elements use 'JetBrains Mono', 'Fira Code', monospace.

Components

Buttons

Primary button: purple background (color-touchable), white text, padding: 12px 24px, border-radius: 8px, font-weight: 600. Hover state: lighten background (95%).
Secondary button: transparent background, border: 1px solid color-border, text uses color-text-primary (dark mode) or color-text-primary (light mode), same padding/radius.
Ghost button: text only, color-text-secondary, underline on focus/hover.

Cards

Background uses color-surface.
Border: 1px solid color-border.
Shadow: 0 4px 16px rgba(0, 0, 0, 0.25) (dark) or 0 2px 8px rgba(0,0,0,0.08) (light).
Padding: space-5.

Accessibility Notes

Maintain a contrast ratio of ≥4.5:1 for body text and ≥3:1 for large text (per WCAG 2.1 AA).
Focus indicators: outline: 2px solid #8B5CF6, outline-offset: 2px.
Hit targets: minimum 44x44px, confirm with devtools during QA.

Implementation

Tailwind config uses these tokens as custom colors (color-touchable, color-success, etc.).
Global CSS (globals.css) maps typographic elements (e.g., h1, p, .cta) to these tokens.
Reuse the Button pattern whenever a CTA appears (hero, testimonial CTA, contact form).

Future Work

Add design tokens to Storybook or Spec Kit pattern library when UI kit becomes available.
Pair with accessibility testing (tab order/focus states) after the hero/CTA sections are interactive.

3.2 KiB Raw Blame History