Second axis on <html>: data-palette (Portfolio type Palette = 'red' | 'blue', localStorage key portfolio-palette, default red so existing visitors see no change). Both attributes are written before paint by the index.html init script and re-written during render in useTheme. - src/types/index.ts, src/data/palettes.ts: Palette + paletteIds/paletteMeta (Record<Language, string>, indexed inline - no lookup helper) - src/hooks/useTheme.tsx: palette state, data-palette write during render, persistence, setPalette; no cyclePalette - src/components/layout/ThemePaletteMenu.tsx: disclosure semantics (aria-expanded/aria-controls, aria-current), variant nav|sheet, panel ids derived from variant, Escape closes and refocuses the trigger - src/components/layout/Navigation.tsx: nav instance in .nav-actions, sheet instance after the mobile link list, remounted closed via key - src/index.css: blue dark/light blocks (0,3,0 selectors) + preview tokens; red --accent-soft/--accent-glow re-derived from the accent in force - src/App.css: .nav-palette* block (token-only), nav hidden at 1024px, sheet options inline - specs: palette-switch spec v0.3.0 with the implementation record; corrected the false AA claim in spec-v3-theme-colors.md (3.90:1, not ~4.8), the composite values in spec-v3-theme-palette-gasatrya.md, the Footer consumer claim in spec-v3-theme-switch.md; AGENTS.md Theming section documents the palette axis Verified: tsc exit 0; vite build green (CSS 31.80 kB); oxlint unchanged at 11 errors / 9 warnings; hex gate over src/App.css 0 matches; inline type styles 0; contrast minima 4.96 / 4.63 / 4.81 / 4.64 with zero AA failures.
48 KiB
Specification — v3 Theme Palette Switch (Red / Blue)
Document:
spec-v3-theme-palette-switch.mdVersion: 0.3.0 (implementation applied 2026-10-17 — §6 and §7 now show the shipped code, §11–§12 and §14 carry the verification evidence) Parents:spec-v3-theme-palette-gasatrya.md(the shipped token set),spec-v3-theme-switch.md(the dark/light control) Priority: P1 Estimate: ~3 hours including contrast verification and browser pass Status: IMPLEMENTED 2026-10-17 — Steps 1–8 are on disk, §6–§7 show the shipped code, §14 records the verification. Open: the owner's browser pass (4 combinations × ≤1024px) and the commit decision.
1. Problem
The site has one brand color. src/index.css defines three palette blocks (:root dark default, :root[data-theme='light'], and the prefers-color-scheme: light bridge) and all three carry the same red accent family (#f87171 dark, #b04138 light). A visitor can change lightness (sun/moon button in the nav) but has no way to see the site in the blue identity that spec-v3-theme-colors.md once described — that palette was never implemented and the document is marked superseded.
Concretely today:
| Control | Exists? | Where |
|---|---|---|
| Dark ↔ light | ✅ | .theme-toggle button, src/components/layout/Navigation.tsx:57-73 |
| Red ↔ blue | ❌ | nothing — the accent family is hard-coded in the three src/index.css blocks |
| Persisted choice | ✅ theme only | localStorage key portfolio-theme, src/hooks/useTheme.tsx:14 |
| No-flash on reload | ✅ theme only | init script index.html:8-20 sets data-theme before paint |
There is also a naming trap this spec has to settle: the code already calls dark/light theme (type Theme = 'dark' | 'light', src/hooks/useTheme.tsx:4). The new choice is a color axis. Reusing the word "theme" for both would make theme: 'red' collide with data-theme="light". This spec therefore names the new axis palette in code (Palette, data-palette, portfolio-palette) and labels it "Theme color" / "Màu giao diện" in the UI — the house spelling is US "color" (spec.md §26 "Color System", spec-v3-theme-colors.md "Theme Colors").
2. Goal
- Two palettes — Red (current, default) and Blue (new) — each with a dark and a light variant: 4 verified combinations.
- A menu in the navigation to pick the palette, working on desktop and on mobile.
- Choice persists across reloads and routes, and applies before first paint (no red flash for a blue user).
- Dark/light and Red/Blue are independent: switching one never changes the other.
- Every combination passes WCAG AA (≥ 4.5:1 for text, ≥ 3.0 for meaningful UI edges) — measured, not asserted.
- No layout change, no new dependency, no new type scale, no hard-coded hex outside the palette declaration blocks.
Non-goals: a third palette, per-page palettes, a system-following palette, and any change to the resume PDF (its print inks are fixed in public/resume-template.html, retinted for red in spec-v3-theme-palette-gasatrya.md §4.4).
3. Current state (verified)
| Fact | Evidence |
|---|---|
Theme = 'dark' | 'light', no 'system'; data-theme set during render, not in an effect |
src/hooks/useTheme.tsx:3, :39 |
resolvedTheme exists only for API compatibility — resolveTheme is the identity function |
src/hooks/useTheme.tsx:29-31 |
Storage: single key portfolio-theme, written in an effect wrapped in try/catch |
src/hooks/useTheme.tsx:14, :41-47 |
Pre-paint script reads storage, falls back to prefers-color-scheme, else dark |
index.html:8-20 |
Nav bar is position: sticky; z-index: 1000, height 64px |
src/App.css:2-20 |
Mobile menu is a full-screen sheet, top: 64px, z-index: 999 (below the nav) |
src/App.css:125-141 |
| Nav actions row: theme toggle, language toggle, hamburger | src/components/layout/Navigation.tsx:56-99 |
Hamburger appears at ≤1024px; .mobile-menu-btn is display: none above it |
src/App.css:109-122, :176-184 |
Existing dropdown idiom: absolute panel under a trigger — --bg-elevated, 1px solid --border, radius 8, 0 4px 12px --shadow, z-index: 100, option hover = accent fill + --text-on-accent |
src/App.css:732-757 |
| A click-outside hook already exists and is the pattern to reuse | src/hooks/useClickOutside.ts:3-16 |
Nav strings live in strings.nav |
src/i18n/strings.ts:2-9 |
| The footer has no theme control | src/components/layout/Footer.tsx (no useTheme import) — spec-v3-theme-switch.md §Step 5 claims it does; that claim is stale |
--accent-soft / --accent-glow were rgba(239, 68, 68, …) = #ef4444 while --accent is #f87171 (dark) / #b04138 (light) |
src/index.css:13,15,71,73 — resolved 2026-10-16, re-derived from the accent in force; see §5 "Red, re-derived" |
4. Model
Two orthogonal axes, both attributes on <html>:
| Axis | Type | Values | Attribute | Storage key | Default |
|---|---|---|---|---|---|
| lightness | Theme (existing) |
'dark' | 'light' |
data-theme |
portfolio-theme |
system, else dark |
| color | Palette (new) |
'red' | 'blue' |
data-palette |
portfolio-palette |
'red' |
4 reachable combinations: red-dark (the shipped default), red-light, blue-dark, blue-light.
Attribute → block matrix and specificity
data-theme |
data-palette |
Block that wins | Specificity |
|---|---|---|---|
| absent | absent | :root (dark red) → then the prefers-color-scheme: light bridge may repaint to light red |
0,1,0 / 0,2,0 |
dark |
absent | :root |
0,1,0 |
light |
absent | :root[data-theme='light'] |
0,2,0 |
dark |
blue |
:root[data-theme='dark'][data-palette='blue'] |
0,3,0 |
light |
blue |
:root[data-theme='light'][data-palette='blue'] |
0,3,0 |
Two-attribute selectors beat both base blocks, so block order no longer decides the winner — the only ordering requirement is readability. No blue variant is needed inside the prefers-color-scheme bridge: data-palette is written by the init script, and that same script always writes data-theme, so a request that reaches the bridge (script blocked / no-JS) is by definition also a request with no stored palette → red. If the script is blocked, the site is red in the OS-preferred lightness: an acceptable, documented degradation.
5. Palettes
Red's neutrals, accents, borders, tints and shadows stay byte-identical to what is shipped (src/index.css:2-57, :60-85); only its two derived alphas were re-derived from the accent in force — see "Red, re-derived" below. Blue is new. Blue's neutrals are retinted cool — the same move the red palette makes warm (#151914, #202423, #2a3028 all carry a green cast); a blue accent sitting on a green-cast neutral reads as a mismatch, not as a theme.
Blue, dark
--bg-primary: #0f1117; --bg-surface: #161922; --bg-elevated: #1c2030;
--text-primary: #e8eaed; --text-secondary: #9aa0a6; --text-muted: #828d9e;
--accent: #60a5fa; --accent-hover: #93c5fd; --accent-active: #3b82f6;
--text-on-accent: #0f1117;
--accent-soft: rgba(96, 165, 250, 0.12);
--accent-tint: #182338;
--accent-glow: rgba(96, 165, 250, 0.30);
--border: #2a3040; --border-strong: #39415a;
--shadow: rgba(0, 0, 0, 0.45);
--inset-highlight: rgba(255, 255, 255, 0.05);
--code-bg: #1a1e2e;
--success: #34d399; --success-glow: rgba(52, 211, 153, 0.35);
--error: #f87171; --warning: #fbbf24;
--grid-color: rgba(232, 234, 237, 0.06);
color-scheme: dark;
Blue, light
--bg-primary: #f4f6f9; --bg-surface: #fbfcfe; --bg-elevated: #ffffff;
--text-primary: #111827; --text-secondary: #4b5563; --text-muted: #5c6b82;
--accent: #2563eb; --accent-hover: #1d4ed8; --accent-active: #1e40af;
--text-on-accent: #ffffff;
--accent-soft: rgba(37, 99, 235, 0.10);
--accent-tint: #eef3fc;
--accent-glow: rgba(37, 99, 235, 0.22);
--border: #dfe3ea; --border-strong: #d3d8e1;
--shadow: rgba(17, 24, 39, 0.10);
--inset-highlight: rgba(255, 255, 255, 0.9);
--code-bg: #eceff5;
--success: #15803d; --success-glow: rgba(21, 128, 61, 0.35);
--error: #991b1b; --warning: #b45309;
--grid-color: rgba(17, 24, 39, 0.07);
color-scheme: light;
Three values were not copied from the old blue draft (spec-v3-theme-colors.md) because that document predates the current token set and never measured anything:
| Token | Old blue draft | This spec | Why |
|---|---|---|---|
--text-muted dark |
#6b7280 |
#828d9e |
#6b7280 measures 3.90 on #0f1117 and 3.63 on #161922 — AA fail. #828d9e measures 5.62 / 5.23 / 4.81 (primary / surface / elevated) |
--text-muted light |
#64748b |
#5c6b82 |
#64748b measures 4.40 on #f4f6f9 — AA fail. #5c6b82 measures 5.00 / 5.27 / 5.41 |
--accent-tint light |
— | #eef3fc |
with #e2eaf8 the accent reads 4.27 on the tint (fail, and the tint is a real background: src/App.css:809); #eef3fc gives 4.64 |
--accent-soft and --accent-glow are derived from the accent actually in force (96,165,250 / 37,99,235), which the red palette does not do today (see §3, last row) — see §10 for the cleanup decision.
Measured contrast (WCAG relative luminance, all four combinations)
Text pairs, need ≥ 4.5:
| Pair | red-dark | red-light | blue-dark | blue-light |
|---|---|---|---|---|
| text-primary / bg-primary | 16.31 | 16.31 | 15.66 | 16.39 |
| text-primary / bg-surface | 14.40 | 17.05 | 14.56 | 17.28 |
| text-primary / bg-elevated | 13.30 | 17.78 | 13.42 | 17.74 |
| text-secondary / bg-primary | 8.11 | 4.80 | 7.15 | 6.98 |
| text-secondary / bg-surface | 7.16 | 5.02 | 6.65 | 7.36 |
| text-muted / bg-primary | 6.08 | 4.77 | 5.62 | 5.00 |
| text-muted / bg-surface | 5.37 | 4.99 | 5.23 | 5.27 |
| text-muted / bg-elevated | 4.96 | 5.20 | 4.81 | 5.41 |
| accent / bg-primary | 6.43 | 5.26 | 7.42 | 4.77 |
| accent / bg-surface | 5.67 | 5.50 | 6.90 | 5.03 |
| accent / bg-elevated | 5.24 | 5.74 | 6.36 | 5.17 |
| accent-hover / bg-surface | 8.27 | 6.15 | 9.73 | 6.53 |
| text-on-accent / accent | 6.43 | 5.74 | 7.42 | 5.17 |
| text-on-accent / accent-hover | 9.37 | 6.42 | 10.46 | 6.70 |
| text-on-accent / accent-active | 5.54 | 7.29 | 5.13 | 8.72 |
| accent / accent-tint | 5.74 | 4.63 | 6.18 | 4.64 |
| text-primary / accent-tint | 14.58 | 14.36 | 13.04 | 15.93 |
| text-primary / code-bg | 15.47 | 15.08 | 13.73 | 15.40 |
| text-secondary / code-bg | 7.69 | 4.44 † | 6.27 | 6.56 |
| text-muted / code-bg | 5.77 | 4.41 † | 4.93 | 4.70 |
| success / bg-surface | 9.01 | 4.81 | 9.13 | 4.89 |
| error / bg-surface | 8.27 | 7.97 | 6.35 | 8.10 |
| warning / bg-surface | 9.40 | 4.81 | 10.52 | 4.89 |
| minimum (pairs the design renders) | 4.96 | 4.63 | 4.81 | 4.64 |
Zero AA failures in the pairs the design renders. --code-bg is consumed only by code / pre — grep -n "code-bg" src/index.css src/App.css returns exactly two uses, src/index.css:265 and :273, and neither rule declares a color, so code text inherits --text-primary (13.30–17.78). The two † cells are secondary/muted text placed on --code-bg, a pairing no rule in src/ produces; they are recorded so that introducing one later is visibly a fail, not an oversight.
Layering invariant luminance(bg-primary) < luminance(bg-surface) < luminance(bg-elevated):
| red-dark | red-light | blue-dark | blue-light |
|---|---|---|---|
| 0.0091 < 0.0169 < 0.0224 ✅ | 0.9131 < 0.9566 < 1.0000 ✅ | 0.0056 < 0.0098 < 0.0149 ✅ | 0.9198 < 0.9729 < 1.0000 ✅ |
Hairline borders are deliberately outside the text gate: --border / --border-strong measure 1.19–1.74 against their backgrounds in every palette, red included. They are separators and panel outlines, not state-bearing component boundaries (WCAG 1.4.11 applies to boundaries needed to identify a control), and the shipped design already uses this hairline model (spec-v3-theme-palette-gasatrya.md §3.2). Blue keeps the same relative step as red: border ≈ bg + 0x15, border-strong ≈ border + 0x10.
Red, re-derived (applied 2026-10-16)
--accent-soft and --accent-glow now use the accent in force, not a third red that happens to sit between the two accents:
| Block | Before | After |
|---|---|---|
dark — src/index.css:13, :15 |
rgba(239, 68, 68, 0.12) / rgba(239, 68, 68, 0.3) |
rgba(248, 113, 113, 0.12) / rgba(248, 113, 113, 0.3) |
light — src/index.css:71, :73 |
rgba(239, 68, 68, 0.1) / rgba(239, 68, 68, 0.22) |
rgba(176, 65, 56, 0.1) / rgba(176, 65, 56, 0.22) |
bridge — src/index.css:100, :102 |
same as light | same as light |
Only the hue source moved; every alpha is the value spec-v3-theme-palette-gasatrya.md signed off.
--accent-soft is the one derived token that carries text: .btn-secondary sets color: var(--accent) (src/App.css:228) and :hover paints background: var(--accent-soft) (src/App.css:235). Every other use is a halo, ring or shadow and is decorative: .btn-primary shadows (src/App.css:212, :219, :223), the timeline pulse keyframes (:1020, :1027), the first-entry marker ring (:975), the TLDR diamond ring (:1105), the responsibility bullet dot (:1199). --accent-glow never carries text.
Wash composites and the resulting accent-on-wash ratios:
| Background | old wash | accent on old wash | new wash | accent on new wash | wash vs background |
|---|---|---|---|---|---|
dark #151914 |
#2f1b1b |
5.87 | #302020 |
5.61 ✅ | 1.10 → 1.15 |
dark #202423 |
#392424 |
5.23 | #3a2a2a |
4.92 ✅ | 1.09 → 1.15 |
dark #272a28 |
#3f2a2a |
4.82 | #403030 |
4.51 ✅ | 1.09 → 1.16 |
light #f6f5f2 |
#f5e4e4 |
4.67 | #efe4e3 |
4.61 ✅ | 1.13 → 1.14 |
light #fbfaf8 |
#fae9e9 |
4.89 | #f4e8e8 |
4.80 ✅ | 1.12 → 1.15 |
light #ffffff |
#fdecec |
5.02 | #f7eceb |
4.96 ✅ | 1.14 → 1.16 |
No AA regression — the worst pair is 4.51 (dark accent text on a soft wash over --bg-elevated), and the wash became slightly more visible against its background in every case. Verified against the emitted bundle: --accent-soft:#f871711f, --accent-glow:#f871714d, --accent-soft:#b041381a (×2, light block + bridge), --accent-glow:#b0413838 (×2) — hex-alpha form, 0x1f = 0.12, 0x4d = 0.30, 0x1a = 0.10, 0x38 = 0.22.
The resume PDF is independent of this: scripts/generate-resume.ts and public/resume-template.html reference no theme token (grep 'accent|--bg|--text' → 0 matches), and both regenerated PDFs still render the five entries with no undefined.
6. UI — the menu
Placement
One component, two placements, chosen by media query. No floating sheet that can collide with the mobile menu sheet.
| Width | Trigger | Options |
|---|---|---|
| > 1024px | in .nav-actions, between the theme toggle and the language toggle |
absolute panel under the trigger, right-aligned to it |
| ≤ 1024px | a block at the bottom of .mobile-menu, after the nav links — 44px tap targets |
the options are inline in the mobile sheet, not a second overlay |
Why 1024px, not 768px. .nav-menu is hidden and .mobile-menu-btn appears at @media (max-width: 1024px) (src/App.css:176-184). Using the same breakpoint means whatever collapses into the sheet collapses together. A 768px palette breakpoint would leave a 769–1024px band where the page links hide behind a hamburger while a color menu sits in the bar — two navigation idioms at the same time. Cost of the choice: at 800px the palette costs two taps instead of one. Alternative if the owner wants one tap: keep 768px and hide the label (.nav-palette-current { display: none }) down to 1024px — the bar fits comfortably there; crowding is only a risk below 1024px, which is where the hamburger already lives. Not taken: the shipped build collapses at 1024 with the links.
Consequence on phones and tablets: .nav-actions keeps exactly three controls (theme, language, hamburger) — unchanged from today, so the 320px bar cannot overflow. The two instances are the same component rendered twice with a variant prop, one hidden per breakpoint (display: none removes it from the accessibility tree).
Component
New file src/components/layout/ThemePaletteMenu.tsx:
interface ThemePaletteMenuProps {
variant: 'nav' | 'sheet'
}
Wiring, then markup (rendered identically for both variants):
const close = useCallback(() => setOpen(false), [])
useClickOutside(containerRef, close)
const handleKeyDown = (event: React.KeyboardEvent<HTMLDivElement>) => {
if (event.key !== 'Escape') return
close()
triggerRef.current?.focus() // keep the screen-reader position on Escape
}
<div ref={containerRef} className={`nav-palette nav-palette-${variant}`} onKeyDown={handleKeyDown}>
<button
ref={triggerRef}
type="button"
className={`nav-palette-trigger ${open ? 'open' : ''}`}
aria-expanded={open}
aria-controls={`palette-menu-${variant}`}
aria-label={`${strings.nav.palette[lang]}: ${paletteMeta[palette].label[lang]}`}
title={strings.nav.paletteAria[lang]}
onClick={() => setOpen((prev) => !prev)}
>
<span className="nav-palette-swatch" aria-hidden="true" />
<span className="nav-palette-group">{strings.nav.palette[lang]}</span>
<span className="nav-palette-current">{paletteMeta[palette].label[lang]}</span>
<svg className="chevron" width="16" height="16" viewBox="0 0 24 24" fill="none"
stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
<polyline points="6 9 12 15 18 9" />
</svg>
</button>
<div id={`palette-menu-${variant}`} className={`nav-palette-panel ${open ? 'open' : ''}`}>
{paletteIds.map((id) => (
<button
key={id}
type="button"
className={`nav-palette-option ${id === palette ? 'active' : ''}`}
aria-current={id === palette ? 'true' : undefined}
onClick={() => { setPalette(id); setOpen(false) }}
>
<span className="nav-palette-preview" data-preview={id} aria-hidden="true" />
<span className="nav-palette-name">{paletteMeta[id].label[lang]}</span>
<span className="nav-palette-hint">{paletteMeta[id].hint[lang]}</span>
</button>
))}
</div>
</div>
The id is derived from variant. Both instances are mounted at the same time (one hidden by CSS), so a hard-coded id would appear twice in the document — invalid HTML and a broken aria-controls.
paletteIds and paletteMeta live in src/data/palettes.ts, shaped like src/data/resume.ts:6-9 (Record<Language, string>, not { en, vi } object literals) so adding a third language fails at compile time instead of silently rendering undefined. paletteMeta is keyed by Palette rather than an array of { id, … } rows: the component indexes paletteMeta[id].label[lang] inline, which removes the need for a paletteLabel(id, lang) lookup helper — a one-expression wrapper the project's ts-no-tiny-functions rule rejects. The type Palette lives in src/types/index.ts next to Language, because the data module and the hook both consume it.
The swatch problem, and how it is solved
A picker must show the colour of the option, not of the current palette: while Red is active, the Blue row has to look blue. var(--accent) cannot do that — it resolves to the active palette. Solution: palette-independent preview tokens declared once in src/index.css inside a declaration block (so the no-literal-hex gate in spec-v3-theme-palette-gasatrya.md §Acceptance still holds, because the literals sit in a declaration block and never in a rule):
/* Picker previews: fixed identity colors so a row previews its own palette,
not the one currently active. Never referenced outside .nav-palette-preview. */
:root {
--preview-red-accent: #b04138;
--preview-red-bg: #f6f5f2;
--preview-blue-accent: #2563eb;
--preview-blue-bg: #f4f6f9;
}
.nav-palette-preview[data-preview='red'] { background: var(--preview-red-accent); border-color: var(--preview-red-bg); }
.nav-palette-preview[data-preview='blue'] { background: var(--preview-blue-accent); border-color: var(--preview-blue-bg); }
No inline style, no hex in src/App.css, no dependence on which palette is active.
States
| State | Style |
|---|---|
| Trigger, closed | same chrome as .theme-toggle: transparent background, --text-muted, padding: 8px, border-radius: var(--radius-md) (src/App.css:86-97) |
| Trigger, open | background: var(--bg-elevated), color: var(--text-primary), chevron rotate(180deg) — mirrors .download-resume-summary.open (src/App.css:728-730) |
| Trigger, focus-visible | outline: 2px solid var(--accent); outline-offset: 2px (src/App.css:104-107) |
| Panel | position: absolute; top: calc(100% + 4px); right: 0 inside .nav-palette { position: relative }; --bg-elevated, 1px solid var(--border), border-radius: var(--radius-lg), box-shadow: 0 4px 12px var(--shadow), z-index: 100. right: 0, never left: 0: the trigger sits at the right edge of .nav-container (padding: 0 24px, src/App.css:12-20), so a left-anchored ~220px panel would run off the viewport on a narrow desktop window. Stacking is safe: .nav is position: sticky; z-index: 1000 (src/App.css:2-10) and creates the stacking context, so the panel paints above page content and above the z-index: 999 mobile sheet |
| Option | color: var(--text-primary), 14px name + 12px --text-muted hint (spec-v3-typography.md reserves the 12–14px band for chrome like tags and pills), min-height 44px |
| Option, active | border-left: 2px solid var(--accent) + a ✓ glyph; label --text-primary |
| Option, hover | background: var(--accent), color: var(--text-on-accent) — the established hover idiom (src/App.css:754-757); hint switches to var(--text-on-accent) with opacity 0.75 |
| Option, focus-visible | outline: 2px solid var(--accent); outline-offset: -2px |
| Sheet variant | a block after </ul> inside .mobile-menu (src/App.css:125-141 — already overflow-y: auto, so the extra row cannot break the layout on a short screen), padding: 12px 0, min-height 44px, label at var(--text-body), group name at var(--text-meta), preview chip 18px, panel position: static; width: 100% so the options expand inline. .mobile-menu is display: none unless .open (src/App.css:126, :138-141), so the row is untabbable while the sheet is closed |
| Reduced motion | main.tsx sets reducedMotion: 'user' and src/index.css:275-284 flattens transition-duration for *, *::before, *::after. The only motion in this component is the chevron's transform transition and the trigger/option color transitions — all covered by that rule, nothing to opt out of |
Behaviour
- Open: click the trigger. Close: selecting an option,
Escape, or a click/tap outside —useClickOutside(ref, close)fromsrc/hooks/useClickOutside.ts, with auseCallback-stable handler because the hook's dependency array is[ref, handler]. - No close-on-navigate effect. The nav variant is already closed by the click that navigated: a nav link is outside
ref, so the click-outside listener fires. The sheet variant is mounted as<ThemePaletteMenu key={location.pathname} variant="sheet" />, so navigation remounts it and its local state resets. CopyingNavigation.tsx:25-27(useEffect(() => setOpen(false), [pathname])) would add a 10threact(set-state-in-effect)warning and break the lint budget in §11. - Keyboard: the panel is
display: nonewhen closed, so its options are out of the tab order; when open,Tabreaches both option buttons andEnter/Spaceactivates one (<button>semantics, no extra code).Escapecloses and returns focus to the trigger viaonKeyDownon the wrapper. No arrow keys, no rovingtabIndex. - Semantics: disclosure, not an ARIA menu.
aria-expanded+aria-controlson the trigger, the panel is a plain container, the selected option carriesaria-current="true". Deliberate:role="menu"+role="menuitemradio"is only correct together with arrow-key navigation and focus management (WAI-ARIA authoring practice); announcing a menu whose arrow keys do nothing is worse than not claiming a menu at all. Two options make the disclosure form the cheaper correct one. - The preview chip is
aria-hidden: color is the redundant channel, the name is the primary one. - Changing the palette never navigates and never scrolls. Changing dark/light keeps the palette; changing the palette keeps dark/light.
Repo idioms this component reuses
| Idiom | Source | How it is reused |
|---|---|---|
Trigger chrome: transparent, --text-muted, padding: 8px, --radius-md, hover --bg-elevated + --text-primary, focus-visible accent outline |
.theme-toggle src/App.css:86-107 |
.nav-palette-trigger |
Chevron: 16×16 polyline 6 9 12 15 18 9, rotates 180° when the trigger is open |
.download-resume-summary .chevron src/App.css:714-717, :728-730 |
same class name chevron, own scoped rule — do not invent .nav-palette-chevron |
| Panel hidden by CSS class, kept in the DOM | .download-resume-dropdown .download-resume-options src/App.css:720-726 |
.nav-palette-panel / .nav-palette-panel.open |
Panel chrome: --bg-elevated, 1px solid --border, radius 8, 0 4px 12px --shadow, z-index: 100 |
.download-resume-options src/App.css:732-743 |
.nav-palette-panel |
Option hover: accent fill + --text-on-accent |
.download-resume-option:hover src/App.css:754-757 |
.nav-palette-option:hover |
Option list built from a data module with Record<Language, string> labels |
src/data/resume.ts:5-9 |
src/data/palettes.ts |
| Shared click-outside hook | src/hooks/useClickOutside.ts |
used deliberately: DownloadResume.tsx:18-31 re-implements it inline, which is the duplication the hook exists to avoid |
Trigger aria-label naming the current value |
Navigation.tsx:60 — Switch theme (currently ${resolvedTheme}) |
same shape, but routed through strings so it is translated |
The existing dropdown has no aria-expanded, no aria-controls and no keyboard support. The new menu is more accessible than it; that is an improvement in behaviour, not a second styling convention.
7. Implementation details
Step 1 — type and data
src/types/index.ts:3, directly under export type Language = 'en' | 'vi';:
export type Palette = 'red' | 'blue';
New src/data/palettes.ts:
import type { Language, Palette } from '@/types'
export const paletteIds: Palette[] = ['red', 'blue']
export const paletteMeta: Record<Palette, { label: Record<Language, string>; hint: Record<Language, string> }> = {
red: { label: { en: 'Red', vi: 'Đỏ' }, hint: { en: 'warm neutral', vi: 'trung tính ấm' } },
blue: { label: { en: 'Blue', vi: 'Xanh dương' }, hint: { en: 'cool neutral', vi: 'trung tính lạnh' } },
}
Record<Language, string> follows src/data/resume.ts:6-9. Theme stays local to useTheme.tsx (unchanged) while Palette is exported from src/types/index.ts: the asymmetry is deliberate — Palette is consumed by a data module, Theme is not.
Step 2 — src/hooks/useTheme.tsx
Add alongside the existing theme state (do not rename Theme, do not touch resolvedTheme):
import type { Palette } from '@/types'
const PALETTE_STORAGE_KEY = 'portfolio-palette'
function getInitialPalette(): Palette {
try {
const stored = localStorage.getItem(PALETTE_STORAGE_KEY)
if (stored === 'red' || stored === 'blue') {
return stored
}
} catch {
// localStorage unavailable
}
return 'red'
}
const [palette, setPaletteState] = useState<Palette>(getInitialPalette)(useTheme.tsx:51)document.documentElement.setAttribute('data-palette', palette)during render, on the line after the existingdata-themewrite (useTheme.tsx:56-57) — same reason: it must be on the element before paint- Persist in the existing
useEffect: secondsetItem+[theme, palette]dependency array (useTheme.tsx:59-66) const setPalette = useCallback((next: Palette) => { setPaletteState(next) }, [])(useTheme.tsx:77-79)ThemeContextValueextended withpalette: PaletteandsetPalette: (palette: Palette) => void(useTheme.tsx:11-12); provider value at:82. NocyclePalette: the UI is a menu that names its options, and a cycle hides which value is which- Consumers after the change (
grep -rn useTheme src):Navigation.tsx:10(cycleTheme,resolvedTheme) andThemePaletteMenu.tsx:13(palette,setPalette);App.tsx:3only mounts the provider
Step 3 — index.html init script
Extend the existing IIFE (index.html:8-20) so both attributes land before paint:
var storedPalette = localStorage.getItem('portfolio-palette')
document.documentElement.setAttribute(
'data-palette',
storedPalette === 'blue' ? 'blue' : 'red'
)
Inside the same try / catch; the catch branch sets data-theme = 'dark' and data-palette = 'red'.
Step 4 — src/i18n/strings.ts
Into strings.nav (after contact, strings.ts:8):
palette: {en: 'Theme color', vi: 'Màu giao diện'},
paletteAria: {en: 'Switch theme color', vi: 'Đổi màu giao diện'},
Shipped at src/i18n/strings.ts:9-10, matching the file's existing {en: …, vi: …} formatting.
The option names and hints come from src/data/palettes.ts (content stays data-driven, per AGENTS.md).
Step 5 — src/components/layout/ThemePaletteMenu.tsx
Shipped as specified in §6: variant: 'nav' | 'sheet', local open state, containerRef + triggerRef, useClickOutside(containerRef, close) with a useCallback-stable close, onKeyDown on the wrapper for Escape (close + refocus the trigger), panel visibility by class (nav-palette-panel / .open) rather than the hidden attribute, so aria-controls always resolves and the options are untabbable while closed. No arrow-key handler, no role="menu".
Step 6 — src/components/layout/Navigation.tsx
- Nav variant after the theme toggle:
Navigation.tsx:76, inside.nav-actions, before the language toggle (:78-85). - Sheet variant after
</ul>inside.mobile-menu:Navigation.tsx:125, mounted as<ThemePaletteMenu key={location.pathname} variant="sheet" />so navigation remounts it closed. - No new state in
Navigation; the menu owns its own open state.
Step 7 — src/index.css
- Added the two blue blocks after
:root[data-theme='light'](src/index.css:60-85) and before the media bridge (src/index.css:152-180):src/index.css:87-114dark,:116-141light. Order is not what makes them win — the two-attribute selectors are 0,3,0 against 0,1,0 and 0,2,0 — but keeping them adjacent to their lightness parents is what makes the file readable. - Added the preview declaration block from §6:
src/index.css:143-150. - Left the three existing blocks and the bridge untouched: no blue variant is needed in the bridge, because the init script always writes
data-palette, so anything reaching the bridge has no stored palette and resolves to red.
Step 8 — src/App.css
Shipped: .nav-palette-nav { display: none } was added to the existing @media (max-width: 1024px) nav block (src/App.css:176-188) rather than inventing a second media block, and the menu block is src/App.css:190-367: .nav-palette, .nav-palette-trigger (+ :hover/.open, :focus-visible), .nav-palette-swatch, .nav-palette-group, .nav-palette-trigger .chevron (+ rotate), .nav-palette-panel (+ .open), .nav-palette-option (+ .active, ::after glyph, :hover, :focus-visible), .nav-palette-preview[data-preview=…], .nav-palette-name, .nav-palette-hint, then the .nav-palette-sheet overrides. Rules use tokens only — no hex, no rgba(), type sizes only inside the 12–14px chrome band, sheet text at var(--text-body) / var(--text-meta), and no fontSize/lineHeight in TSX.
Step 9 — cutover
- No deprecated paths:
Paletteis new,Themeis unchanged, no aliases, no shim. - Existing visitors keep red: an absent
portfolio-paletteresolves to'red', so behaviour for every current user is byte-identical to today. spec-v3-theme-switch.md§Step 5 must be corrected: the footer has no theme control (verified againstsrc/components/layout/Footer.tsx).
8. Edge cases
| Case | Behaviour |
|---|---|
localStorage throws (private mode, blocked) |
try/catch already in place: theme falls back to system/dark, palette falls back to 'red'; the attribute is still set during render, only persistence is skipped |
| JS disabled / script blocked | data-theme absent → the prefers-color-scheme bridge paints light-red or dark-red; no blue. Documented degradation, no broken layout |
Reload with blue stored |
init script sets data-palette='blue' before paint → no red flash |
| Palette menu open, then hamburger opened | impossible by construction at ≤1024px: the options are inside the sheet, so there is only one open surface at a time |
| Palette menu open, then route change | nav variant: the click that navigated is outside ref, so useClickOutside already closed it. Sheet variant: key={location.pathname} remounts it. No effect, no new lint finding |
data-theme absent and data-palette='blue' |
unreachable: both attributes are written by the same init script (index.html:8-20) and by the provider during render (useTheme.tsx:39), always together. If the script is blocked, data-palette is absent too → red, and the prefers-color-scheme bridge decides lightness |
| Context value identity changes | setPalette produces a new provider value object → Navigation re-renders. It is the only useTheme() consumer, so the cost is one subtree |
| Very narrow viewport (320px) | the nav variant is hidden at ≤1024px, so the bar keeps three controls; the sheet row carries the full label |
the palette follows the screen attributes; the resume PDF is generated from public/resume-template.html with its own print inks and is unaffected |
|
color-scheme |
stays dark / light per lightness block; blue blocks re-declare the same value as their lightness parent so form controls do not flip |
9. Affected files
| File | Action |
|---|---|
src/types/index.ts |
+1 line: export type Palette = 'red' | 'blue'; |
src/data/palettes.ts |
new — palette id + Record<Language, string> label and hint, same shape as src/data/resume.ts |
src/hooks/useTheme.tsx |
+palette state, getInitialPalette, data-palette set during render, setPalette, context value extended (~18 lines) |
index.html |
init script extended to set data-palette before paint (+4 lines) |
src/i18n/strings.ts |
+2 keys in strings.nav |
src/components/layout/ThemePaletteMenu.tsx |
new component |
src/components/layout/Navigation.tsx |
+2 insertions (nav variant, sheet variant) |
src/index.css |
+2 blue palette blocks, +1 preview declaration block |
src/App.css |
+1 nav-palette block, +1 mobile override |
docs/design/specs/v3/spec-v3-theme-palette-switch.md |
this document |
docs/design/specs/v3/spec-v3-theme-switch.md |
correct the stale Footer claim in §Step 5 |
AGENTS.md |
Theming section: add the palette axis, data-palette, portfolio-palette |
src/components/index.ts |
no change — the barrel is partial (it omits RollingTextLink, DownloadResume, BackToTop) and Navigation.tsx imports its children by path |
Not touched: src/components/layout/Footer.tsx, scripts/generate-resume.ts, public/resume-template.html, nginx.conf, docker-compose.yaml, any data module other than the new palettes.ts.
10. Decision record (settled by the owner, 2026-10-16)
| # | Question | Decision | Consequence |
|---|---|---|---|
| 1 | Leave red's --accent-soft / --accent-glow on #ef4444, or re-derive them from the accent in force? |
Re-derive | Applied in src/index.css (6 lines across the dark block, the light block and the bridge); re-measured, no AA regression — §5 "Red, re-derived" |
| 2 | One menu carrying both axes, or two separate controls? | Two separate menus | The sun/moon dark↔light button stays exactly as is (Navigation.tsx:57-73); the new Red↔Blue menu is a second, independent control. .nav-actions therefore keeps three controls on mobile because the palette options live inside the mobile sheet (§6) |
| 3 | Vietnamese label | Xanh dương |
src/data/palettes.ts as written in §7 Step 1 |
| 4 | Default palette | red |
An absent portfolio-palette resolves to 'red': existing visitors see no change |
11. Acceptance criteria
data-paletteis present on<html>before first paint on every load (verified by reading the served HTML with JS disabled and withportfolio-palette=bluepre-set).:root[data-theme='dark'][data-palette='blue']and:root[data-theme='light'][data-palette='blue']beat both base blocks (verified by computed style in the browser, not by reasoning).- All four combinations render without a flash, without a layout shift, and with the same geometry as today (measure: nav height 64px, container widths, timeline gutter 36/28 unchanged).
- Contrast script over the four blocks reports zero text pairs below 4.5 and the layering invariant holds. DONE 2026-10-17 — 21 required pairs × 4 palettes, minima 4.96 / 4.63 / 4.81 / 4.64, layering holds in all four (§5).
- Menu opens/closes by click,
Escape, outside click, and on navigation; options reachable byTabwhen the panel is open and out of the tab order when it is closed;aria-expanded+aria-controlson the trigger,aria-current="true"on the selected option. - Desktop (>1024px): menu sits in
.nav-actions, panel right-aligned to the trigger and fully inside the viewport. ≤1024px: palette options appear inside the mobile menu sheet, each ≥44px tall;.nav-actionsstill holds exactly theme + language + hamburger. - Palette choice survives a reload and a route change; theme choice survives a palette change and vice versa.
pnpm exec tsc -bexit 0. DONE — exit 0, no diagnostics.pnpm exec vite build --outDir dist-verifygreen, thenrm -rf dist-verify. DONE —✓ built in 148ms, CSS 31.80 kB (gzip 6.54), JS 450.14 kB (gzip 140.55);dist-verifyremoved.pnpm exec oxlint -c .oxlintrc.json srcstays at 11 errors / 9 warnings. DONE —grep -cE " (error|warning) "prints 20 finding lines, identical to the pre-feature baseline; the 11 errors are still thereact-hooks(rules-of-hooks)findings onuseField/useFieldArray.- Grep gate
#[0-9a-fA-F]{3,8}\b|rgba?\(oversrc/App.cssreturns zero matches. DONE — 0 matches; the new block is token-only, and the new literals insrc/index.cssare confined to:87-150. - Grep gate
style=\{\{[^}]*(fontSize|lineHeight|fontWeight|color|maxWidth)oversrc/still returns zero. DONE — 0 matches. pnpm build:resume-allunchanged. DONE, with a caveat — both PDFs regenerate at the same sizes as before the feature (1,987,582 EN / 1,990,541 VI bytes) andscripts/generate-resume.ts+public/resume-template.htmlare untouched ingit status;pdftotextis not installed here, so no text-level diff was run.- Browser pass by the owner:
/,/experience,/projects/:id,/philosophy× {dark, light} × {red, blue}, plus ≤1024px with the mobile sheet open and the palette block visible. - Red's re-derived
--accent-softwash keeps--accenttext ≥ 4.5 over every background it is used on, and the wash stays visible against its background (≥ 1.10). DONE — §5, worst pair 4.51. - After the re-derivation:
tsc -bexit 0,vite buildgreen,src/App.cssliteral-hex gate 0 matches, oxlint unchanged, both resume PDFs regenerate with the five entries and noundefined. DONE — emitted CSS carries#f871711f,#f871714d,#b041381a,#b0413838. - No duplicate element ids. DONE — an SSR render of both variants side by side (
vite.ssrLoadModule+react-dom/server, throwaway script, since removed) produced exactly oneid="palette-menu-nav"and oneid="palette-menu-sheet", each matched by its ownaria-controls. - Closing the menu on navigation adds no
react(set-state-in-effect)finding. DONE — the oxlint finding count is unchanged afterkey={location.pathname}was added.
12. Progress tracking
| Item | Status |
|---|---|
| §4 model, §5 token values, §6 UI design, §7 steps | DONE (this document) |
| Contrast verification for blue dark + blue light | DONE — measured, §5 |
Red --accent-soft / --accent-glow re-derived + re-measured (decision 1) |
DONE — applied at src/index.css:13,15,71,73,100,102; measured table in §5; worst pair 4.51 |
| Owner decisions §10 | DONE — settled 2026-10-16 |
| §6–§7 review pass against the shipped code (2026-10-17) | DONE — 9 corrections, recorded in §13 |
| Doc corrections listed in §13 | DONE — all four applied 2026-10-17, evidence in the §13 table |
Step 1 type + src/data/palettes.ts |
DONE — src/types/index.ts:3, src/data/palettes.ts (paletteIds + paletteMeta, 8 lines) |
| Step 2 hook | DONE — src/hooks/useTheme.tsx:2,11-12,18,33-43,51,57,59-66,77-79,82 |
| Step 3 init script | DONE — index.html:15-17,20 |
| Step 4 strings | DONE — src/i18n/strings.ts:9-10 |
| Step 5 component | DONE — src/components/layout/ThemePaletteMenu.tsx (79 lines) |
| Step 6 navigation | DONE — src/components/layout/Navigation.tsx:7,76,125 |
Step 7 src/index.css blocks |
DONE — src/index.css:87-141 (blue dark + light), :143-150 (preview tokens) |
Step 8 src/App.css menu styles |
DONE — src/App.css:176-188 (media rule added), :190-367 (menu block) |
Step 9 doc corrections (spec-v3-theme-switch.md, AGENTS.md) |
DONE |
| Owner browser pass, 4 combinations × mobile | TODO — repo rule §5: the owner verifies in a real browser |
13. Review pass against the shipped code (2026-10-17)
Every claim below was checked against the files, not carried over from the v0.1.0 draft.
| # | What was wrong or missing in v0.1.0 | Correction | Evidence |
|---|---|---|---|
| 1 | Hard-coded id="palette-menu-nav" |
id derived from variant |
both instances mount simultaneously, one hidden by CSS → duplicate ids, broken aria-controls |
| 2 | role="menu" + menuitemradio + arrow keys with no focus management |
disclosure semantics + aria-current="true" |
menu semantics without arrow keys / roving tabindex is a known anti-pattern |
| 3 | Close-on-navigate written as an effect | key={location.pathname} on the sheet instance + click-outside for the nav instance |
Navigation.tsx:25-27 is exactly the pattern oxlint reports as set-state-in-effect (1 warning already at :26); an effect here would make it 10 |
| 4 | hidden={!open} on the panel |
open class + display: none |
repo idiom src/App.css:720-726 |
| 5 | Invented .nav-palette-chevron |
reuse the chevron class |
src/App.css:714-717, :728-730 |
| 6 | Panel anchored left: 0 (copied from the download dropdown) |
right: 0 inside .nav-palette { position: relative } |
the trigger is at the right edge of .nav-container (src/App.css:12-20) |
| 7 | 768px palette breakpoint | 1024px | .nav-menu / .mobile-menu-btn collapse at 1024 (src/App.css:176-184) |
| 8 | palettes.ts with { en, vi } literals |
Record<Language, string> |
src/data/resume.ts:6-9 |
| 9 | "three consumers depend on resolvedTheme" |
one consumer | useTheme( has exactly one call site: Navigation.tsx:9 |
| 10 | palettes array + a paletteLabel(id, lang) lookup helper |
paletteIds + paletteMeta keyed by Palette, indexed inline |
the project rule ts-no-tiny-functions rejects a one-expression wrapper; the keyed map also drops the find and the entry ? … : id fallback, which could only ever hide a type error |
| 11 | A @media (max-width: 1024px) block invented for the palette |
.nav-palette-nav { display: none } added to the existing nav media block (src/App.css:176-188) |
one breakpoint, one block — the palette collapses with the links |
| 12 | Trigger markup with no group label | .nav-palette-group added: hidden in the bar, shown in the sheet |
the sheet row must name the setting on its own; the bar trigger is already named by its aria-label |
| 13 | UI label "Theme colour" | "Theme color" | house spelling is US (spec.md §26 "Color System", spec-v3-theme-colors.md "Theme Colors"); a UI label is not prose |
| 14 | Escape only closes the panel |
Escape closes and returns focus to triggerRef |
closing hides the element that had focus, which would otherwise drop focus to <body> |
Confirmed by the review, no work needed:
- No hex or
rgba()literal outside palette declaration blocks anywhere insrc/. Thedata-theme-keyed rules atsrc/App.css:649-671reference tokens only, so they apply unchanged in blue-light. .mobile-menuisdisplay: noneunless.openand alreadyoverflow-y: auto(src/App.css:125-141) → the sheet row cannot be tabbable while closed and cannot overflow a short screen.index.htmlhas notheme-colormeta to keep in sync.ThemeProviderwrapsLayout(src/App.tsx:19-21) →useThemeanduseLanguageare both available insideNavigation.scripts/generate-resume.tsandpublic/resume-template.htmlreference no theme token → the PDFs are unaffected by palette work.
Doc corrections owed elsewhere
| File | Correction |
|---|---|
spec-v3-theme-colors.md:71 |
APPLIED 2026-10-17 — claimed #6b7280 on #0f1117 is "~4.8:1 (AA pass)"; measured 3.90:1, an AA fail. The line is now marked as a fail with a pointer to §5 of this spec as the measured blue replacement |
spec-v3-theme-palette-gasatrya.md |
APPLIED 2026-10-17 — the four token-table rows and the three code snippets that recorded rgba(239, 68, 68, …) now carry the re-derived values (rgba(248,113,113,0.12) / 0.30 dark, rgba(176,65,56,0.10) / 0.22 light), with a dated note explaining that the hue source is the accent in force |
spec-v3-theme-switch.md §Step 5 |
APPLIED 2026-10-17 — the Footer.tsx consumer claim removed; the verified consumer list replaces it |
AGENTS.md Theming section |
APPLIED 2026-10-17 — palette axis, data-palette, portfolio-palette, the selector form and the two menu placements recorded; ThemePaletteMenu.tsx and palettes.ts added to the structure block |
14. Implementation record (2026-10-17)
Steps 1–8 applied on feature/new-theme-color. Nothing committed — the owner decides.
| Check | Result |
|---|---|
pnpm exec tsc -b |
exit 0, no output |
pnpm exec vite build --outDir dist-verify |
✓ built in 148ms; CSS 31.80 kB (gzip 6.54), JS 450.14 kB (gzip 140.55); dist-verify removed afterwards |
| Emitted CSS, selector order | :root[data-theme=light]{ … then :root[data-theme=dark][data-palette=blue]{, then :root[data-theme=light][data-palette=blue]{ — the blue blocks land after both base blocks, and win by specificity regardless of order |
| Emitted CSS, menu rules | .nav-palette-panel{…display:none…} + .nav-palette-panel.open{display:block} + .nav-palette-sheet .nav-palette-panel{…position:static}; the minified media block reads @media (width<=1024px){.nav-menu{display:none}.mobile-menu-btn{display:flex}.nav-palette-nav{display:none}} |
| Preview tokens in the bundle | --preview-red-accent:#b04138, --preview-red-bg:#f6f5f2, --preview-blue-accent:#2563eb, --preview-blue-bg:#f4f6f9 — one declaration each |
| SSR render, both variants at once | id="palette-menu-nav" ×1, id="palette-menu-sheet" ×1, aria-controls ×2 matching those ids, aria-expanded="false" ×2, aria-current="true" ×1 per instance, 4 preview chips, both panels without .open; trigger label Theme color: Red on the default palette with the default language en |
| Contrast | minima 4.96 / 4.63 / 4.81 / 4.64; zero required pairs < 4.5; layering invariant holds in all four |
| oxlint | 20 finding lines = 11 errors / 9 warnings, identical to the baseline before the feature |
| Grep gates | src/App.css hex/rgba() 0 matches; inline fontSize/lineHeight/fontWeight/color/maxWidth in TSX 0 matches |
| Resume PDFs | regenerated at the pre-feature byte sizes; generator and template untouched |
Deliberately not verified here (owner's browser pass, repo rule §5): computed style of the two-attribute selectors, the panel staying inside the viewport at narrow desktop widths, the ≤1024px sheet layout with 44px options, and the visual sweep over all four combinations.