# Specification — v3 Palette Preview Parity & Hamburger Side > **Document:** `spec-v3-nav-swatch-and-hamburger.md` > **Version:** 0.2.0 (drafted 2026-10-17; the owner answered Q1–Q5 the same day and the change was built) > **Parents:** `specs/v3/spec-v3-theme-palette-switch.md` (preview tokens, §Step 8), `specs/v3/spec-v3-nav-cta-enhancements.md` (the swatch gradient, §4.2), `specs/v3/spec-v3-mobile-navigation.md` (bar anatomy, Q13–Q16), `specs/ui/spec-ui-layout.md` (bar table) > **Priority:** P1 (item 1 is a colour defect, item 2 is an ergonomics request) > **Estimate:** ~35 minutes including the gate re-run > **Status:** BUILT 2026-10-17 — Steps 1–6 on disk, §11.1 records the gate run. Open: the owner's browser pass (§8, repo rule §5) and the commit decision. --- ## 1. Request 1. **The red/blue colours in the palette submenus do not match the red/blue in the navigation bar's theme icon (`.nav-palette-swatch`).** The owner suspects the gradient. 2. **Move the mobile menu button (`.mobile-menu-btn`) to the left of the bar** — the owner is left-handed and reaches the left side of a handheld bar more easily. Both items live in the navigation bar, so they are specified as one change set. --- ## 2. Current state (verified against the code, 2026-10-17) ### 2.1 Facts | Fact | Evidence | |---|---| | The bar swatch paints its left half with the **live** accent: `linear-gradient(to right, var(--accent) 0 50%, var(--swatch-empty) 50% 100%)`, 20×20, `border: 1px solid var(--border-strong)` | `src/App.css:340-347`; trigger markup `ThemePaletteMenu.tsx:44-49` | | `--accent` changes with **both** axes: dark red `#f87171`, light red `#b04138`, dark blue `#60a5fa`, light blue `#2563eb` | `src/index.css:9`, `:75`, `:110`, `:143` | | The submenu dots paint with **fixed constants**: `--preview-red-accent: #b04138`, `--preview-blue-accent: #2563eb`, declared once in a `:root` block that has no theme or palette axis | `src/index.css:171-177` | | Those two constants are exactly the **light-mode** accent values | `#b04138` = `src/index.css:75`, `#2563eb` = `src/index.css:143` | | The dots' 2px ring uses `--preview-red-bg: #f6f5f2` / `--preview-blue-bg: #f4f6f9` — the **light-mode** `--bg-primary` of each palette | `src/index.css:173`, `:175`, `:69`, `:137`; consumed at `src/App.css:419-427` | | Both submenu renderings share the same dot element, so both carry the same defect: the desktop `#palette-menu` panel and the sheet's Theme color row | `ThemePaletteMenu.tsx:64`, `MobileMenu.tsx:129` | | The documented intent of these tokens is *palette independence*, not theme independence: "a picker row previews its own palette rather than the active one" | `src/index.css:168-170`; restated in `spec-v3-theme-palette-switch.md:321-334` | | The active swatch option's border is the live accent, its dot is the constant | `src/App.css:290-293` + `:419-427` | | The hamburger is the **last** child of `.nav-actions` at every width, and appears at ≤1024px | `Navigation.tsx:113-146`, `src/App.css:300-308` | | `.nav-container` is `display: flex; justify-content: space-between` with three children: logo, `.nav-menu`, `.nav-actions` | `src/App.css:15-23`, `Navigation.tsx:58-147` | | `.mobile-menu-btn` is **not** a `.nav-control`: no border, `padding: 8px` around a 24px icon → 40px wide | `src/App.css:125-133`, `Navigation.tsx:123-143` | | Closing restores focus into the trigger only when it is rendered: `if (triggerRef.current?.offsetParent)` | `Navigation.tsx:19-23` | | The palette panel is anchored `right: 0` to its trigger, so its placement depends on the palette control staying near the bar's right end | `src/App.css:349-362` | | No CSS rule depends on `.mobile-menu-btn` being a descendant of `.nav-actions` | `grep 'mobile-menu-btn' src/App.css` → `:125`, `:135`, `:305` only | ### 2.2 The measurement that decides item 1 sRGB relative luminance, WCAG 2.x contrast ratios and CIE76 ΔE, computed 2026-10-17 from the hexes above. **Swatch accent half vs the submenu dot of the same palette:** | Theme | Palette | Swatch | Dot | Ratio | ΔE76 | |---|---|---|---|---|---| | dark | red | `#f87171` | `#b04138` | **2.07** | **22.4** | | dark | blue | `#60a5fa` | `#2563eb` | **2.03** | **42.5** | | light | red | `#b04138` | `#b04138` | 1.00 | 0.0 | | light | blue | `#2563eb` | `#2563eb` | 1.00 | 0.0 | The mismatch is **dark-mode only**, and it is large: a factor >2 in luminance, and ΔE76 42.5 for blue — far past the ~2.3 just-noticeable threshold. **Dot legibility against the surface it sits on** (`--bg-elevated` for the panel, `--bg-surface` for the sheet): | Surface | Today | After parity | |---|---|---| | dark red panel `#272a28` | **2.53** | **5.24** | | dark blue panel `#1c2030` | **3.13** | **6.36** | | dark red sheet `#202423` | **2.73** | **5.67** | | dark blue sheet `#161922` | **3.40** | **6.90** | | light red panel `#ffffff` | 5.74 | 5.74 | | light blue panel `#ffffff` | 5.17 | 5.17 | In dark mode today the dots sit **below the 4.5 floor** this project uses for its contrast gates (`spec-v3-mobile-navigation.md` §9, `spec-v3-nav-cta-enhancements.md` §8). Parity lifts every dark case above it. **Ring colour against the same surfaces:** | Surface | Today (`--preview-*-bg`) | `--border-strong` | palette `--bg-primary` | |---|---|---|---| | dark red panel `#272a28` | **13.30** | 1.36 | 1.23 | | dark blue panel `#1c2030` | **14.94** | 1.60 | 1.17 | | dark red sheet `#202423` | **14.40** | 1.48 | 1.13 | | dark blue sheet `#161922` | **16.21** | 1.74 | 1.07 | | light red panel `#ffffff` | 1.09 | 1.45 | 1.09 | | light blue panel `#ffffff` | 1.08 | 1.43 | 1.09 | The ring is a near-white halo in dark mode (13–16) and an almost invisible hairline in light mode (1.08–1.09). `--border-strong` — the token the bar swatch already uses — gives 1.36–1.74 dark and 1.43–1.45 light: the same *kind* of ring in both themes. **Active-state inconsistency, dark mode:** `.mobile-menu-swatch-option.active` draws a live-accent border around a constant dot — 2.07 (red) and 2.03 (blue) between the ring and the fill it surrounds. ### 2.3 Is the gradient the cause? Partly. - **Not the cause of the hue difference.** The dots are flat `background` fills; the swatch's accent half is `var(--accent)`. The hue diverges because the dot reads a **constant pinned to the light-mode values** while the swatch reads a **live per-theme value**. In light mode the two constants happen to equal `--accent`, which is why the defect is invisible there. - **The gradient *is* the reason the two read as different objects.** The swatch is a half-disc (accent | `--swatch-empty` white) with a 1px hairline; the dot is a full disc with a 2px ring that eats 2px from each side, leaving a 14px fill against the swatch's 20px. Even with identical hexes, an 18px 14px-core disc and a 20px half-disc read differently. Shape parity is a separate decision (Q3). --- ## 3. Root causes | # | Cause | Where | |---|---|---| | C1 | The preview accent constants were written from the light-mode accent values and never given a dark-mode counterpart. | `src/index.css:171-177` | | C2 | The preview ring constants were written from the light-mode `--bg-primary` values, same omission. | `src/index.css:173`, `:175` | | C3 | Two colour sources for one identity: the swatch uses the theme-resolved `--accent` family, the dots use a parallel constant family. Nothing keeps them equal, so they drift. | `src/App.css:346` vs `src/App.css:420`, `:425` | | C4 | The hamburger's position is a markup decision, frozen by Q16 ("the hamburger stays last in the bar"). The request supersedes that half of Q16. | `Navigation.tsx:113-146`, `spec-v3-mobile-navigation.md:795`, `:806`, `spec-ui-layout.md:106`, `AGENTS.md:61` | --- ## 4. Design — item 1: preview parity ### 4.1 Token strategy (Q1) | Option | Shape | Cost | Verdict | |---|---|---|---| | **A — theme-aware preview tokens** | Declare `--preview-red-accent` / `--preview-blue-accent` inside the theme blocks, mirroring that block's `--accent`. 6 new declarations across 3 blocks. | Small; touches only `src/index.css`; keeps the documented palette-independent contract intact | **Recommended** | | B — structural dedup: name each palette's accent once (`--accent-red`, `--accent-blue`) and let `--accent` alias it | Parity becomes impossible to break; zero duplicated hexes | Re-plumbs the accent declaration chain in 4 blocks, re-documents the token contract in `spec-v3-theme-colors.md`, `spec-v3-nav-cta-enhancements.md` §4.3 and `AGENTS.md:59`, and leaves the `-hover`/`-active`/`-solid`/`-glow` family palette-scoped — a half-renamed system | Rejected: larger blast radius than the defect warrants | | C — Option A plus an equality gate | A throwaway check asserting each `--preview-*-accent` equals the matching block's `--accent` | ~10 lines, deleted after the run | **Adopted alongside A** — it is what stops the duplication from drifting again | The palette axis needs **no** override, and that is the invariant that makes Option A small: a preview is chosen by `data-preview='red'|'blue'`, so its token is keyed by palette name, never by the active palette. `:root[data-theme='dark'][data-palette='blue']` and `:root[data-theme='light'][data-palette='blue']` therefore declare nothing — the dark pair from `:root` and the light pair from `:root[data-theme='light']` are already the right values for both palettes. ### 4.2 Ring treatment (Q2) | Option | Result | Verdict | |---|---|---| | **A — shared hairline**: `border: 1px solid var(--border-strong)`, delete `--preview-red-bg` and `--preview-blue-bg` | One ring style everywhere (the swatch already uses this token at `src/App.css:345`); 1.36–1.74 dark, 1.43–1.45 light; two tokens removed; the fill gains 2px of diameter (14 → 16 core) | **Recommended** | | B — theme-aware ring values (each palette's own `--bg-primary` per theme) | Keeps the "the ring is that palette's world" idea; 1.07–1.23 dark, 1.08–1.09 light — nearly invisible in both; 4 more declarations to maintain | Rejected: four tokens for a ring the eye cannot separate | | C — keep today's constants | 13.30–16.21 halo in dark, 1.08 in light — the inconsistency the owner is seeing is partly this | Rejected | ### 4.3 Shape parity (Q3) | Option | Result | Verdict | |---|---|---| | **A — keep the full disc** | The dot stays a clean colour chip; only the colours change. The row stays legible at 18px | **Recommended** | | B — make the previews half-circles like the bar icon (`linear-gradient(... var(--preview-*-accent) 0 50%, var(--swatch-empty) 50% 100%)`) | Literal identity with `.nav-palette-swatch`, and `--preview-*-bg` becomes unnecessary | Rejected for now: half of every option renders white, which weakens the colour signal at 18px and makes the two options look half-coloured | --- ## 5. Design — item 2: hamburger on the left ### 5.1 Placement (Q4) | Option | Bar at ≤1024px | Verdict | |---|---|---| | **A — brand group on the left**: wrap the hamburger and the logo in `.nav-brand` as the first child of `.nav-container`; `.nav-actions` keeps language → mode → theme color | `☰ {CV}` … `VI ☀ ◕` | **Recommended** | | B — hamburger as a bare first child, logo left to `space-between` | `☰` … `{CV}` … controls — the brand drifts to the centre of the bar | Rejected: the logo loses its fixed anchor and the row's centre becomes variable | | C — keep the hamburger in `.nav-actions` and move the whole cluster to the left | controls on the left, brand on the right | Rejected: the brand leaves the left edge, and the palette panel's `right: 0` anchor (`src/App.css:353`) would then hang off the bar's left side | | D — CSS only: `.nav-actions { display: contents }` + `.mobile-menu-btn { order: -1 }` | visual order `☰ VI ☀ ◕`, DOM order `VI ☀ ◕ ☰` | Rejected: Tab order no longer matches visual order (WCAG 2.4.3), and `display: contents` discards the box whose `gap` the layout depends on — `.nav-actions { gap }` at `src/App.css:86` and `:317-319` would both stop applying | Option A keeps **DOM order = visual order = Tab order**, which is why it is chosen over every CSS-only variant. ### 5.2 Consequences that must hold | Concern | Outcome | |---|---| | Desktop (>1024px) | Unchanged. `.mobile-menu-btn` is `display: none` (`src/App.css:126`), so `.nav-brand` renders as the logo alone, and `.nav-container`'s three children are still brand / `.nav-menu` / `.nav-actions` under the same `space-between`. | | Palette submenu position | Unchanged. The palette trigger remains the last control in `.nav-actions`, so `#palette-menu`'s `right: 0` anchor still opens it inside the viewport. | | Close-focus guard | Still correct. `offsetParent` is null when the element itself is `display: none`, regardless of the new wrapper, so `Navigation.tsx:22` keeps skipping the restore above 1024px. | | Sheet, `inert` targets, Escape, scroll lock | Untouched. | | Row fit at 320px | **Tighter — this is the one real cost.** Measured 2026-10-17: today the intrinsic widths are logo ~70 + 44×3 + hamburger 40 + 3×12 gaps = **242px**, and `space-between` distributes the remaining **46px** between brand and controls. After the move the brand group's 12px gap becomes fixed: 40 + 12 + 70 + 44×3 + 2×12 = **278px**, leaving **10px** of slack inside 288px. Mitigation: `.nav-brand { gap: 8px }` at ≤420px → 274px, 14px slack. | | Stale arithmetic in the code comment | `src/App.css:310-311` claims `~70 + 44×4 + 12×3 = 262px` with "26px of slack". The same row measures 242px intrinsic / 46px distributed today; 262 matches neither. The comment is corrected as part of this change. | --- ## 6. Implementation Details ### Step 1 — preview accents become theme-aware (`src/index.css`) Delete the fixed-identity block at `:168-177` and move its surviving tokens into the theme blocks. `src/index.css:2-27` (`:root`, dark red) — after `--accent-glow` (`:23`): ```css /* Picker previews: each row previews its own palette, never the active one — the token is keyed by palette name, not by --accent. Values mirror this block's --accent so a dot and the bar's swatch half are the same colour in the same theme. */ --preview-red-accent: #f87171; --preview-blue-accent: #60a5fa; --swatch-empty: #ffffff; ``` `src/index.css:68-92` (`:root[data-theme='light']`) — after `--accent-glow` (`:87`): ```css --preview-red-accent: #b04138; --preview-blue-accent: #2563eb; ``` `src/index.css:180-212` (the `prefers-color-scheme: light` bridge) — after `--accent-glow` (`:199`): ```css --preview-red-accent: #b04138; --preview-blue-accent: #2563eb; ``` `src/index.css:103-127` and `:136-166` (the two `[data-palette='blue']` blocks) — **no change**, per §4.1. Cascade check: `:root` = 0,1,0; `:root[data-theme='light']` = 0,2,0; `:root:not([data-theme='dark'])` = 0,2,0 and sits later, so a pre-hydration light page gets the light pair, and a light page with `data-theme='light'` set gets the same values from either selector. `--swatch-empty` stays a single constant declaration in `:root`, as documented at `src/index.css:168-170` and `AGENTS.md:60`. ### Step 2 — one ring everywhere (`src/App.css:411-427`) ```css .nav-palette-preview { flex: none; width: 18px; height: 18px; border-radius: 50%; border: 1px solid var(--border-strong); } .nav-palette-preview[data-preview='red'] { background: var(--preview-red-accent); } .nav-palette-preview[data-preview='blue'] { background: var(--preview-blue-accent); } ``` `border: 2px solid` + two `border-color` overrides → one 1px hairline using the token the swatch already uses (`src/App.css:345`). `--preview-red-bg` and `--preview-blue-bg` lose their last consumer and are **not** carried into Step 1. ### Step 3 — swatch comment (`src/App.css:338-339`) Restate the pairing so the next reader knows the two are meant to agree: the swatch's left half is the live `--accent`; the submenu dots read `--preview-*-accent`, which mirror the same per-theme accent values. No selector change. ### Step 4 — brand group (`src/components/layout/Navigation.tsx`) Move the whole hamburger button block (`:113-146`) out of `.nav-actions` (`:83-147`) and place it before the logo, wrapping both: ```tsx