84 lines
3.2 KiB
Markdown
84 lines
3.2 KiB
Markdown
# 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.
|