Files
cv/docs/design/specs/ui/spec-ui-layout.md
T
dong.nguyen c95f7b09d1 feat(nav): theme-aware palette previews, left-side hamburger, home icon brand
Preview chips now mirror the bar swatch: --preview-*-accent is declared per theme (dark #f87171/#60a5fa, light #b04138/#2563eb, repeated in the prefers-color-scheme bridge) and the two [data-palette=blue] blocks declare nothing, since a chip names its own palette through data-preview. --preview-*-bg is deleted; chips take the shared --border-strong hairline. Dark-mode dots move from 2.53/3.13 to 5.24/6.36 against their panel.

The hamburger leads the bar in a new .nav-brand group (trigger then brand), and the wordmark becomes a 24px stroke home icon in a 44px target with a :focus-visible ring, still a <Link to="/">. .logo-bracket/.logo-text are removed and the <=420px guard drops its brand-gap override: the row measures 252px inside 288px.

Docs: new specs/v3/spec-v3-nav-swatch-and-hamburger.md plus supersession notes in spec-v3-mobile-navigation, spec-v3-theme-palette-switch and spec-v3-ui-enhancements; AGENTS.md, spec-ui-layout and spec-ui-navigation updated. Gates: tsc+vite build exit 0, oxlint 15 findings (11 rules-of-hooks, unchanged baseline), zero hex in App.css, 12/12 SSR bar-order assertions.
2026-10-17 22:33:42 +07:00

5.1 KiB
Raw Blame History

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

/* 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-swatch-option buttons — the Mode/Language segmented-row shape, 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 + text 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, 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