Files
cv/docs/design/specs/ui/spec-ui-layout.md

160 lines
5.1 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# UI Spec — Layout & Theme
## Overview
Global layout structure, theme system, and page transitions.
---
## Layout Structure
```
App
├── Navigation (sticky top)
├── Main Content
│ └── Page Container
│ └── Page Content
└── Footer (bottom)
```
---
## 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
```css
/* Dark mode (default) */
--bg-primary: #0a0a0a;
--bg-surface: #141414;
--bg-elevated: #1a1a1a;
--text-primary: #f0f0f0;
--text-secondary: #a0a0a0;
--text-muted: #666666;
--accent: #60a5fa;
--border: #2a2a2a;
--shadow: rgba(0, 0, 0, 0.3);
/* Light mode */
--bg-primary: #ffffff;
--bg-surface: #f5f5f5;
--bg-elevated: #ffffff;
--text-primary: #0a0a0a;
--text-secondary: #404040;
--text-muted: #808080;
--accent: #2563eb;
--border: #e0e0e0;
--shadow: rgba(0, 0, 0, 0.1);
```
### 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); the mobile sheet carries a Dark/Light segmented control instead |
| Icon | Sun/Moon icon |
| Tooltip | Current mode (dark/light) |
| Click behavior | Toggle: dark ↔ light — the `system` variant was removed (`src/hooks/useTheme.tsx:4`) |
### Theme Palette
| Property | Value |
|---|---|
| Location | Navigation bar (right side, the last of the three appearance controls — after the mode toggle) at **every** width — the control is not hidden at ≤1024px (Q14) — plus the Theme color row, the last of three rows in the mobile sheet's Appearance group (Language → Mode → Theme color), while the sheet is open |
| Control | Bar: `ThemePaletteMenu` (`src/components/layout/ThemePaletteMenu.tsx`), icon-only trigger — a 20px half-circle swatch (active palette's accent left, `--swatch-empty` right), no text and no chevron, name in `aria-label`, hint in `title` — opening the `#palette-menu` panel. Sheet: rendered by `MobileMenu.tsx` from `paletteIds` + `paletteMeta` as `.mobile-menu-icon-option` buttons — the 44px icon-only square the Language row shares, options drawn as colour icons |
| Options | `red` (default) / `blue` — `src/data/palettes.ts` (`paletteIds`, `paletteMeta.label`/`hint`), written to `data-palette` on `<html>`; the sheet lists both, one colour icon each |
| Chrome | The bar's three appearance controls share `.nav-control` (44px bordered box, accent border + icon on hover/open, one `:focus-visible`) and sit in `.nav-actions` at the bar's right end in the order language → mode → theme color; the hamburger leads the bar inside `.nav-brand`, left of the logo (Q17 of `specs/v3/spec-v3-nav-swatch-and-hamburger.md`, superseding that spec's Q16 hamburger-last clause), with a `@media (max-width: 420px)` guard so the row fits 320px |
Spec: `specs/v3/spec-v3-theme-palette-switch.md`.
### Mobile Menu Sheet
| Property | Value |
|---|---|
| Trigger | Hamburger button at the bar's **left edge**, immediately left of the brand home icon (`.nav-logo`, a `<Link to="/">`), ≤1024px (Q17) |
| Groups | Menu (6 routes) → Appearance (Language — icon-only globe / flag-outline options, Mode, Theme color) → Connect (GitHub, LinkedIn, email) |
| Behaviour | `role="dialog"` + `aria-modal="true"` + `tabIndex={-1}`: focus lands on the panel itself on open — never on a link, because focusing a link fires its rolling-text animation — Escape closes from any focus position, `#main-content` / `.footer` / `.back-to-top` are `inert` while open, body scroll locked |
Spec: `specs/v3/spec-v3-mobile-navigation.md`.
---
## 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 |
The navigation bar collapses to the hamburger + sheet at **≤1024px** (`src/App.css` `@media (max-width: 1024px)`), not at 768px. 768px governs single-column content layouts only.
---
## 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