diff --git a/docs/design/specs/ui/spec-ui-layout.md b/docs/design/specs/ui/spec-ui-layout.md index 9750677..dffb442 100644 --- a/docs/design/specs/ui/spec-ui-layout.md +++ b/docs/design/specs/ui/spec-ui-layout.md @@ -113,7 +113,7 @@ Spec: `specs/v3/spec-v3-theme-palette-switch.md`. |---|---| | Trigger | Hamburger button in the bar, ≤1024px | | Groups | Menu (6 routes) → Appearance (Language, Mode, Theme color) → Connect (GitHub, LinkedIn, email) | -| Behaviour | `role="dialog"` + `aria-modal="true"`, Escape closes from any focus position, `#main-content` / `.footer` / `.back-to-top` are `inert` while open, body scroll locked | +| 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`. diff --git a/docs/design/specs/v3/spec-v3-mobile-navigation.md b/docs/design/specs/v3/spec-v3-mobile-navigation.md index 6c65ea7..5c33a21 100644 --- a/docs/design/specs/v3/spec-v3-mobile-navigation.md +++ b/docs/design/specs/v3/spec-v3-mobile-navigation.md @@ -1,11 +1,11 @@ # Specification — v3 Mobile Navigation Menu (social links + modern sheet) > **Document:** `spec-v3-mobile-navigation.md` -> **Version:** 0.7.0 (seven owner decisions + three review answers resolved 2026-10-17, then six post-build follow-ups Q11–Q16; the review pass re-measured §3.3, corrected the Escape/focus/`inert` rules, moved the social aria strings, and pinned the nav order — Q16 puts it at Language → Mode → Theme in the bar and in the sheet) +> **Version:** 0.8.0 (seven owner decisions + three review answers resolved 2026-10-17, then six post-build follow-ups Q11–Q16 and one owner-reported defect — the sheet rolled the Home link on open; the review pass re-measured §3.3, corrected the Escape/focus/`inert` rules, moved the social aria strings, pinned the nav order at Language → Mode → Theme (Q16), and moved the sheet's focus target onto the panel itself) > **Parents:** `specs/ui/spec-ui-layout.md` (navigation layout), `spec-v3-i18n.md` (translated chrome), `spec-v3-theme-palette-switch.md` (palette row, contrast table at `:145-159`), `spec-v3-typography.md` (type tokens, chrome band) > **Priority:** P1 > **Estimate:** ~2.5 hours including the social-links cutover -> **Status:** DECISIONS CLOSED — §10 records the seven owner answers, the three review answers (Q8–Q10) and the six post-build follow-ups (Q11–Q16). §3.2's contrast measurement was reproduced independently and stands. §3.3's height arithmetic was wrong — drafted 596px, actually 736px as drafted, 643px with the Step 8 tightenings, 647px after Q13 — and is rewritten. Steps 1–9 plus Q12–Q16 are built and gated (§12); the five criteria that can only be observed live all wait on the owner's browser pass (§11) +> **Status:** DECISIONS CLOSED — §10 records the seven owner answers, the three review answers (Q8–Q10) and the six post-build follow-ups (Q11–Q16). §3.2's contrast measurement was reproduced independently and stands. §3.3's height arithmetic was wrong — drafted 596px, actually 736px as drafted, 643px with the Step 8 tightenings, 647px after Q13 — and is rewritten. Steps 1–9 plus Q12–Q16 are built and gated (§12), as is the 2026-10-17 focus defect fix (the sheet no longer rolls the Home link on open); the five criteria that can only be observed live all wait on the owner's browser pass (§11) --- @@ -202,7 +202,7 @@ Total perceived open time: 220ms panel + 330ms last row ≈ 0.55s. Nothing loops | Open | hamburger, with `aria-expanded` (already) plus new `aria-controls="mobile-menu"` | | Close | hamburger, any nav link click, `Escape` — handled on `document` while the sheet is open (see the Escape row below) | | Navigation | every sheet link carries `onClick={close}` (already the case, `Navigation.tsx:116`); the redundant route effect (D3) is **deleted**, and with it the `key={location.pathname}` reset on the palette instance — conditional mount resets it | -| Focus | open → first sheet link, via `onAnimationComplete` on the panel (no effect, no lint finding) — note that lands ~220ms after the click, and the callback also fires for the exit animation, where `firstLinkRef.current` is already null: the optional chain covers it. Close → `triggerRef.current?.focus()`, mirroring `ThemePaletteMenu`'s Escape handler (`ThemePaletteMenu.tsx:22-26`), **but only when the trigger is rendered**: `.mobile-menu-btn` is `display: none` above 1024px (`src/App.css:109-110`), so a close caused by the media-query subscription must skip the restore (`if (triggerRef.current?.offsetParent)`) rather than fail silently and drop focus to `` mid-navigation | +| Focus | open → **the panel itself**: `tabIndex={-1}` + `ref={sheetRef}` on the panel, focused in `onAnimationComplete` (~220ms after the click, no effect, no lint finding; the callback also fires for the exit animation, where the ref is already null — the optional chain covers it). The drafted version focused the first sheet link, and that was a defect: `RollingTextLink` rolls its text on `onFocus`, so every open rolled "Home" whatever the route. A focusable container is also the standard dialog target, and Tab from it still reaches the Home link first. Close → `triggerRef.current?.focus()`, mirroring `ThemePaletteMenu`'s Escape handler (`ThemePaletteMenu.tsx:22-26`), **but only when the trigger is rendered**: `.mobile-menu-btn` is `display: none` above 1024px (`src/App.css:109-110`), so a close caused by the media-query subscription must skip the restore (`if (triggerRef.current?.offsetParent)`) rather than fail silently and drop focus to `` mid-navigation | | Background | the existing scroll-lock effect (`Navigation.tsx:15-24`) also sets `inert` on `#main-content`, `.footer` **and `.back-to-top`** while open and clears all three on close. `Layout.tsx:17` renders `` as a sibling of the other two, and `.back-to-top` is `position: fixed; bottom/right: 24px; z-index: 100` (`src/App.css:1820-1837`) — painted under the sheet (z 999) yet Tab-reachable unless it is inert. Imperative DOM work in the effect that already does imperative DOM work, so no new context and no new provider | | Bar while open | stays operable on purpose: the hamburger is the sheet's own close control. A focus trap would have to trap the bar too — more code, known source of stuck-focus bugs | | Semantics | sheet: `role="dialog" aria-modal="true" aria-label={translated}`; bar keeps `role="navigation" aria-label="Main navigation"` | @@ -372,22 +372,24 @@ export function MobileMenu({ open, onClose }: MobileMenuProps) { const { resolvedTheme, setTheme, palette, setPalette } = useTheme() const location = useLocation() const reduceMotion = useReducedMotion() - const firstLinkRef = useRef(null) + const sheetRef = useRef(null) return ( {open && ( firstLinkRef.current?.focus()} + onAnimationComplete={() => sheetRef.current?.focus()} >