UI Spec — Layout & Theme
Overview
Global layout structure, theme system, and page transitions.
Layout Structure
Page Container
| Property |
Value |
| Max-width |
1200px (wide sections), 800px (content sections) |
| Padding |
0 24px (desktop), 0 16px (mobile) |
| Margin |
Auto center |
Section Spacing
| Property |
Value |
| Vertical padding |
80px (desktop), 48px (mobile) |
| Between sections |
0 (continuous flow) |
Theme System
Modes
| Mode |
Description |
| Dark |
Primary mode, near-black background |
| Light |
Secondary mode, white background |
| System |
Follow OS preference |
Default
- System preference
- Persist in
localStorage
CSS Variables
Single Accent Color
- Only one accent color per theme
- Avoid multi-color palette
- Use accent for: links, active states, CTAs, badges, highlights
Theme Toggle
| Property |
Value |
| Location |
Navigation bar (right side) |
| Icon |
Sun/Moon icon |
| Tooltip |
Current mode (dark/light/system) |
| Click behavior |
Cycle: dark → light → system → dark |
Page Transitions
- Fade transition between routes (200ms)
- No slide, no parallax
- Respect
prefers-reduced-motion
Responsive Breakpoints
| Breakpoint |
Width |
Description |
| Mobile |
< 768px |
Single column, touch-optimized |
| Tablet |
768–1023px |
Adaptive grid |
| Desktop |
>= 1024px |
Multi-column, wide layouts |
Accessibility
prefers-color-scheme media query
prefers-reduced-motion media query
- Theme toggle:
aria-label with current mode
- Focus visible: accent color outline (2px)
- Contrast ratio >= 4.5:1 for all text
- No theme flash on page load (inline script)
Constraints
- Theme state in context/provider (not global store)
- Persist preference in
localStorage
- Inline script in
<head> to prevent flash
- CSS variables for all theme values
- No hardcoded colors in components