— LoginPage.tsx untouched"
+ - "tokens.css --color-member-0 is the single source for brand accent; --sx-color-primary follows via var()"
+
+key-files:
+ created: []
+ modified:
+ - "apps/pwa/src/components/BrandSlot.tsx — placeholder FS div replaced with decorative logo img"
+ - "apps/pwa/src/styles/tokens.css — --brand-logo-border-radius: 0; --color-member-0: #e8915a"
+ - "apps/pwa/index.html — favicon.svg + favicon.ico links added; theme-color updated to #e8915a"
+ - "apps/pwa/vite.config.ts — maskable icon fixed to /icon-maskable-512.png; theme_color updated to #e8915a"
+
+key-decisions:
+ - "Applied --brand-logo-border-radius: 0 verbatim from 17-02 checkpoint (SVG rx=104 draws its own shape)"
+ - "Applied brand accent #e8915a verbatim from 17-02 checkpoint across all three files (Variant B)"
+ - "Favicon order: favicon.svg first (modern browsers), favicon.ico second (legacy) — per UI-SPEC wiring contract"
+ - "--color-focus-ring left at #4a90d9 — semantic accessibility token; not in scope for brand accent update"
+
+# Metrics
+duration: 4min
+completed: 2026-06-18
+status: complete
+---
+
+# Phase 17 Plan 04: Brand Wiring Summary
+
+**BrandSlot logo img wired from seam with no LoginPage change; favicon set + theme-color in index.html; manifest maskable icon fixed to /icon-maskable-512.png; brand accent #e8915a applied consistently across tokens.css, index.html, and vite.config.ts**
+
+## Performance
+
+- **Duration:** ~4 min
+- **Started:** 2026-06-18T16:47:28Z
+- **Completed:** 2026-06-18T16:51:02Z
+- **Tasks:** 2/2
+- **Files modified:** 4
+
+## Accomplishments
+
+### Task 1: BrandSlot logo img + --brand-logo-border-radius
+
+Replaced the Phase 19 placeholder `FS
` with a decorative `` for an `![]()
` and override the `--brand-logo-*` tokens — **without changing `LoginPage` layout** (the seam was built in Phase 19 precisely to isolate this). Keep the accessibility shape: `` carries the app name, logo image is decorative (`alt=""` / `aria-hidden`), no layout shift.
+
+### C — Theme-token groundwork
+- **D-06:** Restructure `tokens.css` into a themeable layer (semantic tokens resolvable per theme via `data-theme`/`prefers-color-scheme`) — **groundwork only** (option 3a). **Do NOT** author dark palette values, wire `prefers-color-scheme` to actually flip, or add a toggle this phase. Light remains the sole shipped theme. Keep the existing invariant: no hard-coded hex/px in component files — all values stay in `tokens.css`. The restructure must leave the Schedule-X `--sx-color-*` overrides (bottom of tokens.css) working unchanged.
+
+### D — UAT-surfaced UI findings (from Phase 19 live UAT, 2026-06-17)
+Surfaced by the operator during the Phase 19 local-auth UAT and **routed here by operator decision** — these are UI concerns, not Phase 19 auth blockers. Phase 19 ships functionally complete; Phase 17 owns the UI. (Recorded in `.planning/phases/19-local-auth-no-oidc-mode/19-UAT.md` as F-01…F-04.)
+- **D-07 (F-02) — Wire a logout control into the UI.** Logout is fully plumbed but unreachable: the endpoint `POST/GET /api/auth/local/logout` works (200, clears cookie — BL-02 verified live) and `fetchLocalLogout()` exists at `apps/pwa/src/api/client.ts:127`, but **no component calls it** (zero logout buttons in `apps/pwa/src`). Add a logout control (likely in `SettingsSheet.tsx` and/or `AppNav`) that calls the existing client function + redirects to `/login`. **No backend work** — UI wiring only. (Slightly beyond pure "polish" — it's a small new control; planner should size it.)
+- **D-08 (F-01) — Add success feedback to admin local-account actions.** Admin create-member and reset-password both succeed (verified at DB/login level in UAT) but show **no success toast/confirmation**, leaving the operator unsure it worked. Add success feedback to those admin flows (`AdminPage.tsx`).
+- **D-09 (F-03) — Fix dialog/popup positioning.** Popups/sheets render **bottom-center instead of properly centered**. Fits the fixed-chrome/sheet-positioning sweep already in workstream A; likely the same dialog/sheet CSS (`SettingsSheet.tsx` and shared dialog styles). Verify across phone + desktop via playwright-cli.
+- **D-10 (F-04) — Rework the clunky admin navigation.** Admin UI navigation reads as clunky and needs a rework. Larger UX item than the others — planner should decide whether it fits this phase's "polish" budget or warrants its own slice. (`AdminPage.tsx`, admin nav/tab surface.)
+
+### Claude's Discretion
+- **D-02** (fix technique + regression guard) is explicitly delegated to the researcher/planner.
+- Exact small-viewport issues surfaced by the `layout.spec` sweep (D-01) — fix as found, within the no-behaviour-change boundary.
+- Logo visual execution within the brand brief (see Specific Ideas) — subject to user approval at the checkpoint.
+
+### Folded Todos
+- **`2026-06-13-pwa-phone-bottombar-overlap.md`** (`area: pwa-ui`, `resolves_phase: 17`) — the phase's seed defect. Phone-layout fixed BottomTabBar overlaps the New Event FAB + colour legend at ≤767px. Reproduced 2026-06-13 via playwright-cli at 390×844 (FAB over Admin tab; "Dev User" legend clipped) vs 1280×800 (no overlap). Long-standing (BottomTabBar dates to Phase 04), not a Phase 10 regression. This is workstream A's anchor — its `files:` list (`App.tsx`, `BottomTabBar.tsx`, `CalendarShell.tsx`) is the fix surface.
+
+
+
` carries the app name, logo image is decorative (`alt=""` / `aria-hidden`), no layout shift.
+
+### C — Theme-token groundwork
+- **D-06:** Restructure `tokens.css` into a themeable layer (semantic tokens resolvable per theme via `data-theme`/`prefers-color-scheme`) — **groundwork only** (option 3a). **Do NOT** author dark palette values, wire `prefers-color-scheme` to actually flip, or add a toggle this phase. Light remains the sole shipped theme. Keep the existing invariant: no hard-coded hex/px in component files — all values stay in `tokens.css`. The restructure must leave the Schedule-X `--sx-color-*` overrides (bottom of tokens.css) working unchanged.
+
+### D — UAT-surfaced UI findings (from Phase 19 live UAT, 2026-06-17)
+Surfaced by the operator during the Phase 19 local-auth UAT and **routed here by operator decision** — these are UI concerns, not Phase 19 auth blockers. Phase 19 ships functionally complete; Phase 17 owns the UI. (Recorded in `.planning/phases/19-local-auth-no-oidc-mode/19-UAT.md` as F-01…F-04.)
+- **D-07 (F-02) — Wire a logout control into the UI.** Logout is fully plumbed but unreachable: the endpoint `POST/GET /api/auth/local/logout` works (200, clears cookie — BL-02 verified live) and `fetchLocalLogout()` exists at `apps/pwa/src/api/client.ts:127`, but **no component calls it** (zero logout buttons in `apps/pwa/src`). Add a logout control (likely in `SettingsSheet.tsx` and/or `AppNav`) that calls the existing client function + redirects to `/login`. **No backend work** — UI wiring only. (Slightly beyond pure "polish" — it's a small new control; planner should size it.)
+- **D-08 (F-01) — Add success feedback to admin local-account actions.** Admin create-member and reset-password both succeed (verified at DB/login level in UAT) but show **no success toast/confirmation**, leaving the operator unsure it worked. Add success feedback to those admin flows (`AdminPage.tsx`).
+- **D-09 (F-03) — Fix dialog/popup positioning.** Popups/sheets render **bottom-center instead of properly centered**. Fits the fixed-chrome/sheet-positioning sweep already in workstream A; likely the same dialog/sheet CSS (`SettingsSheet.tsx` and shared dialog styles). Verify across phone + desktop via playwright-cli.
+- **D-10 (F-04) — Rework the clunky admin navigation.** Admin UI navigation reads as clunky and needs a rework. Larger UX item than the others — planner should decide whether it fits this phase's "polish" budget or warrants its own slice. (`AdminPage.tsx`, admin nav/tab surface.)
+
+### Claude's Discretion
+- **D-02** (fix technique + regression guard) is explicitly delegated to the researcher/planner.
+- Exact small-viewport issues surfaced by the `layout.spec` sweep (D-01) — fix as found, within the no-behaviour-change boundary.
+- Logo visual execution within the brand brief (see Specific Ideas) — subject to user approval at the checkpoint.
+
+### Folded Todos
+- **`2026-06-13-pwa-phone-bottombar-overlap.md`** (`area: pwa-ui`, `resolves_phase: 17`) — the phase's seed defect. Phone-layout fixed BottomTabBar overlaps the New Event FAB + colour legend at ≤767px. Reproduced 2026-06-13 via playwright-cli at 390×844 (FAB over Admin tab; "Dev User" legend clipped) vs 1280×800 (no overlap). Long-standing (BottomTabBar dates to Phase 04), not a Phase 10 regression. This is workstream A's anchor — its `files:` list (`App.tsx`, `BottomTabBar.tsx`, `CalendarShell.tsx`) is the fix surface.
+
+
+
+## Canonical References
+
+**Downstream agents MUST read these before planning or implementing.**
+
+### Phase scope & seed defect
+- `.planning/ROADMAP.md` §"Phase 17: UI Optimization & Polish" — goal, three-workstream scope, scope boundary, seed-defect detail + CSS fix sketch.
+- `.planning/todos/pending/2026-06-13-pwa-phone-bottombar-overlap.md` — the folded seed-defect todo (repro, fix sketch, affected files).
+- `.planning/ROADMAP.md` §"Phase 999.20" / §"Phase 999.21" — the deferred dark-mode and styling-refresh backlog items (what is explicitly NOT in this phase).
+
+### A — Phone layout (fix surface)
+- `apps/pwa/src/App.tsx` — `window.matchMedia('(max-width: 767px)')` phone breakpoint + `contentStyle` (currently reserves no `padding-bottom` for the fixed bar).
+- `apps/pwa/src/components/BottomTabBar.tsx` — `position: fixed; height: calc(56px + env(safe-area-inset-bottom)); z-index: 200`.
+- `apps/pwa/src/components/CalendarShell.tsx` — the "New Event" FAB (`position: fixed; bottom: var(--space-6); right: var(--space-6)`).
+- `apps/pwa/e2e/layout.spec.ts` — Phase 7 quality-bar assertions (UI-SPEC Rules 1–4: ≥44px tap targets, no overflow, in-viewport, accessible names); the sweep checklist AND the home for any new overlap regression assertion.
+- `apps/pwa/playwright.config.ts` — `iphone` (iPhone 14/WebKit 390×844), `pixel` (Pixel 7/Chromium 412×915), `desktop` (Desktop Chrome 1280×720) profiles to verify across.
+
+### B — Branding
+- `apps/pwa/src/components/BrandSlot.tsx` — the Phase-17 branding seam; header documents the `--brand-logo-*` token contract and the swap-div-for-`![]()
` plan.
+- `.planning/phases/19-local-auth-no-oidc-mode/19-UI-SPEC.md` §Brand Slot — the seam's design contract (referenced by BrandSlot.tsx).
+- `apps/pwa/public/` — `apple-touch-icon.png`, `icon-192.png`, `icon-512.png` (placeholder stubs to replace).
+- `apps/pwa/index.html` — current `` + `theme-color` meta (no `` yet).
+- `apps/pwa/vite.config.ts` §`VitePWA({ manifest: { icons: [...] } })` (lines ~29–41) — PWA manifest icon list to update (incl. the improper maskable reuse).
+
+### C — Theming
+- `apps/pwa/src/styles/tokens.css` — the single light `:root` token system to restructure into a themeable layer (note the Schedule-X `--sx-color-*` overrides at the bottom and the `--brand-logo-*` defaults).
+
+
+
+## Existing Code Insights
+
+### Reusable Assets
+- **`BrandSlot` seam** (`apps/pwa/src/components/BrandSlot.tsx`): purpose-built in Phase 19 to absorb the real logo with zero `LoginPage` layout change — swap the placeholder div for an `![]()
` and set `--brand-logo-*`. The branding workstream is wiring, not new architecture.
+- **`layout.spec.ts` + 3 Playwright profiles** (Phase 7/14): a ready, CI-wired structural quality bar (tap targets / overflow / in-viewport / a11y names) — doubles as the sweep checklist (D-01) and the natural home for a regression guard (D-02).
+- **CSS custom-property token system** (`tokens.css`): everything is already a variable with "no hard-coded hex/px in components" enforced — the themeable-layer restructure (D-06) builds on an already-favourable structure rather than fighting inline values.
+- **`vite-plugin-pwa` manifest** (`vite.config.ts`): the icon set is declared in one place; replacing stubs = update files in `public/` + the manifest `icons[]` + `index.html` links.
+
+### Established Patterns
+- **Phone/desktop split at 767/768px** via `matchMedia` in `App.tsx`; phone uses top AppNav (PhoneNav ``) + fixed BottomTabBar (sole `
+
+
+## Specific Ideas
+
+**Logo / brand brief (user, 2026-06-17):**
+- **FamilySync *is* the brand** — family-oriented, the name is the identity.
+- **Caricature-family vibes** — a warm, characterful family feel (not a cold/corporate geometric mark).
+- **Warm tones.**
+- **Rounded corners / rounded shapes.**
+- Overall it should **"make you feel comfortable and at home."**
+
+This brief drives the AI-generated logo + icon set (D-03/D-04). Present generated options at a user-approval checkpoint before finalizing; the warm/rounded/at-home direction is the acceptance lens. Note the current `theme-color` is `#4A90D9` (cool blue) and `--color-shared-family` is rose `#f25c7a` — the warm-tone brief may motivate revisiting the brand/theme accent during the token-groundwork work (keep within light-theme scope).
+
+
+
+## Deferred Ideas
+
+- **Shipped dark theme + light/dark/system toggle** — captured as backlog **999.20** (PWA dark mode / theming). Phase 17 ships the enabling token groundwork only.
+- **Modern visual styling refresh** (contemporary restyle across high-visibility surfaces) — captured as backlog **999.21**, flagged for a **future milestone** (redesign risk; own track).
+
+### Reviewed Todos (not folded)
+- **`2026-06-10-gitea-ci-regression-and-docker-publish.md`** — surfaced as a weak keyword match (score 0.6) but is CI/tooling work already shipped in Phase 8/14; unrelated to this UI phase. Not folded.
+
+
+---
+
+*Phase: 17-ui-optimization-polish*
+*Context gathered: 2026-06-17*
diff --git a/.planning/phases/17-ui-optimization-polish/17-DISCUSSION-LOG.md b/.planning/phases/17-ui-optimization-polish/17-DISCUSSION-LOG.md
new file mode 100644
index 0000000..0559374
--- /dev/null
+++ b/.planning/phases/17-ui-optimization-polish/17-DISCUSSION-LOG.md
@@ -0,0 +1,102 @@
+# Phase 17: UI Optimization & Polish - Discussion Log
+
+> **Audit trail only.** Do not use as input to planning, research, or execution agents.
+> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.
+
+**Date:** 2026-06-17
+**Phase:** 17-ui-optimization-polish
+**Areas discussed:** Scope breadth, Fix technique, Regression guard, Phase shape, Branding asset ownership, Dark-mode depth, Styling-refresh boundary, Logo/brand direction
+
+---
+
+## Phase shape / sequencing
+
+Initial framing was a CSS-only layout-polish phase. Mid-discussion the user expanded scope to also include branding/logo assets (started but unfinished, incl. favicon), groundwork for themes (dark mode), and a modern styling refresh. This pushed past the ROADMAP's original "CSS/layout only, not a redesign" boundary, so scope was re-negotiated.
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| One phase, four workstreams (A layout + B branding + C dark mode + D styling) | Keep everything in Phase 17 | |
+| Split — keep layout + branding + token groundwork; defer dark theme & styling | Bound the phase, route the rest to backlog | ✓ |
+| One phase but styling "light" | A+B+C full, D incidental only | |
+
+**User's choice:** "spin dark mode and styling into /gsd-capture --backlog. We do the rest in the phase." → Phase 17 = layout polish + branding + theme-token groundwork. Shipped dark theme → backlog 999.20; styling refresh → backlog 999.21 (future milestone).
+**Notes:** ROADMAP Phase 17 goal/scope updated to match; two backlog items created and committed (916fb34).
+
+## A — Scope breadth (layout)
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Seed defect + targeted sweep | Fix overlap, then run Phase 7 layout.spec checklist across phone routes | ✓ (implied by keeping the layout workstream) |
+| Seed defect only | Fix just the bottom-bar overlap | |
+| Broad small-viewport audit | Free-form audit of every phone screen | |
+
+**User's choice:** Layout workstream retained as the bounded, checklist-driven sweep (D-01).
+**Notes:** Phase 7 `layout.spec.ts` assertions are the checklist.
+
+## A — Fix technique & regression guard
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Shared bar-height token + padding / inline calc / shrink column | CSS technique for the overlap | (researcher decides) |
+| Add overlap assertions to layout.spec / manual playwright-cli / both | Regression guard | (researcher decides) |
+
+**User's choice:** "5 - have the researcher decide."
+**Notes:** Delegated to research/planning (D-02). Default lean noted: shared `--bottom-chrome-h` token + CI assertion, but researcher decides on the merits.
+
+## B — Branding asset ownership
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| AI-generate in-phase | Claude generates logo + full icon set, wires in, user approves | ✓ |
+| User supplies final art | User provides logo, Claude derives icon set | |
+| Generate placeholders now, real art later | Stopgap improved mark via the seam | |
+
+**User's choice:** "2a" — AI-generate in-phase.
+**Notes:** No existing logo draft found beyond the "FS" placeholder + stub icons. Full icon set incl. proper maskable + favicon.ico/svg (D-03/D-04/D-05).
+
+## C — Dark-mode depth
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Groundwork only | Themeable token restructure, light stays default; dark flippable later | ✓ |
+| Ship working dark mode | Finished dark theme via prefers-color-scheme | |
+| Ship dark mode + in-app toggle | Plus persisted light/dark/system toggle | |
+
+**User's choice:** "3a" — groundwork only. Combined with "spin dark mode into backlog," the *token restructure* stays in-phase; the *shipped dark theme + toggle* go to backlog 999.20 (D-06).
+**Notes:** Light remains the sole shipped theme this phase.
+
+## D — Styling-refresh boundary
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| In-system polish | Modernize within existing design system | |
+| Component-level refresh | Rework high-visibility surfaces | |
+| Broader visual overhaul | Open-ended modern restyle | (deferred) |
+
+**User's choice:** "Dont do 4 - that goes into future milestone." → routed entirely to backlog 999.21.
+**Notes:** Redesign risk; own track in a future milestone.
+
+## Logo / brand direction
+
+**User's choice (free-text):** "FamilySync is the brand — family orientated. I like caricature family kind of vibes, warm tones, rounded corner sort of thing. Something that makes you feel comfortable and at home."
+**Notes:** Captured verbatim into CONTEXT Specific Ideas as the acceptance lens for generated logo/icon options. Current theme-color `#4A90D9` (cool blue) may be revisited toward warm tones within light-theme scope.
+
+---
+
+## Claude's Discretion
+
+- Fix technique + regression-guard mechanism for the layout overlap (delegated to researcher — D-02).
+- Specific small-viewport issues surfaced by the `layout.spec` sweep (fix as found, no behaviour change).
+- Logo visual execution within the brand brief, subject to user approval at a checkpoint.
+
+## Deferred Ideas
+
+- Shipped dark theme + light/dark/system toggle → backlog **999.20**.
+- Modern visual styling refresh → backlog **999.21** (future milestone).
+- (Reviewed, not folded) `2026-06-10-gitea-ci-regression-and-docker-publish.md` — weak keyword match, already-shipped CI work, unrelated to this UI phase.
+
+---
+
+## Process note — interactive question tool blocked
+
+The `AskUserQuestion` tool returned "Permission denied by hook" during this discussion. Investigation: no configured PreToolUse hook or permission rule matches `AskUserQuestion` (user-settings matchers are only `Write|Edit`/`Bash`/`MultiEdit`; `defaultMode: bypassPermissions`; no managed settings). The block correlates with an active background subagent (the Phase 19 `--fix --auto` fixer) running concurrently — interactive questions are suppressed while a background agent is live. Discussion proceeded via the plain-text numbered-list fallback.
diff --git a/.planning/phases/17-ui-optimization-polish/17-PATTERNS.md b/.planning/phases/17-ui-optimization-polish/17-PATTERNS.md
new file mode 100644
index 0000000..67c873c
--- /dev/null
+++ b/.planning/phases/17-ui-optimization-polish/17-PATTERNS.md
@@ -0,0 +1,836 @@
+# Phase 17: UI Optimization & Polish — Pattern Map
+
+**Mapped:** 2026-06-18
+**Files analyzed:** 13 new/modified files
+**Analogs found:** 13 / 13
+
+---
+
+## File Classification
+
+| New/Modified File | Role | Data Flow | Closest Analog | Match Quality |
+|-------------------|------|-----------|----------------|---------------|
+| `apps/pwa/src/App.tsx` | component (shell) | request-response | self (modify existing) | self |
+| `apps/pwa/src/components/CalendarShell.tsx` | component | event-driven | self (modify FAB block lines 463-491) | self |
+| `apps/pwa/src/components/BottomTabBar.tsx` | component | event-driven | self (optional token ref) | self |
+| `apps/pwa/src/styles/tokens.css` | config | transform | self (selector restructure only) | self |
+| `apps/pwa/src/components/BrandSlot.tsx` | component | transform | self (swap div→img) | self |
+| `apps/pwa/index.html` | config | transform | self (add icon links) | self |
+| `apps/pwa/vite.config.ts` | config | transform | self (update icons[]) | self |
+| `apps/pwa/src/components/SettingsSheet.tsx` | component | request-response | self (add logout row + desktop centering) | self |
+| `apps/pwa/src/routes/AdminPage.tsx` | route/component | CRUD | self (add tabs + success toasts) | self |
+| `apps/pwa/src/components/ChangePasswordSheet.tsx` (inside SettingsSheet.tsx) | component | request-response | `SettingsSheet.tsx` `ChangePasswordSheet` (lines 583-815) | exact |
+| `apps/pwa/src/components/LinkOidcSheet.tsx` (inside SettingsSheet.tsx) | component | request-response | `SettingsSheet.tsx` `LinkOidcSheet` (lines 876-1025) | exact |
+| `apps/pwa/e2e/layout.spec.ts` | test | request-response | self (add overlap assertion) | self |
+| `apps/pwa/e2e/admin.spec.ts` | test | request-response | `apps/pwa/e2e/layout.spec.ts` | role-match |
+| `apps/pwa/public/logo.svg` (+ generated icon set) | asset | transform | none (new AI-generated asset) | none |
+| `apps/pwa/pwa-assets.config.ts` | config | transform | none (new build-time config) | none |
+
+---
+
+## Pattern Assignments
+
+### `apps/pwa/src/App.tsx` — add `paddingBottom` to phone `contentStyle`
+
+**Analog:** self, lines 154–163
+
+**Current contentStyle (lines 155–163) — the gap to fill:**
+```ts
+// App.tsx lines 155–163
+const contentStyle: React.CSSProperties = {
+ flex: 1,
+ minWidth: 0,
+ minHeight: 0,
+ display: 'flex',
+ flexDirection: 'column',
+ overflow: 'hidden',
+ position: 'relative',
+ // ← paddingBottom is ABSENT — this is the defect site
+};
+```
+
+**Phone branch pattern (isPhone() defined at line 64):**
+```ts
+// App.tsx lines 64, 84 — the phone boolean already exists
+function isPhone(): boolean {
+ return typeof window !== 'undefined' && window.matchMedia('(max-width: 767px)').matches;
+}
+// ...
+const phone = isPhone(); // line 84
+```
+
+**After fix — spread operator pattern (matches existing outerStyle pattern at lines 144-152):**
+```ts
+const contentStyle: React.CSSProperties = {
+ flex: 1,
+ minWidth: 0,
+ minHeight: 0,
+ display: 'flex',
+ flexDirection: 'column',
+ overflow: 'hidden',
+ position: 'relative',
+ // Phone-only: reserve space for the fixed BottomTabBar
+ ...(phone ? { paddingBottom: 'var(--bottom-chrome-h)' } : {}),
+};
+```
+
+---
+
+### `apps/pwa/src/components/CalendarShell.tsx` — fix FAB `bottom` offset
+
+**Analog:** self, lines 463–491 (the FAB block)
+
+**Current FAB style (lines 468–487) — the defect site:**
+```ts
+// CalendarShell.tsx lines 463-491
+{phone && (
+
+)}
+```
+
+**After fix — change only the `bottom` line:**
+```ts
+bottom: 'calc(var(--bottom-chrome-h) + var(--space-6))',
+// FAB sits var(--space-6) (24px) above the BottomTabBar top edge
+```
+
+---
+
+### `apps/pwa/src/components/BottomTabBar.tsx` — optional token reference
+
+**Analog:** self, line 73
+
+**Current inline height (line 73) — unchanged but optionally can reference token:**
+```ts
+// BottomTabBar.tsx line 73
+height: 'calc(56px + env(safe-area-inset-bottom, 0px))',
+// This resolves identically to var(--bottom-chrome-h) — token reference is optional
+```
+
+**isPhone() pattern (lines 23–25) — same function, confirmed project-wide:**
+```ts
+function isPhone(): boolean {
+ return typeof window !== 'undefined' && window.matchMedia('(max-width: 767px)').matches;
+}
+```
+
+**Tab active/inactive style pattern (lines 27–50) — for admin two-tab analog:**
+```ts
+const tabBase: React.CSSProperties = {
+ flex: 1,
+ display: 'flex',
+ flexDirection: 'column',
+ alignItems: 'center',
+ justifyContent: 'center',
+ gap: '3px',
+ textDecoration: 'none',
+ fontSize: 'var(--text-label-size, 13px)',
+ fontWeight: 400,
+ lineHeight: 'var(--text-label-line-height, 1.4)',
+ fontFamily: 'var(--font-family-base)',
+ color: 'var(--color-text-muted)',
+ minHeight: '44px',
+ borderBottom: '2px solid transparent',
+ transition: 'color 0.1s ease, border-color 0.1s ease',
+};
+
+const tabActiveOverride: React.CSSProperties = {
+ color: 'var(--color-member-0)',
+ borderBottom: '2px solid var(--color-member-0)',
+};
+```
+
+---
+
+### `apps/pwa/src/styles/tokens.css` — selector restructure + add `--bottom-chrome-h`
+
+**Analog:** self (selector-only change)
+
+**Current structure:**
+```css
+:root {
+ /* all tokens */
+}
+```
+
+**After restructure — combined selector, no value changes:**
+```css
+:root,
+[data-theme="light"] {
+ /* All existing :root declarations move here verbatim */
+ /* Add new token at the top of the spacing group: */
+ --bottom-chrome-h: calc(56px + env(safe-area-inset-bottom, 0px));
+
+ /* ...all existing tokens unchanged... */
+
+ /* Schedule-X overrides stay INSIDE this same rule block (critical — see pitfall 3) */
+ --sx-color-primary: var(--color-member-0);
+ /* etc. */
+}
+
+/* Dark theme stub — values intentionally absent (Phase 17 groundwork only).
+ Phase 999.20 fills these values and wires prefers-color-scheme. */
+/* [data-theme="dark"] { ... } */
+```
+
+**Key constraint:** `--sx-color-*` overrides must remain inside the same combined rule block — do NOT split into a separate selector.
+
+---
+
+### `apps/pwa/src/components/BrandSlot.tsx` — swap placeholder div for `![]()
`
+
+**Analog:** self, lines 29–50 (the placeholder div to replace)
+
+**Current placeholder (lines 29–50):**
+```tsx
+{/* Phase 17 replaces this div with 
*/}
+
+```
+
+**After swap — keep same token surface, swap element:**
+```tsx
+
+```
+
+**`--brand-logo-bg` is no longer applied** (no background div). Update `--brand-logo-border-radius` in tokens.css from `50%` to the checkpoint-determined value (likely `12px` for warm/rounded brief or `0` if the SVG draws its own shape).
+
+---
+
+### `apps/pwa/index.html` — add favicon links
+
+**Analog:** self (additive changes only)
+
+**Current state (one apple-touch-icon link, no favicon links):**
+```html
+
+
+```
+
+**After Phase 17:**
+```html
+
+
+
+
+
+
+
+```
+
+Order matters: SVG first (modern browsers), ICO second (legacy fallback). `{CHECKPOINT_ACCENT_HEX}` = `#4A90D9` (default) or warm variant pending checkpoint.
+
+---
+
+### `apps/pwa/vite.config.ts` — fix maskable icon + add `icon-maskable-512.png`
+
+**Analog:** self, lines 38–42
+
+**Current defective icons array (lines 38–42):**
+```ts
+icons: [
+ { src: '/icon-192.png', sizes: '192x192', type: 'image/png' },
+ { src: '/icon-512.png', sizes: '512x512', type: 'image/png' },
+ { src: '/icon-512.png', sizes: '512x512', type: 'image/png', purpose: 'maskable' }, // ← DEFECT: same file
+],
+```
+
+**After fix — separate maskable file:**
+```ts
+icons: [
+ { src: '/icon-192.png', sizes: '192x192', type: 'image/png' },
+ { src: '/icon-512.png', sizes: '512x512', type: 'image/png' },
+ { src: '/icon-maskable-512.png', sizes: '512x512', type: 'image/png', purpose: 'maskable' },
+],
+```
+
+Also update `theme_color` (line 33) to match checkpoint accent: `'#4A90D9'` default.
+
+---
+
+### `apps/pwa/src/components/SettingsSheet.tsx` — add logout row + desktop centering
+
+**Analog:** self
+
+**Current sheet outer `` (lines 184–202) — the centering defect site:**
+```tsx
+// SettingsSheet.tsx lines 184-202 — currently bottom-only positioning
+
+```
+
+**After fix — phone/desktop style branch:**
+```tsx
+// isPhone() from App.tsx pattern (same function defined identically in BottomTabBar.tsx)
+const phone = window.matchMedia('(max-width: 767px)').matches;
+
+
+```
+
+**This exact phone/desktop pattern applies to ALL sheets:**
+- `SettingsSheet` outer `` (lines 184–202)
+- `ChangePasswordSheet` outer `` (lines 598–616)
+- `LinkOidcSheet` outer `` (lines 894–909)
+- `AdminPage.ResetPasswordSheet` outer `` (lines 1262–1280)
+- `CredentialSheet` (separate file — apply same branch)
+
+**Logout row pattern — add after the Account section (after line 437 close tag, before the backdrop close):**
+```tsx
+{/* Sign out — bottom of sheet, after all other sections */}
+
+
+```
+
+**handleSignOut function — try/catch with navigate in both branches (pitfall 4):**
+```ts
+// Import: import { LogOut } from 'lucide-react'; (add to existing X, Bell, AlertCircle, Loader2)
+// Import: import { fetchLocalLogout } from '../api/client.js'; (add to existing fetchMe, etc.)
+// Import: import { useNavigate } from 'react-router'; (or use window.location.replace)
+
+async function handleSignOut() {
+ try {
+ await fetchLocalLogout();
+ } catch {
+ // Fire-and-best-effort: navigate regardless of whether the API call succeeded
+ }
+ // Always navigate — server-side cookie was cleared (or already expired)
+ navigate('/login');
+}
+```
+
+**Existing section divider pattern analog (lines 372–376) — same style for logout separator:**
+```tsx
+
+```
+
+---
+
+### `apps/pwa/src/routes/AdminPage.tsx` — success toasts + two-tab navigation
+
+**Analog:** self + `SyncStateToast.tsx`
+
+**Existing `createMemberMutation.onSuccess` (lines 213–221) — hook point for toast:**
+```ts
+onSuccess: () => {
+ // Clear form + refresh member list
+ setCreateDisplayName('');
+ setCreateUsername('');
+ setCreatePassword('');
+ setCreateConfirmPassword('');
+ setCreateError(null);
+ void queryClient.invalidateQueries({ queryKey: ['admin', 'members'] });
+ void queryClient.invalidateQueries({ queryKey: ['me'] });
+ // ← ADD: setToast('Member added.')
+},
+```
+
+**Existing `resetMutation.onSuccess` (lines 1230–1232) — hook point for toast:**
+```ts
+onSuccess: () => {
+ handleClose();
+ // ← ADD: setToast('Password reset.') — must propagate up from ResetPasswordSheet
+},
+```
+
+**Toast state pattern — inline in AdminPage (no new component needed; single use):**
+```ts
+// Local state — add at top of AdminPage()
+const [toast, setToast] = useState(null);
+
+// Auto-dismiss after 3 seconds — same useEffect pattern as SyncStateToast lines 72-79
+useEffect(() => {
+ if (!toast) return;
+ const timer = setTimeout(() => setToast(null), 3000);
+ return () => clearTimeout(timer);
+}, [toast]);
+```
+
+**Toast render — copy visual structure from SyncStateToast.tsx lines 159–189:**
+```tsx
+// SyncStateToast.tsx lines 159-189 — extract the wrapper div pattern
+{toast && (
+
+
+ {toast}
+
+)}
+```
+
+Note: `CheckCircle` is already imported in AdminPage.tsx line 28. `phone` constant needs adding (use `isPhone()` or inline `window.matchMedia`).
+
+**Two-tab strip pattern — add above MEMBERS section (after `Admin Settings
`):**
+```tsx
+// Local state — add at top of AdminPage()
+const [activeTab, setActiveTab] = useState<'members' | 'settings'>('members');
+
+// Keyboard nav for roving tabindex
+function handleTabKeyDown(e: React.KeyboardEvent, current: 'members' | 'settings') {
+ if (e.key === 'ArrowRight') {
+ e.preventDefault();
+ const next = current === 'members' ? 'settings' : 'members';
+ setActiveTab(next);
+ (e.currentTarget.parentElement?.querySelector(`[id="admin-tab-${next}"]`) as HTMLElement)?.focus();
+ } else if (e.key === 'ArrowLeft') {
+ e.preventDefault();
+ const prev = current === 'settings' ? 'members' : 'settings';
+ setActiveTab(prev);
+ (e.currentTarget.parentElement?.querySelector(`[id="admin-tab-${prev}"]`) as HTMLElement)?.focus();
+ }
+}
+
+// Tab strip render
+
+ {(['members', 'settings'] as const).map((id) => (
+
+ ))}
+
+
+{/* Tab panels */}
+
+ {/* MEMBERS section + LOCAL ACCOUNTS section */}
+
+
+ {/* SHARED CALENDAR section + TIMEZONE section */}
+
+```
+
+**Existing `sectionLabelStyle` (lines 44–51) — reuse unchanged inside tab panels:**
+```ts
+const sectionLabelStyle: React.CSSProperties = {
+ fontSize: 'var(--text-label-size, 13px)',
+ fontWeight: 600,
+ color: 'var(--color-text-muted)',
+ textTransform: 'uppercase',
+ letterSpacing: '0.06em',
+ marginBottom: 'var(--space-2, 8px)',
+};
+```
+
+---
+
+### `apps/pwa/e2e/layout.spec.ts` — add FAB/BottomTabBar overlap assertion
+
+**Analog:** self, lines 30–60 (existing test structure pattern)
+
+**Existing test structure to follow (lines 31-60):**
+```ts
+test.describe('Rule 1/3/4 — BottomTabBar tap targets and in-viewport position', () => {
+ test.beforeEach(async ({ page }) => {
+ await page.goto('/calendar');
+ });
+
+ test('Calendar tab meets 44×44px touch-target minimum (Rule 1)', async ({ page }) => {
+ const nav = page.getByRole('navigation', { name: 'Main navigation' });
+ const calTab = nav.getByRole('link', { name: 'Calendar' });
+ const box = await calTab.boundingBox();
+ expect(box, 'Calendar tab bounding box must not be null').not.toBeNull();
+ expect(box!.width, 'Calendar tab width ≥ 44px').toBeGreaterThanOrEqual(44);
+ expect(box!.height, 'Calendar tab height ≥ 44px').toBeGreaterThanOrEqual(44);
+ });
+```
+
+**New overlap assertion to add:**
+```ts
+test('New Event FAB does not overlap BottomTabBar (A — phone only)', async ({ page }, testInfo) => {
+ test.skip(testInfo.project.name === 'desktop', 'Phone-only assertion');
+ await page.goto('/calendar');
+ const fab = page.getByRole('button', { name: 'New Event' });
+ const nav = page.getByRole('navigation', { name: 'Main navigation' });
+ const fabBox = await fab.boundingBox();
+ const navBox = await nav.boundingBox();
+ expect(fabBox, 'FAB bounding box must not be null').not.toBeNull();
+ expect(navBox, 'BottomTabBar bounding box must not be null').not.toBeNull();
+ // FAB bottom edge must be at or above the BottomTabBar top edge
+ expect(fabBox!.y + fabBox!.height).toBeLessThanOrEqual(navBox!.y);
+});
+```
+
+---
+
+### `apps/pwa/e2e/admin.spec.ts` (new file)
+
+**Analog:** `apps/pwa/e2e/layout.spec.ts` — copy file header pattern, test.describe structure, page.goto pattern
+
+**File header + structure pattern (layout.spec.ts lines 1–27):**
+```ts
+/**
+ * admin.spec.ts — TEST-XX
+ *
+ * Admin page UI assertions: two-tab ARIA pattern, success toasts, sheet centering.
+ * ...
+ *
+ * Runs on all three device profiles unless skipped via testInfo.project.name.
+ */
+import { test, expect } from '@playwright/test';
+
+test.describe('Admin tab strip — ARIA tabs pattern (D-10)', () => {
+ test.beforeEach(async ({ page }) => {
+ // Note: requires an admin session — playwright.config.ts storageState for admin
+ await page.goto('/admin');
+ });
+
+ test('Tab strip has correct ARIA roles', async ({ page }) => {
+ await expect(page.getByRole('tablist')).toBeVisible();
+ await expect(page.getByRole('tab', { name: 'Members & Accounts' })).toBeVisible();
+ await expect(page.getByRole('tab', { name: 'Settings' })).toBeVisible();
+ });
+
+ test('ArrowRight switches to Settings tab', async ({ page }) => {
+ const membersTab = page.getByRole('tab', { name: 'Members & Accounts' });
+ await membersTab.focus();
+ await page.keyboard.press('ArrowRight');
+ await expect(page.getByRole('tab', { name: 'Settings' })).toHaveAttribute('aria-selected', 'true');
+ });
+});
+```
+
+---
+
+## Shared Patterns
+
+### Phone/Desktop Breakpoint
+**Source:** `apps/pwa/src/components/BottomTabBar.tsx` lines 23–25; `apps/pwa/src/App.tsx` line 64
+**Apply to:** All sheet centering fixes (SettingsSheet, ChangePasswordSheet, LinkOidcSheet, ResetPasswordSheet, CredentialSheet), admin toast positioning, admin tab strip phone layout check
+
+```ts
+// Identical function defined in BottomTabBar.tsx, App.tsx, CalendarShell.tsx
+function isPhone(): boolean {
+ return typeof window !== 'undefined' && window.matchMedia('(max-width: 767px)').matches;
+}
+// Or inline: window.matchMedia('(max-width: 767px)').matches
+```
+
+### Sheet/Dialog Pattern
+**Source:** `apps/pwa/src/components/SettingsSheet.tsx` lines 170–202 (backdrop + dialog wrapper)
+**Apply to:** All sheets that need desktop-centering fix
+
+```tsx
+{/* Backdrop — unchanged across all sheets */}
+
+{/* Sheet outer wrapper — gains phone/desktop branch */}
+
+```
+
+### Section Divider Pattern
+**Source:** `apps/pwa/src/components/SettingsSheet.tsx` lines 372–376
+**Apply to:** Logout row separator in SettingsSheet
+
+```tsx
+
+```
+
+### Mutation + Toast Pattern
+**Source:** `apps/pwa/src/routes/AdminPage.tsx` lines 197–235 (`createMemberMutation`), `apps/pwa/src/components/SyncStateToast.tsx` lines 72–79 (auto-dismiss), lines 159–189 (toast render)
+**Apply to:** AdminPage create-member and reset-password success feedback
+
+Auto-dismiss pattern from SyncStateToast (lines 72–79):
+```ts
+useEffect(() => {
+ if (status !== 'done') return; // adapt: if (!toast) return;
+ const timer = setTimeout(() => {
+ setLastSyncedUid(null); // adapt: setToast(null)
+ }, 2000); // use 3000ms for admin toasts per UI-SPEC
+ return () => clearTimeout(timer);
+}, [status, setLastSyncedUid]);
+```
+
+### Accessible Button Row Pattern
+**Source:** `apps/pwa/src/components/SettingsSheet.tsx` lines 390–410 (Change password button row)
+**Apply to:** Logout button in SettingsSheet
+
+```tsx
+
+```
+
+---
+
+## No Analog Found
+
+| File | Role | Data Flow | Reason |
+|------|------|-----------|--------|
+| `apps/pwa/public/logo.svg` | asset | transform | New AI-generated SVG logo — no existing brand mark in codebase |
+| `apps/pwa/public/favicon.svg`, `favicon.ico`, `icon-maskable-512.png` | asset | transform | New generated assets — none exist in `public/` yet |
+| `apps/pwa/pwa-assets.config.ts` | config | transform | New `@vite-pwa/assets-generator` config — no prior asset-generation config in repo |
+
+---
+
+## Critical Pitfalls (for Planner)
+
+1. **Maskable icon must be a separate file.** `icon-maskable-512.png` is a distinct generated asset with safe-zone padding — the defect is reusing `icon-512.png` for the maskable purpose. Fix by generating `icon-maskable-512.png` via `@vite-pwa/assets-generator`.
+
+2. **`paddingBottom` in `contentStyle` is phone-only.** The `...(phone ? {...} : {})` spread pattern (from outerStyle at App.tsx lines 144–152) ensures desktop gets no extra bottom padding.
+
+3. **`--sx-color-*` overrides must stay inside the combined `tokens.css` rule block.** Do not split them to a separate selector — they must override the `@schedule-x/theme-default` values by staying in the same specificity context.
+
+4. **`fetchLocalLogout` error must not prevent navigation.** Wrap in try/catch and call `navigate('/login')` in both branches — fire-and-best-effort semantics per UI-SPEC §D-07.
+
+5. **`--brand-logo-border-radius` update required after logo approval.** The current `50%` value (circle) clips an SVG logo that draws its own shape. Update to `12px` (warm/rounded) or `0` (if SVG has own border-radius) at the checkpoint — before wiring.
+
+6. **Admin tab state is not URL-persisted.** Tab state is `useState` only — navigating away and back resets to Tab 1 ("Members & Accounts"). This is intentional per UI-SPEC §D-10.
+
+---
+
+## Metadata
+
+**Analog search scope:** `apps/pwa/src/components/`, `apps/pwa/src/routes/`, `apps/pwa/src/api/`, `apps/pwa/e2e/`, `apps/pwa/`
+**Files read:** 10 source files
+**Pattern extraction date:** 2026-06-18
diff --git a/.planning/phases/17-ui-optimization-polish/17-RESEARCH.md b/.planning/phases/17-ui-optimization-polish/17-RESEARCH.md
new file mode 100644
index 0000000..a51b25a
--- /dev/null
+++ b/.planning/phases/17-ui-optimization-polish/17-RESEARCH.md
@@ -0,0 +1,515 @@
+# Phase 17: UI Optimization & Polish — Research
+
+**Researched:** 2026-06-18
+**Domain:** React PWA polish, branding asset toolchain, CSS token architecture
+**Confidence:** HIGH (fix surfaces grounded against actual codebase; toolchain decision based on registry verification and official documentation)
+
+---
+
+
+## User Constraints (from CONTEXT.md)
+
+### Locked Decisions
+- **D-01:** Fix BottomTabBar/FAB/colour-legend overlap AND run bounded small-viewport sweep using layout.spec.ts assertions as the checklist. Fix what they flag; no free-form audit.
+- **D-03:** Logo + full icon set are AI-generated in-phase by Claude. User approves before assets are finalised. No external designer / user-supplied art.
+- **D-04:** Deliver the complete icon set: `favicon.ico` + `favicon.svg`, `icon-192.png`, `icon-512.png`, a proper maskable `icon-maskable-512.png` (safe-zone padded), `apple-touch-icon.png` (180×180). Update `index.html` and `vite.config.ts` manifest.
+- **D-05:** Drive logo through the existing BrandSlot seam: swap placeholder `` for `![]()
`, override `--brand-logo-*` tokens. No LoginPage layout changes. Accessibility shape unchanged (`` carries name, logo is decorative `alt="" aria-hidden`).
+- **D-06:** Restructure `tokens.css` into a themeable layer (`:root, [data-theme="light"]` combined selector). Groundwork only — no dark palette values, no `prefers-color-scheme` wiring, no toggle. Schedule-X `--sx-color-*` overrides must remain working.
+- **D-07 (F-02):** Wire logout control in SettingsSheet (and/or AppNav) calling existing `fetchLocalLogout()` (client.ts:124) then navigate to `/login`. No backend work.
+- **D-08 (F-01):** Add success toast/confirmation to AdminPage create-member and reset-password flows. No backend work.
+- **D-09 (F-03):** Fix dialog/sheet centering — bottom-sheet on phone (unchanged), centered modal on desktop. Applies to SettingsSheet, ChangePasswordSheet, LinkOidcSheet, CredentialSheet, admin reset-password sheet.
+- **D-10 (F-04):** Rework admin navigation as a two-tab strip ("Members & Accounts" / "Settings") with full ARIA tabs pattern (roving tabindex, ArrowLeft/Right keyboard).
+- **D-02:** Fix technique and regression-guard mechanism are researcher/planner's call. (Resolved by UI-SPEC: shared `--bottom-chrome-h` token + permanent overlap assertion in `layout.spec.ts`.)
+
+### Claude's Discretion
+- D-02: fix technique + regression guard (resolved by UI-SPEC to: shared token + CI assertion).
+- Exact small-viewport issues surfaced by layout.spec sweep — fix as found, within no-behaviour-change boundary.
+- Logo visual execution within the brand brief — subject to user approval at checkpoint.
+
+### Deferred Ideas (OUT OF SCOPE)
+- **Shipped dark theme + light/dark/system toggle** → backlog 999.20. Phase 17 ships enabling groundwork only.
+- **Modern visual styling refresh** (login/calendar/event-form/lists/admin restyle) → backlog 999.21.
+
+
+---
+
+## Summary
+
+Phase 17 is a well-specified, bounded polish and branding pass across four workstreams on an existing shipped React 19 + Vite PWA. The UI-SPEC (17-UI-SPEC.md, approved 2026-06-18) resolves all design decisions. This research focuses on the one genuine implementation gap — the branding asset-generation toolchain — plus validation architecture and a grounded code-surface audit.
+
+**Workstream A (phone layout):** The defect is confirmed in source: `CalendarShell.tsx` FAB uses `bottom: 'var(--space-6)'` (24px), which places it behind the 56px BottomTabBar. The fix is a shared CSS custom property `--bottom-chrome-h` consumed by both the FAB offset and `App.tsx contentStyle`. This is a CSS-only change touching three files.
+
+**Workstream B (branding assets):** Sharp is not installed in this monorepo. The recommended toolchain is `@vite-pwa/assets-generator` (CLI mode, `minimal-2023` preset) which depends on `sharp` and `sharp-ico` internally, generates all seven required assets from a single source SVG, and is purpose-built for the vite-plugin-pwa ecosystem. The source logo is hand-authored SVG (warm/rounded/caricature-family brief) — this is the most reproducible, version-controlled, deterministic path.
+
+**Workstream C (token groundwork):** The `tokens.css` restructure is a single-selector change: `:root` becomes `:root, [data-theme="light"]`. The Schedule-X overrides remain inside the same rule block; no cascade order changes.
+
+**Workstream D (UAT fixes):** All four fixes are confirmed wirable against existing symbols — `fetchLocalLogout()` exists at `client.ts:124`, `SyncStateToast.tsx` provides the visual toast pattern, `AdminPage.tsx` has `useMutation` infrastructure already, and dialog centering is a `window.matchMedia` branch on the outer `` style.
+
+**Primary recommendation:** Use `@vite-pwa/assets-generator` CLI (v1.0.2) with the `minimal-2023` preset + `overrideManifestIcons: false` (manual manifest update for explicit control). Source logo: hand-authored SVG committed to `apps/pwa/public/logo.svg`.
+
+---
+
+## Architectural Responsibility Map
+
+| Capability | Primary Tier | Secondary Tier | Rationale |
+|------------|-------------|----------------|-----------|
+| FAB/BottomTabBar overlap fix | Browser / Client (CSS) | — | Pure layout geometry; CSS custom property token on the client; no server involvement |
+| Icon/favicon asset generation | Build tooling (Node.js CLI) | Static/CDN | Run once at design time; assets committed to `public/`; served as static files |
+| Token restructure (tokens.css) | Browser / Client (CSS) | — | CSS-only structural change; no server data |
+| BrandSlot logo swap | Browser / Client (React) | — | Component-internal change; logo served from `public/logo.svg` static file |
+| Logout control | Frontend + API | — | UI calls existing `POST /api/auth/local/logout` (already implemented); no new backend |
+| Admin success toast | Browser / Client (React) | — | Client-side state (`useState` + `setTimeout`); mutation already exists |
+| Dialog centering | Browser / Client (CSS/React) | — | Breakpoint-conditional inline style on existing dialog wrappers |
+| Admin two-tab nav | Browser / Client (React) | — | Local `useState` in AdminPage; ARIA tabs pattern; no routing change |
+
+---
+
+## Standard Stack
+
+### Core (already installed — no new runtime dependencies required)
+
+| Library | Version | Purpose | Status |
+|---------|---------|---------|--------|
+| React 19 | ^19.0.0 | PWA component framework | Installed |
+| lucide-react | 1.17.0 | Icon library (`LogOut`, `CheckCircle` for D-07/D-08) | Installed; `LogOut` not yet imported anywhere |
+| @tanstack/react-query | 5.101.0 | Mutation infrastructure for admin toasts | Installed |
+| vite-plugin-pwa | ^1.3.0 | Manifest icons wiring | Installed |
+
+### Build-time toolchain (new devDependency, `apps/pwa` scope)
+
+| Package | Version | Purpose | Verdict |
+|---------|---------|---------|---------|
+| `@vite-pwa/assets-generator` | 1.0.2 | CLI: generates all PWA icon assets from SVG source | OK [VERIFIED: npm registry] |
+| `sharp` | 0.35.1 (latest) | Raster processing engine (pulled as dependency of assets-generator) | SUS (see audit) — well-known package, seam flagged as too-new due to version date |
+| `sharp-ico` | 0.1.5 | ICO encoder used internally by assets-generator | OK [VERIFIED: npm registry] |
+
+**Note on `sharp` SUS verdict:** The seam flagged it `too-new` because the latest publish date (2026-06-11) is within 30 days. This is a 12-year-old package (created 2013-08-20) with 65.6M weekly downloads at `github.com/lovell/sharp` — it is the canonical Node.js image processing library. The `too-new` signal reflects the latest version's publish date, not the package age. The planner should note this but may treat it as approved. [ASSUMED: confidence assessment of seam verdict vs. package age]
+
+**No new runtime dependencies.** Zero npm packages are added to `dependencies` — only devDependencies for the asset generation script.
+
+### Alternatives Considered
+
+| Instead of | Could Use | Why not |
+|------------|-----------|---------|
+| `@vite-pwa/assets-generator` | `pwa-asset-generator` (v8.1.5) | pwa-asset-generator uses Puppeteer/Chromium to generate assets (heavier); last meaningful update 2026-06-01; not the official vite-pwa project's tool |
+| `@vite-pwa/assets-generator` | `sharp` directly + custom script | More code to maintain; assets-generator is purpose-built for this stack and already handles maskable safe-zone, ICO via sharp-ico |
+| `@vite-pwa/assets-generator` | ImageMagick `convert` | ImageMagick is not installed on this machine (confirmed via `which convert`) |
+| Hand-authored SVG source | Raster PNG source + trace | SVG is version-controllable, infinitely scalable, editable as text; no round-trip through a raster format |
+
+---
+
+## Package Legitimacy Audit
+
+| Package | Registry | Age | Downloads | Source Repo | Verdict | Disposition |
+|---------|----------|-----|-----------|-------------|---------|-------------|
+| `@vite-pwa/assets-generator` | npm | ~7 mo (2025-10-14) | 231K/wk | github.com/vite-pwa/assets-generator | OK | Approved |
+| `sharp` | npm | 13 yrs (2013-08-20) | 65.6M/wk | github.com/lovell/sharp | SUS (too-new flag on latest version) | Approved — package age and download volume override seam's version-recency signal; see note above |
+| `sharp-ico` | npm | ~4 yrs (2022-08-30) | 431K/wk | github.com/ssnangua/sharp-ico | OK | Approved |
+
+**Packages removed due to SLOP verdict:** none
+**Packages flagged as suspicious SUS:** `sharp` — seam flagged due to latest version publish date (2026-06-11 within 30-day window). This is a false positive given 13-year age and 65M weekly downloads. Planner does NOT need to add `checkpoint:human-verify` for this package; document the assessment and proceed.
+
+---
+
+## Architecture Patterns
+
+### Recommended Asset-Generation Script Shape
+
+```
+apps/pwa/
+├── pwa-assets.config.ts # @vite-pwa/assets-generator config
+└── public/
+ ├── logo.svg # Source — hand-authored SVG (warm/rounded; committed)
+ ├── favicon.svg # Generated (copy of source SVG)
+ ├── favicon.ico # Generated (48×48 ICO via sharp-ico)
+ ├── icon-192.png # Generated (192×192 transparent PNG)
+ ├── icon-512.png # Generated (512×512 transparent PNG)
+ ├── icon-maskable-512.png # Generated (512×512 maskable, safe-zone padded)
+ └── apple-touch-icon.png # Generated (180×180 PNG)
+```
+
+**Minimal pwa-assets.config.ts:**
+
+```ts
+// Source: @vite-pwa/assets-generator official docs / vite-pwa-org.netlify.app
+import { defineConfig, minimal2023Preset } from '@vite-pwa/assets-generator/config'
+
+export default defineConfig({
+ preset: {
+ ...minimal2023Preset,
+ // The minimal-2023 preset generates:
+ // - favicon.ico (48x48 via sharp-ico)
+ // - favicon.svg (copy of source)
+ // - icon-64.png (64×64 transparent)
+ // - icon-192.png (192×192 transparent)
+ // - icon-512.png (512×512 transparent, purpose: 'any')
+ // - icon-maskable-512.png (512×512 maskable, white bg, safe-zone padded, purpose: 'maskable')
+ // - apple-touch-icon.png (180×180)
+ },
+ images: ['public/logo.svg'],
+})
+```
+
+**Generate command:**
+
+```bash
+# Run from apps/pwa/
+npx --yes @vite-pwa/assets-generator generate
+```
+
+Or add to `package.json` scripts:
+
+```json
+"pwa:icons": "pwa-assets-generator generate"
+```
+
+**Maskable safe-zone math (confirmed by minimal-2023 preset):** The preset produces a 512×512 maskable PNG with the logo scaled to fit within the 80% safe zone (410px effective canvas) centered on the canvas, with a solid background fill. The outer 10% on each edge may be cropped by adaptive-icon masks. The source `logo.svg` viewBox should be square; the tool handles all padding arithmetic. [CITED: vite-pwa-org.netlify.app/assets-generator/]
+
+**ICO generation:** `sharp-ico` (a dependency of `@vite-pwa/assets-generator`) produces the `.ico` file. The `minimal-2023` preset emits a 48×48 single-size ICO. The UI-SPEC calls for 16+32 multi-size — this is a minor gap. Resolution: the favicon.ico produced at 48px is adequate for modern use; multi-size ICO adds complexity with negligible real-world benefit for a household app. The `favicon.svg` (higher priority) covers modern browsers. [ASSUMED: 48px single-size ICO is sufficient vs. 16+32 multi-size for this use case]
+
+**vite.config.ts manifest update (after generation):**
+
+```ts
+icons: [
+ { src: '/icon-192.png', sizes: '192x192', type: 'image/png' },
+ { src: '/icon-512.png', sizes: '512x512', type: 'image/png' },
+ { src: '/icon-maskable-512.png', sizes: '512x512', type: 'image/png', purpose: 'maskable' },
+],
+```
+
+**index.html wiring (after generation):**
+
+```html
+
+
+
+
+```
+
+### Pattern 1: Shared Bottom-Chrome Token (Workstream A)
+
+**What:** Single CSS custom property `--bottom-chrome-h` defines the BottomTabBar's effective height including the safe-area-inset. Three sites consume it — the bar's own height, the FAB bottom offset, and the content area padding-bottom.
+
+**Fix contract:**
+
+```css
+/* tokens.css — add to :root */
+--bottom-chrome-h: calc(56px + env(safe-area-inset-bottom, 0px));
+```
+
+```ts
+// CalendarShell.tsx — FAB bottom offset (phone branch only)
+bottom: 'calc(var(--bottom-chrome-h) + var(--space-6))',
+```
+
+```ts
+// App.tsx — contentStyle (phone branch only)
+...(phone ? { paddingBottom: 'var(--bottom-chrome-h)' } : {}),
+```
+
+The BottomTabBar.tsx `height` already uses the same arithmetic inline (`calc(56px + env(safe-area-inset-bottom, 0px))`); it may optionally reference the token for consistency, but neither path changes the visual geometry.
+
+### Pattern 2: Overlap Regression Assertion (Workstream A)
+
+**Add to `layout.spec.ts`:**
+
+```ts
+// Source: UI-SPEC §Regression Guard (D-02)
+test('New Event FAB does not overlap BottomTabBar (A — phone only)', async ({ page }, testInfo) => {
+ test.skip(testInfo.project.name === 'desktop', 'Phone-only assertion');
+ await page.goto('/calendar');
+ const fab = page.getByRole('button', { name: 'New Event' });
+ const nav = page.getByRole('navigation', { name: 'Main navigation' });
+ const fabBox = await fab.boundingBox();
+ const navBox = await nav.boundingBox();
+ expect(fabBox).not.toBeNull();
+ expect(navBox).not.toBeNull();
+ expect(fabBox!.y + fabBox!.height).toBeLessThanOrEqual(navBox!.y);
+});
+```
+
+### Pattern 3: Admin Tabs ARIA Pattern (Workstream D-10)
+
+```tsx
+// AdminPage.tsx — roving tabindex ARIA tabs
+
+ {(['members', 'settings'] as const).map((id) => (
+
+ ))}
+
+
+ {/* active panel content */}
+
+```
+
+`handleTabKeyDown` moves focus + activates on ArrowLeft/ArrowRight using `document.querySelector('[role="tab"]')` siblings or a ref array.
+
+### Anti-Patterns to Avoid
+
+- **Do not add `data-theme="light"` attribute to ``** in Phase 17. The groundwork is CSS-only; the attribute is added by Phase 999.20 when the toggle is shipped. The combined `:root, [data-theme="light"]` selector means light tokens apply regardless — no attribute needed for light-only.
+- **Do not use `pwa-asset-generator` (the older v8 package)** — it uses Puppeteer/Chromium and is not the official vite-pwa project tool.
+- **Do not run `@vite-pwa/assets-generator` with `overrideManifestIcons: true`** in this project — the manifest is manually maintained in `vite.config.ts`; auto-overwrite would stomp the explicit entries.
+- **Do not modify `LoginPage.tsx`** when swapping BrandSlot internals — the seam contract from Phase 19 explicitly forbids layout changes to LoginPage.
+- **Do not use `dangerouslySetInnerHTML`** in any new components (T-05-24 invariant, enforced project-wide).
+
+---
+
+## Don't Hand-Roll
+
+| Problem | Don't Build | Use Instead | Why |
+|---------|-------------|-------------|-----|
+| Maskable icon safe-zone padding | Custom canvas/sharp script | `@vite-pwa/assets-generator` minimal-2023 preset | Safe-zone math, ICO encoding, maskable background fill already implemented and tested |
+| ICO encoding | Custom bit-packing | `sharp-ico` (dependency of assets-generator) | ICO is a non-trivial multi-image container format; sharp-ico handles it correctly |
+| Toast state management | Custom event bus | Local `useState` + `setTimeout` in AdminPage | Single-component use; TanStack Query `onSuccess` callback feeds the state directly |
+| ARIA tabs keyboard nav | Custom focus-trap | Roving tabindex pattern (standard ARIA spec) | Two tabs; ArrowLeft/ArrowRight with `tabIndex={-1}` on inactive tabs is 10 lines of code |
+
+---
+
+## Code Surface Audit (Fix Surfaces Verified Against Source)
+
+All files and symbols confirmed to exist as described in CONTEXT.md and UI-SPEC. No drift found.
+
+### Workstream A
+
+| File | Finding | Status |
+|------|---------|--------|
+| `apps/pwa/src/App.tsx` | `contentStyle` (lines 155–163): no `paddingBottom`; phone split done via `isPhone()` function defined at line 64 | CONFIRMED — `paddingBottom` absent, fix is additive |
+| `apps/pwa/src/components/BottomTabBar.tsx` | `height: 'calc(56px + env(safe-area-inset-bottom, 0px))'` at line 72; `position: fixed; bottom: 0; z-index: 200` | CONFIRMED — matches UI-SPEC description exactly |
+| `apps/pwa/src/components/CalendarShell.tsx` | FAB at lines 463–484: `position: 'fixed', bottom: 'var(--space-6)', right: 'var(--space-6)'` — the defect | CONFIRMED — FAB bottom is `var(--space-6)` (24px), not clearing the 56px bar |
+| `apps/pwa/e2e/layout.spec.ts` | Existing assertions cover tap targets, overflow, in-viewport; no overlap assertion yet | CONFIRMED — overlap assertion is missing; file is the correct home for it |
+| `apps/pwa/playwright.config.ts` | Three profiles: iphone (390×844 WebKit), pixel (412×915 Chromium), desktop (1280×720 Chrome) | CONFIRMED |
+
+### Workstream B
+
+| File | Finding | Status |
+|------|---------|--------|
+| `apps/pwa/public/` | Three stubs: `apple-touch-icon.png` (617 B), `icon-192.png` (699 B), `icon-512.png` (4086 B). No `favicon.ico`, no `favicon.svg`, no `icon-maskable-512.png` | CONFIRMED — stubs only; all need replacement |
+| `apps/pwa/index.html` | One ``, one ``, no `` | CONFIRMED — favicon links entirely absent |
+| `apps/pwa/vite.config.ts` | `icons` array (lines 38–42): 3 entries; last entry incorrectly reuses `icon-512.png` for maskable purpose | CONFIRMED — `{ src: '/icon-512.png', sizes: '512x512', type: 'image/png', purpose: 'maskable' }` is the defect |
+| `apps/pwa/src/components/BrandSlot.tsx` | Placeholder `` with `--brand-logo-*` token consumption; `FamilySync
` and tagline `` present | CONFIRMED — swap internals only; seam is correct |
+| `sharp` in monorepo | Not installed anywhere in monorepo — not in `apps/pwa/package.json`, `apps/api/package.json`, or root; `node_modules/sharp` absent | CONFIRMED — must install `@vite-pwa/assets-generator` as devDependency |
+
+### Workstream C
+
+| File | Finding | Status |
+|------|---------|--------|
+| `apps/pwa/src/styles/tokens.css` | Single `:root { ... }` block with all tokens including `--brand-logo-*` tokens and Schedule-X `--sx-color-*` overrides at bottom | CONFIRMED — restructure is selector-only; token values unchanged |
+
+### Workstream D
+
+| Symbol | File | Line | Status |
+|--------|------|------|--------|
+| `fetchLocalLogout()` | `apps/pwa/src/api/client.ts` | 124–134 | CONFIRMED — `POST /api/auth/local/logout`, `credentials: 'include'`, `redirect: 'manual'`; handles opaqueredirect |
+| `SyncStateToast` visual pattern | `apps/pwa/src/components/SyncStateToast.tsx` | 1–60 | CONFIRMED — toast renders with `role="status"` or `role="alert"`, bottom-center position; reuse the visual style |
+| `AdminPage.tsx` | `apps/pwa/src/routes/AdminPage.tsx` | 1–80 | CONFIRMED — `useMutation` imports from TanStack Query present; `sectionLabelStyle` defined; currently single-scroll layout |
+| `SettingsSheet.tsx` sheet structure | `apps/pwa/src/components/SettingsSheet.tsx` | 1–60 | CONFIRMED — `role="dialog"` pattern exists; `LogOut` lucide icon NOT yet imported (needs adding) |
+
+---
+
+## Common Pitfalls
+
+### Pitfall 1: Maskable Icon Without Safe Zone
+**What goes wrong:** Reusing the non-maskable 512 PNG as the maskable icon (the current defect in `vite.config.ts`) — the logo gets cropped at the edges on Android adaptive icons.
+**Why it happens:** The manifest `purpose: 'maskable'` flag is easy to add without understanding that maskable requires the logo to be inset within the 80% safe zone.
+**How to avoid:** Generate a separate `icon-maskable-512.png` using `@vite-pwa/assets-generator` which pads the logo to the safe zone automatically with a solid background fill.
+**Warning signs:** `maskable` and `any` entries pointing to the same file in the manifest.
+
+### Pitfall 2: FAB Position Regression on Desktop
+**What goes wrong:** Applying `paddingBottom: 'var(--bottom-chrome-h)'` to `contentStyle` unconditionally — on desktop, this adds 56px+ of empty space below content where there is no BottomTabBar.
+**Why it happens:** `contentStyle` in `App.tsx` is shared across phone and desktop layouts.
+**How to avoid:** Apply the padding-bottom only in the phone branch — `...(phone ? { paddingBottom: 'var(--bottom-chrome-h)' } : {})`. The existing `phone` boolean (computed from `isPhone()` at line 84 of `App.tsx`) is the correct gate.
+**Warning signs:** layout.spec.ts desktop profile shows content area with unexpected bottom padding.
+
+### Pitfall 3: Schedule-X Token Override Cascade Break
+**What goes wrong:** Moving the `--sx-color-*` overrides OUTSIDE the `:root, [data-theme="light"]` block during the tokens.css restructure — they no longer override the `@schedule-x/theme-default` values.
+**Why it happens:** The tokens.css comment says "must come after the theme-default import" (import order in main.tsx), but that refers to the stylesheet import order. If the overrides move to a new rule block that comes before `:root` in cascade order (e.g., a bare `[data-theme="light"]` block without `:root`), specificity changes could affect the Schedule-X defaults.
+**How to avoid:** Keep ALL tokens — including `--sx-color-*` — inside the combined `:root, [data-theme="light"]` block. Do not split them across multiple rule blocks.
+**Warning signs:** Schedule-X calendar grid loses custom colors (event chips revert to the Schedule-X default blue/green).
+
+### Pitfall 4: `fetchLocalLogout` Error Swallowed on Navigate
+**What goes wrong:** If `fetchLocalLogout()` rejects (e.g., server error, network timeout), a naive `await fetchLocalLogout(); navigate('/login')` would navigate away without clearing the cookie. The user would believe they logged out but the session cookie may still be valid.
+**Why it happens:** Async error propagation on a fire-and-forget logout.
+**How to avoid:** Wrap in `try/catch` and call `navigate('/login')` in both the `try` (success) and `catch` (failure) branches — the UI-SPEC documents this as "fire-and-best-effort for a cookie clear." The server already handles the 401 case by expiring the cookie; the navigate is always safe.
+**Warning signs:** `fetchLocalLogout` throws and the SettingsSheet stays open.
+
+### Pitfall 5: `--brand-logo-border-radius` Not Updated
+**What goes wrong:** After swapping the BrandSlot `
` for an `![]()
`, the `--brand-logo-border-radius: 50%` token (currently in tokens.css) clips the `![]()
` into a circle regardless of the logo's own shape.
+**Why it happens:** The token was set for the initials-circle placeholder; it is inherited by the `![]()
` element via the BrandSlot swap contract.
+**How to avoid:** After the logo art is approved at the checkpoint, update `--brand-logo-border-radius` in tokens.css to match the logo shape (likely `12px` for a warm/rounded brief, or `0` if the SVG draws its own shape).
+**Warning signs:** The real logo looks cropped or forced into a circle shape in the login view.
+
+---
+
+## Runtime State Inventory
+
+SKIPPED — this is a greenfield polish phase, not a rename/refactor/migration. No stored data, live service config, OS-registered state, secrets, or build artifacts carry strings being changed.
+
+---
+
+## Environment Availability
+
+| Dependency | Required By | Available | Version | Fallback |
+|------------|------------|-----------|---------|----------|
+| Node.js | Asset generation script | ✓ | 22 LTS | — |
+| pnpm | Monorepo package management | ✓ | (installed) | — |
+| `@vite-pwa/assets-generator` | Workstream B icon generation | ✗ (not installed) | 1.0.2 (latest) | Install as devDependency in `apps/pwa` |
+| `sharp` | Transitive dep of assets-generator | ✗ (not installed) | 0.35.1 (latest) | Installed automatically with assets-generator |
+| ImageMagick `convert` | Alternative ICO generation | ✗ | — | Not needed — using assets-generator instead |
+| Playwright | Workstream A regression assertions | ✓ | 1.60.0 | — |
+| Vitest | Unit tests | ✓ | ^4.1.8 | — |
+
+**Missing dependencies with no fallback:** none
+**Missing dependencies with fallback:** `@vite-pwa/assets-generator` — install as devDependency in `apps/pwa`.
+
+---
+
+## Validation Architecture
+
+### Test Framework
+
+| Property | Value |
+|----------|-------|
+| E2E Framework | Playwright 1.60.0 |
+| Unit Framework | Vitest ^4.1.8 |
+| E2E Config | `apps/pwa/playwright.config.ts` |
+| Unit Config | `apps/pwa/vitest.config.ts` |
+| E2E quick run | `pnpm --filter @familysync/pwa exec playwright test --project=pixel layout.spec.ts` |
+| E2E full suite | `pnpm --filter @familysync/pwa test:e2e` |
+
+### Phase Requirements → Validation Map
+
+| Workstream | Behavior | Test Type | Command / Method | Automated? |
+|------------|----------|-----------|------------------|------------|
+| A — FAB overlap | FAB bottom edge ≤ BottomTabBar top edge on iphone/pixel | Playwright geometry assertion | New assertion in `layout.spec.ts` | CI (iphone + pixel profiles) |
+| A — Content clearance | Color legend chips visible; content scrollable above bar | Playwright + playwright-cli sweep | `layout.spec.ts` full suite + manual scroll | Partially automated |
+| A — No horizontal overflow | `scrollWidth ≤ clientWidth` after fix | Playwright Rule 2 | Existing `layout.spec.ts` Rule 2 tests | CI (all profiles) |
+| A — Tap targets preserved | All existing ≥44px/≥56px assertions pass | Playwright Rule 1 | Existing `layout.spec.ts` Rule 1 tests | CI (all profiles) |
+| B — Asset existence | All 7 files present in `apps/pwa/public/` | Shell `ls` / existence check | `ls apps/pwa/public/{favicon.svg,favicon.ico,icon-192.png,icon-512.png,icon-maskable-512.png,apple-touch-icon.png,logo.svg}` | CI gate / Wave 0 check |
+| B — Manifest references resolve | PWA manifest icons all 200 in browser | Playwright | `page.goto('/')` then check `navigator.serviceWorker` / devtools manifest tab | playwright-cli |
+| B — Maskable dimensions | `icon-maskable-512.png` is exactly 512×512 | Node.js check using `sharp` | `node -e "require('sharp')('/path/icon-maskable-512.png').metadata().then(m => console.log(m.width, m.height))"` | Scripted |
+| B — ICO is not zero-byte | `favicon.ico` exists and is >100 bytes | Shell | `test $(wc -c < apps/pwa/public/favicon.ico) -gt 100` | CI gate |
+| B — Visual logo approval | Logo meets warm/rounded brief | Human review | playwright-cli screenshot + operator approval | Human checkpoint (checkpoint:human-verify) |
+| C — No hard-coded values in components | `grep` finds no hex/px literals in component files | `grep` | `grep -rn '#[0-9a-fA-F]\{3,6\}\|[0-9]\+px' apps/pwa/src/components/ apps/pwa/src/routes/` | CI gate |
+| C — Schedule-X colors unchanged | Calendar grid retains custom colors post-restructure | Playwright + playwright-cli | playwright-cli visual sweep of /calendar | playwright-cli |
+| C — Build succeeds | TypeScript + Vite build exits 0 | Build | `pnpm --filter @familysync/pwa build` | CI |
+| D-07 — Logout control renders | "Sign out" button visible in SettingsSheet | Playwright + playwright-cli | playwright-cli: open settings sheet, confirm button visible | playwright-cli |
+| D-07 — Logout wiring | `fetchLocalLogout` called on click; navigate to /login | Playwright interaction | playwright-cli: click Sign out, confirm redirect to /login | playwright-cli |
+| D-08 — Admin create toast | "Member added." toast appears after create success | Playwright interaction | playwright-cli: create member, confirm toast | playwright-cli (admin session) |
+| D-08 — Admin reset toast | "Password reset." toast appears after reset success | Playwright interaction | playwright-cli: reset password, confirm toast | playwright-cli (admin session) |
+| D-08 — Toast auto-dismiss | Toast disappears after ~3 seconds | Playwright interaction | playwright-cli: wait 3.5s after toast appears | playwright-cli |
+| D-09 — Dialog desktop centering | Sheet renders centered (`top: 50%; left: 50%; transform`) on desktop | Playwright geometry | playwright-cli at 1280×720: open SettingsSheet, confirm geometry | playwright-cli (desktop) |
+| D-09 — Dialog phone bottom-sheet | Sheet renders at bottom on phone | Playwright geometry | playwright-cli at 390×844: open SettingsSheet, confirm bottom-sheet | playwright-cli (phone) |
+| D-10 — Admin tabs render | Two-tab strip visible with correct labels | Playwright | playwright-cli at /admin: confirm "Members & Accounts" and "Settings" tabs | playwright-cli (admin session) |
+| D-10 — Admin tabs keyboard | ArrowLeft/ArrowRight switches tabs | Playwright keyboard | playwright-cli: focus tab, ArrowRight, confirm second tab active | playwright-cli |
+| D-10 — Admin tab ARIA | `role="tablist"`, `role="tab"`, `aria-selected`, `role="tabpanel"` present | Playwright | `page.getByRole('tablist')`, `page.getByRole('tab', {name: ...})` | Playwright test (add to layout.spec.ts or admin.spec.ts) |
+
+### Sampling Rate
+
+- **Per task commit:** `pnpm --filter @familysync/pwa exec playwright test --project=pixel layout.spec.ts` (fast; phone profile covers the primary fix geometry)
+- **Per wave merge:** `pnpm --filter @familysync/pwa test:e2e` (full 3-profile suite)
+- **Phase gate:** Full Playwright suite green + playwright-cli visual sweeps passed + human logo approval received before `/gsd-verify-work`
+
+### Wave 0 Gaps
+
+- [ ] The overlap regression assertion does not exist yet — add to `apps/pwa/e2e/layout.spec.ts` (Workstream A)
+- [ ] Admin tab ARIA assertions — add to a new `apps/pwa/e2e/admin.spec.ts` or append to `layout.spec.ts` (Workstream D-10)
+- [ ] Asset existence check script — can be a Wave 0 npm script or inline CI step
+
+---
+
+## Security Domain
+
+`security_enforcement: true` in `.planning/config.json`. ASVS level 1.
+
+| ASVS Category | Applies | Control |
+|---------------|---------|---------|
+| V2 Authentication | No — no auth changes; logout calls existing endpoint | Existing endpoint (`POST /api/auth/local/logout`) already verified in Phase 19 |
+| V3 Session Management | Indirect — logout clears session cookie | `fetchLocalLogout` posts to existing endpoint; cookie clearance is server-side |
+| V4 Access Control | No — admin page UX gating unchanged; server 403 unchanged | No new routes or authorization changes |
+| V5 Input Validation | Minimal — admin tab state, toast message strings are hardcoded constants | No user input reaches new UI surfaces except the existing admin forms (unchanged) |
+| V6 Cryptography | No | No new crypto |
+
+### Known Threat Patterns
+
+| Pattern | STRIDE | Mitigation |
+|---------|--------|------------|
+| XSS via toast message content | Spoofing/Tampering | Toast copy is hardcoded JSX string constants ("Member added." / "Password reset.") — no user-controlled content; T-05-24 invariant maintained |
+| Session fixation after logout | Elevation of Privilege | `fetchLocalLogout` clears the `local-session` cookie server-side; client navigates to `/login` regardless of success/failure |
+| Admin route access without OIDC | Elevation of Privilege | No change — `isAdmin` check in App.tsx is UX-only; server enforces 403 on all `/api/admin/*` (unchanged) |
+
+---
+
+## Assumptions Log
+
+| # | Claim | Section | Risk if Wrong |
+|---|-------|---------|---------------|
+| A1 | `@vite-pwa/assets-generator` `minimal-2023` preset generates a maskable icon with the logo properly inset in the 80% safe zone (not just solid-color fill) | Standard Stack / Asset Toolchain | If the preset only fills the 512×512 with a background and does not inset the logo, the maskable icon will have the logo cropped on adaptive-icon masks — require custom `padding` option in config |
+| A2 | The 48×48 single-size `favicon.ico` from `@vite-pwa/assets-generator` is adequate for this household app (vs. 16+32 multi-size) | Standard Stack | Negligible visual risk — legacy browsers (IE, old Safari) may show a slightly blurry icon; no functional impact for modern browsers which prefer `favicon.svg` |
+| A3 | `sharp` SUS verdict is a false positive due to version recency window; the package is safe to use | Package Legitimacy Audit | Near-zero risk — 13-year-old package, 65.6M weekly downloads, lovell/sharp well-known author; risk if the seam has additional signals not surfaced in the output |
+| A4 | Hand-authoring SVG for the logo (warm/rounded family vibes) in-phase by Claude produces a logo that meets the brand brief to the operator's satisfaction at the checkpoint | Workstream B | If operator rejects the generated logo, the phase stalls at the checkpoint; the plan must include a checkpoint:human-verify before assets are wired in |
+
+---
+
+## Open Questions
+
+1. **`@vite-pwa/assets-generator` maskable padding behavior**
+ - What we know: the `minimal-2023` preset produces a `maskable` 512×512 PNG with a white background; the documentation describes it as "safe zone padded"
+ - What's unclear: whether the preset option allows overriding the background color to a warm brand color (e.g., `#fef3ec`) matching the logo palette, vs. always producing white
+ - Recommendation: use white background for the maskable icon in Wave 1; if the operator wants a brand-color background, add a `maskableIconOptions` config in `pwa-assets.config.ts` at the checkpoint
+
+2. **Brand accent checkpoint outcome**
+ - What we know: two candidates (Variant A: `#4a90d9` cool blue; Variant B: warm rose `#f25c7a` or amber `#e8915a`) per UI-SPEC §Color
+ - What's unclear: which the operator will select after seeing the logo
+ - Recommendation: produce the logo, show both accent variants in context (the token restructure in C makes it a one-line swap), checkpoint before committing accent to `index.html`/`vite.config.ts`/`tokens.css`
+
+---
+
+## Sources
+
+### Primary (HIGH confidence — official project documentation)
+- `apps/pwa/src/App.tsx` — `contentStyle`, `isPhone()`, phone/desktop branch; confirmed missing `paddingBottom` [VERIFIED: codebase grep]
+- `apps/pwa/src/components/CalendarShell.tsx:469–470` — FAB `bottom: 'var(--space-6)'` defect [VERIFIED: codebase grep]
+- `apps/pwa/src/components/BottomTabBar.tsx:72` — bar `height: 'calc(56px + env(safe-area-inset-bottom, 0px))'` [VERIFIED: codebase grep]
+- `apps/pwa/src/api/client.ts:124–134` — `fetchLocalLogout()` exists, POST, credentials include [VERIFIED: codebase grep]
+- `apps/pwa/src/styles/tokens.css` — single `:root {}` block confirmed; `--sx-color-*` overrides at bottom [VERIFIED: codebase grep]
+- `apps/pwa/vite.config.ts:38–42` — maskable icon defect (reusing `icon-512.png`) confirmed [VERIFIED: codebase grep]
+- `apps/pwa/index.html` — no `` entries confirmed [VERIFIED: codebase grep]
+- `apps/pwa/public/` — only 3 stub files, none maskable, no favicon.ico/svg [VERIFIED: codebase grep]
+- `.planning/config.json` — `nyquist_validation: true`, `security_enforcement: true` [VERIFIED: codebase grep]
+
+### Secondary (MEDIUM confidence — official package docs)
+- `@vite-pwa/assets-generator` v1.0.2 — vite-pwa-org.netlify.app/assets-generator/ [CITED: vite-pwa-org.netlify.app/assets-generator/]
+- `sharp` v0.35.1 — sharp.pixelplumbing.com; github.com/lovell/sharp [CITED: npm registry metadata]
+- `vite-plugin-pwa` v1.3.0 — peer-depends on `@vite-pwa/assets-generator ^1.0.0` [CITED: npm registry peerDependencies]
+
+### Tertiary (LOW confidence — training knowledge)
+- ARIA tabs pattern (roving tabindex, `role="tablist"/"tab"/"tabpanel"`) — standard W3C ARIA spec [ASSUMED — widely documented, no drift risk]
+
+---
+
+## Metadata
+
+**Confidence breakdown:**
+- Fix surfaces: HIGH — directly confirmed against codebase source
+- Asset toolchain: MEDIUM — based on official vite-pwa documentation and npm registry; `minimal-2023` preset maskable behavior [ASSUMED] pending a test run
+- Architecture patterns: HIGH — Workstreams A/C/D are CSS/React patterns with no external dependencies
+- Pitfalls: HIGH — drawn from confirmed code structure and known project conventions
+
+**Research date:** 2026-06-18
+**Valid until:** 2026-08-18 (stable APIs; vite-plugin-pwa and @vite-pwa/assets-generator are stable releases)
diff --git a/.planning/phases/17-ui-optimization-polish/17-REVIEW-FIX.iter2.md b/.planning/phases/17-ui-optimization-polish/17-REVIEW-FIX.iter2.md
new file mode 100644
index 0000000..0eb8662
--- /dev/null
+++ b/.planning/phases/17-ui-optimization-polish/17-REVIEW-FIX.iter2.md
@@ -0,0 +1,125 @@
+---
+phase: 17-ui-optimization-polish
+fixed_at: 2026-06-18T00:00:00Z
+review_path: .planning/phases/17-ui-optimization-polish/17-REVIEW.md
+iteration: 1
+findings_in_scope: 15
+fixed: 15
+skipped: 0
+status: all_fixed
+---
+
+# Phase 17: Code Review Fix Report
+
+**Fixed at:** 2026-06-18T00:00:00Z
+**Source review:** .planning/phases/17-ui-optimization-polish/17-REVIEW.md
+**Iteration:** 1
+
+**Summary:**
+- Findings in scope: 15 (fix_scope: all — includes Info)
+- Fixed: 15
+- Skipped: 0
+
+All fixes were verified with `tsc --noEmit` (clean) and `eslint --max-warnings 0`
+(clean) on every touched file; the PWA also builds (`vite build` succeeds). A new
+shared hook `apps/pwa/src/hooks/useIsPhone.ts` was created to back WR-05/IN-03.
+
+## Fixed Issues
+
+### WR-01: Modal dialogs declare `aria-modal="true"` but do not trap focus
+
+**Files modified:** `apps/pwa/src/components/CredentialSheet.tsx`, `apps/pwa/src/components/SettingsSheet.tsx`, `apps/pwa/src/routes/AdminPage.tsx`
+**Commit:** fb30800
+**Applied fix:** Reused the existing `useFocusTrap(dialogRef)` hook (already used by EventForm/SeriesEditPrompt). Added a `dialogRef` + `onKeyDown={handleDialogKeyDown}` to every modal sheet that asserts `aria-modal="true"`: CredentialSheet, SettingsSheet, ChangePasswordSheet, LinkOidcSheet, and ResetPasswordSheet. Tab/Shift-Tab now cycle within the dialog instead of escaping to occluded background controls.
+
+### WR-02: Admin tab strip keyboard nav is incomplete (no Home/End, no explicit wrap)
+
+**Files modified:** `apps/pwa/src/routes/AdminPage.tsx`
+**Commit:** f601c0c
+**Applied fix:** Rewrote `handleTabKeyDown` to the full WAI-ARIA tabs pattern: ArrowLeft/Right now wrap around the ends using modular arithmetic over the `['members','settings']` order, and Home/End jump to the first/last tab.
+
+### WR-03: Success toast does not re-announce repeated identical messages
+
+**Files modified:** `apps/pwa/src/routes/AdminPage.tsx`
+**Commit:** f601c0c
+**Applied fix:** Changed toast state from `string | null` to `{ id: number; msg: string } | null` with a `showToast(msg)` helper that mints a fresh `id` (Date.now()) per call. The rendered toast `` is now keyed on `toast.id` so an identical repeated message remounts and `aria-live` re-announces it; the auto-dismiss effect depends on the fresh object reference so the 3s timer restarts.
+
+### WR-04: Toast `whiteSpace: nowrap` is a latent horizontal-overflow regression
+
+**Files modified:** `apps/pwa/src/routes/AdminPage.tsx`
+**Commit:** f601c0c
+**Applied fix:** Removed `whiteSpace: 'nowrap'` from the toast style so a longer/localized message wraps within `maxWidth: 90vw` instead of overflowing `documentElement.scrollWidth` (which would trip the layout suite's no-horizontal-overflow rule).
+
+### WR-05: `matchMedia(...)` read at render time does not react to resize/orientation
+
+**Files modified:** `apps/pwa/src/hooks/useIsPhone.ts` (new), `apps/pwa/src/App.tsx`, `apps/pwa/src/components/CalendarShell.tsx`, `apps/pwa/src/components/SettingsSheet.tsx`, `apps/pwa/src/components/CredentialSheet.tsx`, `apps/pwa/src/routes/AdminPage.tsx`
+**Commit:** a4a7438
+**Applied fix:** Added a resize-aware `useMediaQuery`/`useIsPhone` hook backed by `matchMedia.addEventListener('change', …)`. Replaced all six synchronous `matchMedia('(max-width: 767px)')` render-time reads with `useIsPhone()`. Hook calls were placed before any early `return null` to respect the Rules of Hooks. Components now re-render when the 767px breakpoint is crossed (iPad rotation, desktop resize).
+
+### WR-06: Timezone combobox `aria-activedescendant`/highlight can desync after filtering
+
+**Files modified:** `apps/pwa/src/routes/AdminPage.tsx`
+**Commit:** 1c0f357
+**Applied fix:** Derived a clamped `tzActiveIndexClamped = Math.min(tzActiveIndex, max(0, filteredZones.length - 1))` in render and used it for `aria-activedescendant`, the Enter-to-commit lookup, and the visual highlight (`i === tzActiveIndexClamped`). ArrowUp/ArrowDown clamp the current index before moving so they never start from a stale position past the end of a freshly-shrunk list.
+**Note:** Combobox interaction logic — recommend a quick manual/keyboard pass (type to filter, arrow, Enter) to confirm behavior.
+
+### WR-07: Timezone combobox drops Tab-to-commit and relies on a fragile blur timeout
+
+**Files modified:** `apps/pwa/src/routes/AdminPage.tsx`
+**Commit:** 1c0f357
+**Applied fix:** Added a `Tab` branch to the combobox `onKeyDown` that commits the highlighted option WITHOUT `preventDefault` (focus still advances to Save). Added an unmount cleanup effect that clears `tzBlurTimer`. Reduced the blur-close `setTimeout` from 120ms to 0ms now that options `preventDefault()` on `onMouseDown` (so a click never blurs the input first).
+**Note:** Interaction logic — recommend a manual check that tabbing out of the open listbox commits the highlighted zone and that clicking an option still selects it.
+
+### WR-08: `pwa:icons` script is non-portable and silently coupled to generated filenames
+
+**Files modified:** `apps/pwa/scripts/copy-pwa-icons.mjs` (new), `apps/pwa/package.json`, `apps/pwa/vite.config.ts`
+**Commit:** dd0b761
+**Applied fix:** Replaced the five-`cp` Unix-only chain with a cross-platform Node script (`fs.copyFileSync`) that maps each generated filename to its stable manifest name and fails loudly with a named error if a generated file is missing (generator rename guard). Added a discoverability comment beside the manifest `icons` array in `vite.config.ts` pointing at the script's COPIES table.
+
+### IN-01: `OidcRedirect` navigates as a render-phase side effect
+
+**Files modified:** `apps/pwa/src/App.tsx`
+**Commit:** a4a7438
+**Applied fix:** Moved `window.location.replace('/api/login')` into a `useEffect(() => {...}, [])` so the navigation is no longer a render-phase side effect.
+
+### IN-02: Inconsistent `exhaustive-deps` disables across sibling dialogs
+
+**Files modified:** `apps/pwa/src/components/CredentialSheet.tsx`, `apps/pwa/src/components/SettingsSheet.tsx`
+**Commit:** 3f4b7ea
+**Applied fix:** Wrapped `handleClose` in `useCallback` in CredentialSheet and ChangePasswordSheet, added it to the Escape effect's dependency array, and removed the `// eslint-disable-line react-hooks/exhaustive-deps` comments — matching the LinkOidc/Reset sheet pattern.
+
+### IN-03: `isPhone`/`phone` 767px check duplicated across ~6 sites
+
+**Files modified:** (same as WR-05)
+**Commit:** a4a7438
+**Applied fix:** Resolved together with WR-05 — the single `useIsPhone()` hook now backs all call sites, and the `(max-width: 767px)` query lives in one place (`PHONE_MAX_QUERY` in the hook). The old standalone `isPhone()` helpers in App.tsx and CalendarShell.tsx were deleted.
+
+### IN-04: Dead placeholder brand tokens retained
+
+**Files modified:** `apps/pwa/src/styles/tokens.css`
+**Commit:** 2317833
+**Applied fix:** Removed the unused `--brand-logo-bg`, `--brand-logo-text`, and `--brand-app-name` declarations (verified via grep that nothing references them); left a short comment explaining the removal and that BrandSlot only reads `--brand-logo-size`/`--brand-logo-border-radius`.
+
+### IN-05: Admin members-panel JSX has inconsistent indentation / stacked bottom margins
+
+**Files modified:** `apps/pwa/src/routes/AdminPage.tsx`
+**Commit:** 4bc1e2a
+**Applied fix:** Ran Prettier (project `.prettierrc`) over AdminPage.tsx, normalizing the members-panel indentation and the rest of the file's drift; `prettier --check` now passes on the file. The stacked `marginBottom: var(--space-8)` on the last panel section was left intentionally — the review flagged it only as a minor cosmetic note, and changing section spacing risks a visual regression outside the finding's scope.
+
+### IN-06: Toast and dialog `zIndex` overlap (300/301)
+
+**Files modified:** `apps/pwa/src/routes/AdminPage.tsx`
+**Commit:** f601c0c
+**Applied fix:** Raised the toast `zIndex` from 300 to 400 so it always paints above sheet backdrops (300) and sheets (301), removing the DOM-order-dependent paint ambiguity.
+
+### IN-07: `Intl.DateTimeFormat()` recomputed every render in the calendar-config path
+
+**Files modified:** `apps/pwa/src/components/CalendarShell.tsx`, `apps/pwa/src/routes/AdminPage.tsx`
+**Commit:** 11b6b36
+**Applied fix:** Wrapped both `Intl.DateTimeFormat().resolvedOptions().timeZone` reads in `useMemo(…, [])` — `displayTimeZone` in CalendarShell (feeds the stable `useCalendarApp` config) and `detectedTz` in AdminPage.
+
+---
+
+_Fixed: 2026-06-18T00:00:00Z_
+_Fixer: Claude (gsd-code-fixer)_
+_Iteration: 1_
diff --git a/.planning/phases/17-ui-optimization-polish/17-REVIEW-FIX.iter3.md b/.planning/phases/17-ui-optimization-polish/17-REVIEW-FIX.iter3.md
new file mode 100644
index 0000000..0eb8662
--- /dev/null
+++ b/.planning/phases/17-ui-optimization-polish/17-REVIEW-FIX.iter3.md
@@ -0,0 +1,125 @@
+---
+phase: 17-ui-optimization-polish
+fixed_at: 2026-06-18T00:00:00Z
+review_path: .planning/phases/17-ui-optimization-polish/17-REVIEW.md
+iteration: 1
+findings_in_scope: 15
+fixed: 15
+skipped: 0
+status: all_fixed
+---
+
+# Phase 17: Code Review Fix Report
+
+**Fixed at:** 2026-06-18T00:00:00Z
+**Source review:** .planning/phases/17-ui-optimization-polish/17-REVIEW.md
+**Iteration:** 1
+
+**Summary:**
+- Findings in scope: 15 (fix_scope: all — includes Info)
+- Fixed: 15
+- Skipped: 0
+
+All fixes were verified with `tsc --noEmit` (clean) and `eslint --max-warnings 0`
+(clean) on every touched file; the PWA also builds (`vite build` succeeds). A new
+shared hook `apps/pwa/src/hooks/useIsPhone.ts` was created to back WR-05/IN-03.
+
+## Fixed Issues
+
+### WR-01: Modal dialogs declare `aria-modal="true"` but do not trap focus
+
+**Files modified:** `apps/pwa/src/components/CredentialSheet.tsx`, `apps/pwa/src/components/SettingsSheet.tsx`, `apps/pwa/src/routes/AdminPage.tsx`
+**Commit:** fb30800
+**Applied fix:** Reused the existing `useFocusTrap(dialogRef)` hook (already used by EventForm/SeriesEditPrompt). Added a `dialogRef` + `onKeyDown={handleDialogKeyDown}` to every modal sheet that asserts `aria-modal="true"`: CredentialSheet, SettingsSheet, ChangePasswordSheet, LinkOidcSheet, and ResetPasswordSheet. Tab/Shift-Tab now cycle within the dialog instead of escaping to occluded background controls.
+
+### WR-02: Admin tab strip keyboard nav is incomplete (no Home/End, no explicit wrap)
+
+**Files modified:** `apps/pwa/src/routes/AdminPage.tsx`
+**Commit:** f601c0c
+**Applied fix:** Rewrote `handleTabKeyDown` to the full WAI-ARIA tabs pattern: ArrowLeft/Right now wrap around the ends using modular arithmetic over the `['members','settings']` order, and Home/End jump to the first/last tab.
+
+### WR-03: Success toast does not re-announce repeated identical messages
+
+**Files modified:** `apps/pwa/src/routes/AdminPage.tsx`
+**Commit:** f601c0c
+**Applied fix:** Changed toast state from `string | null` to `{ id: number; msg: string } | null` with a `showToast(msg)` helper that mints a fresh `id` (Date.now()) per call. The rendered toast `` is now keyed on `toast.id` so an identical repeated message remounts and `aria-live` re-announces it; the auto-dismiss effect depends on the fresh object reference so the 3s timer restarts.
+
+### WR-04: Toast `whiteSpace: nowrap` is a latent horizontal-overflow regression
+
+**Files modified:** `apps/pwa/src/routes/AdminPage.tsx`
+**Commit:** f601c0c
+**Applied fix:** Removed `whiteSpace: 'nowrap'` from the toast style so a longer/localized message wraps within `maxWidth: 90vw` instead of overflowing `documentElement.scrollWidth` (which would trip the layout suite's no-horizontal-overflow rule).
+
+### WR-05: `matchMedia(...)` read at render time does not react to resize/orientation
+
+**Files modified:** `apps/pwa/src/hooks/useIsPhone.ts` (new), `apps/pwa/src/App.tsx`, `apps/pwa/src/components/CalendarShell.tsx`, `apps/pwa/src/components/SettingsSheet.tsx`, `apps/pwa/src/components/CredentialSheet.tsx`, `apps/pwa/src/routes/AdminPage.tsx`
+**Commit:** a4a7438
+**Applied fix:** Added a resize-aware `useMediaQuery`/`useIsPhone` hook backed by `matchMedia.addEventListener('change', …)`. Replaced all six synchronous `matchMedia('(max-width: 767px)')` render-time reads with `useIsPhone()`. Hook calls were placed before any early `return null` to respect the Rules of Hooks. Components now re-render when the 767px breakpoint is crossed (iPad rotation, desktop resize).
+
+### WR-06: Timezone combobox `aria-activedescendant`/highlight can desync after filtering
+
+**Files modified:** `apps/pwa/src/routes/AdminPage.tsx`
+**Commit:** 1c0f357
+**Applied fix:** Derived a clamped `tzActiveIndexClamped = Math.min(tzActiveIndex, max(0, filteredZones.length - 1))` in render and used it for `aria-activedescendant`, the Enter-to-commit lookup, and the visual highlight (`i === tzActiveIndexClamped`). ArrowUp/ArrowDown clamp the current index before moving so they never start from a stale position past the end of a freshly-shrunk list.
+**Note:** Combobox interaction logic — recommend a quick manual/keyboard pass (type to filter, arrow, Enter) to confirm behavior.
+
+### WR-07: Timezone combobox drops Tab-to-commit and relies on a fragile blur timeout
+
+**Files modified:** `apps/pwa/src/routes/AdminPage.tsx`
+**Commit:** 1c0f357
+**Applied fix:** Added a `Tab` branch to the combobox `onKeyDown` that commits the highlighted option WITHOUT `preventDefault` (focus still advances to Save). Added an unmount cleanup effect that clears `tzBlurTimer`. Reduced the blur-close `setTimeout` from 120ms to 0ms now that options `preventDefault()` on `onMouseDown` (so a click never blurs the input first).
+**Note:** Interaction logic — recommend a manual check that tabbing out of the open listbox commits the highlighted zone and that clicking an option still selects it.
+
+### WR-08: `pwa:icons` script is non-portable and silently coupled to generated filenames
+
+**Files modified:** `apps/pwa/scripts/copy-pwa-icons.mjs` (new), `apps/pwa/package.json`, `apps/pwa/vite.config.ts`
+**Commit:** dd0b761
+**Applied fix:** Replaced the five-`cp` Unix-only chain with a cross-platform Node script (`fs.copyFileSync`) that maps each generated filename to its stable manifest name and fails loudly with a named error if a generated file is missing (generator rename guard). Added a discoverability comment beside the manifest `icons` array in `vite.config.ts` pointing at the script's COPIES table.
+
+### IN-01: `OidcRedirect` navigates as a render-phase side effect
+
+**Files modified:** `apps/pwa/src/App.tsx`
+**Commit:** a4a7438
+**Applied fix:** Moved `window.location.replace('/api/login')` into a `useEffect(() => {...}, [])` so the navigation is no longer a render-phase side effect.
+
+### IN-02: Inconsistent `exhaustive-deps` disables across sibling dialogs
+
+**Files modified:** `apps/pwa/src/components/CredentialSheet.tsx`, `apps/pwa/src/components/SettingsSheet.tsx`
+**Commit:** 3f4b7ea
+**Applied fix:** Wrapped `handleClose` in `useCallback` in CredentialSheet and ChangePasswordSheet, added it to the Escape effect's dependency array, and removed the `// eslint-disable-line react-hooks/exhaustive-deps` comments — matching the LinkOidc/Reset sheet pattern.
+
+### IN-03: `isPhone`/`phone` 767px check duplicated across ~6 sites
+
+**Files modified:** (same as WR-05)
+**Commit:** a4a7438
+**Applied fix:** Resolved together with WR-05 — the single `useIsPhone()` hook now backs all call sites, and the `(max-width: 767px)` query lives in one place (`PHONE_MAX_QUERY` in the hook). The old standalone `isPhone()` helpers in App.tsx and CalendarShell.tsx were deleted.
+
+### IN-04: Dead placeholder brand tokens retained
+
+**Files modified:** `apps/pwa/src/styles/tokens.css`
+**Commit:** 2317833
+**Applied fix:** Removed the unused `--brand-logo-bg`, `--brand-logo-text`, and `--brand-app-name` declarations (verified via grep that nothing references them); left a short comment explaining the removal and that BrandSlot only reads `--brand-logo-size`/`--brand-logo-border-radius`.
+
+### IN-05: Admin members-panel JSX has inconsistent indentation / stacked bottom margins
+
+**Files modified:** `apps/pwa/src/routes/AdminPage.tsx`
+**Commit:** 4bc1e2a
+**Applied fix:** Ran Prettier (project `.prettierrc`) over AdminPage.tsx, normalizing the members-panel indentation and the rest of the file's drift; `prettier --check` now passes on the file. The stacked `marginBottom: var(--space-8)` on the last panel section was left intentionally — the review flagged it only as a minor cosmetic note, and changing section spacing risks a visual regression outside the finding's scope.
+
+### IN-06: Toast and dialog `zIndex` overlap (300/301)
+
+**Files modified:** `apps/pwa/src/routes/AdminPage.tsx`
+**Commit:** f601c0c
+**Applied fix:** Raised the toast `zIndex` from 300 to 400 so it always paints above sheet backdrops (300) and sheets (301), removing the DOM-order-dependent paint ambiguity.
+
+### IN-07: `Intl.DateTimeFormat()` recomputed every render in the calendar-config path
+
+**Files modified:** `apps/pwa/src/components/CalendarShell.tsx`, `apps/pwa/src/routes/AdminPage.tsx`
+**Commit:** 11b6b36
+**Applied fix:** Wrapped both `Intl.DateTimeFormat().resolvedOptions().timeZone` reads in `useMemo(…, [])` — `displayTimeZone` in CalendarShell (feeds the stable `useCalendarApp` config) and `detectedTz` in AdminPage.
+
+---
+
+_Fixed: 2026-06-18T00:00:00Z_
+_Fixer: Claude (gsd-code-fixer)_
+_Iteration: 1_
diff --git a/.planning/phases/17-ui-optimization-polish/17-REVIEW-FIX.md b/.planning/phases/17-ui-optimization-polish/17-REVIEW-FIX.md
new file mode 100644
index 0000000..cf13a44
--- /dev/null
+++ b/.planning/phases/17-ui-optimization-polish/17-REVIEW-FIX.md
@@ -0,0 +1,56 @@
+---
+phase: 17-ui-optimization-polish
+fixed_at: 2026-06-18T14:04:00Z
+review_path: .planning/phases/17-ui-optimization-polish/17-REVIEW.md
+iteration: 3
+findings_in_scope: 2
+fixed: 2
+skipped: 0
+status: all_fixed
+---
+
+# Phase 17: Code Review Fix Report (Iteration 3)
+
+**Fixed at:** 2026-06-18T14:04:00Z
+**Source review:** .planning/phases/17-ui-optimization-polish/17-REVIEW.md
+**Iteration:** 3
+
+**Summary:**
+- Findings in scope: 2 (fix_scope: all — includes Info)
+- Fixed: 2
+- Skipped: 0
+
+**Gate status after fixes (all pass):**
+- `pnpm --filter @familysync/pwa test` → pass (22 files, 266 passed / 0 failed)
+- `pnpm --filter @familysync/pwa typecheck` → pass (tsc + e2e tsconfig)
+- `pnpm --filter @familysync/pwa lint` → pass (eslint `--max-warnings 0`)
+
+## Fixed Issues
+
+### CR-01: `useFocusTrap` visibility filter excluded all focusables under jsdom (CI gate failed)
+
+**Files modified:** `apps/pwa/src/hooks/useFocusTrap.ts`
+**Commit:** 287ecae
+**Applied fix:** The prior iter-3 auto-fix (WR-01) rejected every focusable under jsdom because there `getBoundingClientRect()` returns all-zero geometry and `offsetParent` is `null` for every node, which short-circuited the trap (`focusable.length === 0`) and broke the two pre-existing WR-07 focus-trap regression tests — making `pnpm test` (a CI gate) fail at 2 failed / 264 passed.
+
+Made the visibility heuristic tolerant of a non-layout environment: it now derives `hasLayout = r.width > 0 || r.height > 0 || el.offsetParent !== null`, and when there is no evidence of a layout engine (jsdom) it treats the node as visible instead of filtering it. Only when a real layout exists does it apply the `offsetParent === null` / zero-geometry exclusion, so genuinely hidden/collapsed nodes are still excluded in a real browser. The `hidden`-attribute exclusion is unambiguous regardless of layout, so it was hoisted out and kept unconditional. Result: all 266 PWA tests pass, including both WR-07 cases.
+
+### IN-01: Focus-trap containment guard was unreachable as wired (harmless dead branch)
+
+**Files modified:** `apps/pwa/src/hooks/useFocusTrap.ts`
+**Commit:** 287ecae
+**Applied fix:** The handler is wired only to each dialog's own `onKeyDown`, so it can only run while focus is already inside the dialog subtree; the `!dialogRef.current.contains(document.activeElement)` containment branch could therefore never evaluate true and delivered no actual containment guarantee. Per the review's recommendation, removed the inert branch and replaced its misleading comment with an accurate note: this is a deliberate boundary-only trap (a `document`-level `keydown`/`focusin` listener would be required for true containment, and is unnecessary for the current always-focus-the-heading-on-open flows). No behavior change in any real scenario — it only removes a comment that implied a guarantee the wiring cannot provide.
+
+## Skipped Issues
+
+None.
+
+## Prior Iterations
+
+Iterations 1 and 2 fixed the earlier batches of findings (15 in iter-1, then the iter-3 review's WR-01/IN-02/IN-03 set). The IN-02 (favicon.ico coupling) and IN-03 (OidcRedirect visible status) fixes were confirmed clean by the final re-review. This iteration-3 report supersedes those and records the final state: the WR-01 regression (CR-01) and its inert containment guard (IN-01) are now resolved, with all CI gates green.
+
+---
+
+_Fixed: 2026-06-18T14:04:00Z_
+_Fixer: Claude (gsd-code-fixer)_
+_Iteration: 3_
diff --git a/.planning/phases/17-ui-optimization-polish/17-REVIEW.iter2.md b/.planning/phases/17-ui-optimization-polish/17-REVIEW.iter2.md
new file mode 100644
index 0000000..60ec5fd
--- /dev/null
+++ b/.planning/phases/17-ui-optimization-polish/17-REVIEW.iter2.md
@@ -0,0 +1,167 @@
+---
+phase: 17-ui-optimization-polish
+reviewed: 2026-06-18T00:00:00Z
+depth: deep
+files_reviewed: 13
+files_reviewed_list:
+ - apps/pwa/e2e/admin.spec.ts
+ - apps/pwa/e2e/layout.spec.ts
+ - apps/pwa/index.html
+ - apps/pwa/package.json
+ - apps/pwa/pwa-assets.config.ts
+ - apps/pwa/src/App.tsx
+ - apps/pwa/src/components/BrandSlot.tsx
+ - apps/pwa/src/components/CalendarShell.tsx
+ - apps/pwa/src/components/CredentialSheet.tsx
+ - apps/pwa/src/components/SettingsSheet.tsx
+ - apps/pwa/src/routes/AdminPage.tsx
+ - apps/pwa/src/styles/tokens.css
+ - apps/pwa/vite.config.ts
+findings:
+ critical: 0
+ warning: 8
+ info: 7
+ total: 15
+status: issues_found
+---
+
+# Phase 17: Code Review Report
+
+**Reviewed:** 2026-06-18T00:00:00Z
+**Depth:** deep
+**Files Reviewed:** 13
+**Status:** issues_found
+
+## Summary
+
+Phase 17 is UI optimization/polish: brand logo swap, PWA manifest/icon hand-maintenance, an admin two-tab ARIA strip, a success toast, and a searchable timezone combobox, plus structural layout/admin Playwright suites. No structural-findings pre-pass was provided.
+
+The code is generally careful — XSS surfaces are plain-text JSX, password fields use `new-password` autocomplete and are never pre-filled, the OIDC `authorizationUrl` null is guarded before navigation, and touch targets are consistently ≥44px. I found **no BLOCKERs** (no injection, no secret leakage, no data-loss path, no crash on the happy path).
+
+There are real correctness/robustness defects worth fixing before ship: the **admin tab keyboard handler half-implements the WAI-ARIA tabs pattern** (no Home/End, no wrap); the **timezone combobox `aria-activedescendant`/highlight can desync after filtering** and **drops Tab-to-commit**; the **success toast does not re-announce** repeated identical messages and its `whiteSpace: nowrap` is a latent Rule-2 horizontal-overflow hazard against the project's own layout suite; **none of the modal dialogs trap focus** despite `aria-modal="true"`; and several `window.matchMedia` reads at render time **do not react to resize/orientation**, a stale-UI class this project explicitly cares about (iPad rotation).
+
+## Warnings
+
+### WR-01: Modal dialogs declare `aria-modal="true"` but do not trap focus
+
+**File:** `apps/pwa/src/components/CredentialSheet.tsx:173-176`, `apps/pwa/src/components/SettingsSheet.tsx:199-202` (plus ChangePasswordSheet ~667-701 and LinkOidcSheet ~979-1013), `apps/pwa/src/routes/AdminPage.tsx:1420-1423` (ResetPasswordSheet)
+**Issue:** Every sheet sets `role="dialog"` + `aria-modal="true"` and focuses the heading/close button on open, but none implements a focus trap. Tab/Shift-Tab can move focus out of the dialog to content behind the backdrop (still in the DOM). `aria-modal="true"` asserts to assistive tech that focus is contained — it is not. The app's stated UX hard-constraint is "slick and low-friction for a non-technical Apple member"; VoiceOver/keyboard users will escape the dialog silently and interact with occluded background controls.
+**Fix:** Add a focus trap — capture Tab/Shift-Tab in the dialog keydown handler and cycle between first/last focusable descendants, ideally as a shared `useFocusTrap(ref)` hook reused by all sheets:
+```tsx
+onKeyDown={(e) => {
+ if (e.key !== 'Tab') return;
+ const f = dialogRef.current?.querySelectorAll(
+ 'a[href],button:not([disabled]),input:not([disabled]),[tabindex]:not([tabindex="-1"])');
+ if (!f?.length) return;
+ const first = f[0], last = f[f.length - 1];
+ if (e.shiftKey && document.activeElement === first) { e.preventDefault(); last.focus(); }
+ else if (!e.shiftKey && document.activeElement === last) { e.preventDefault(); first.focus(); }
+}}
+```
+
+### WR-02: Admin tab strip keyboard nav is incomplete (no Home/End, no explicit wrap)
+
+**File:** `apps/pwa/src/routes/AdminPage.tsx:205-225`
+**Issue:** `handleTabKeyDown` handles only `ArrowRight`/`ArrowLeft`, and the next/prev computation is a two-state toggle that does not wrap (ArrowRight on the Settings tab is a no-op rather than wrapping to Members). The WAI-ARIA tabs pattern requires `Home`/`End` to jump to first/last tab. `admin.spec.ts` (lines 134-152) only exercises the Arrow keys, so this gap is untested and ships a half-pattern.
+**Fix:** Handle `Home`/`End` and decide wrap behavior explicitly:
+```tsx
+const order = ['members', 'settings'] as const;
+const idx = order.indexOf(current);
+let next: typeof order[number] | null = null;
+if (e.key === 'ArrowRight') next = order[(idx + 1) % order.length];
+else if (e.key === 'ArrowLeft') next = order[(idx - 1 + order.length) % order.length];
+else if (e.key === 'Home') next = order[0];
+else if (e.key === 'End') next = order[order.length - 1];
+if (next) { e.preventDefault(); setActiveTab(next); /* focus #admin-tab-${next} */ }
+```
+
+### WR-03: Success toast does not re-announce repeated identical messages
+
+**File:** `apps/pwa/src/routes/AdminPage.tsx:62-69`, `1028-1065`
+**Issue:** The toast is a single `role="status" aria-live="polite"` region rendering the `toast` string. If the same message fires twice (two password resets, two "Member added.") and the second `setToast('…')` lands before the first cleared, React's state-equality short-circuit means the DOM text does not change, so `aria-live` does not re-announce — the second success is silent to screen-reader users, and the 3s auto-dismiss timer (keyed on `toast` identity) does not reset for an identical string.
+**Fix:** Make each toast a distinct value and remount it so AT re-announces and the timer resets:
+```tsx
+const [toast, setToast] = useState<{ id: number; msg: string } | null>(null);
+const show = (msg: string) => setToast({ id: Date.now(), msg });
+// effect dep: [toast?.id]; render: {toast.msg}
+```
+
+### WR-04: Toast `whiteSpace: nowrap` is a latent horizontal-overflow regression against Rule 2
+
+**File:** `apps/pwa/src/routes/AdminPage.tsx:1054-1055`
+**Issue:** The toast sets `whiteSpace: 'nowrap'` with `maxWidth: '90vw'`. `nowrap` + `maxWidth` does not shrink text; it overflows. A longer/localized toast on a 390px viewport will exceed 90vw and, because the toast is `position: fixed`, contribute to `documentElement.scrollWidth` — violating `layout.spec.ts` Rule 2 (lines 176-200), which asserts no horizontal overflow on `/calendar` and `/lists`. Current strings are short, so the bug is latent, not active, but it is a direct hazard to the project's own quality bar.
+**Fix:** Remove `whiteSpace: 'nowrap'` (let it wrap), or bound the width and use `overflow:hidden; text-overflow:ellipsis`. Wrapping is safer for a toast that may localize.
+
+### WR-05: `matchMedia(...)` read at render time does not react to resize/orientation
+
+**File:** `apps/pwa/src/App.tsx:64-66` (`isPhone()`), `apps/pwa/src/components/CalendarShell.tsx:74-76`, `apps/pwa/src/components/SettingsSheet.tsx:135`, `apps/pwa/src/components/CredentialSheet.tsx:156`, `apps/pwa/src/routes/AdminPage.tsx:59`, `1378-1379`
+**Issue:** These components compute `phone` once per render via synchronous `matchMedia('(max-width: 767px)').matches`, with no `change` listener. Rotating an iPad across 767px (or resizing a desktop window across the breakpoint) does not trigger a re-render, so the layout (FAB vs toolbar button in `CalendarShell`, bottom-sheet vs centered modal in the sheets, content `paddingBottom` in `App`) stays stale until an unrelated state change forces a re-render. The developer profile explicitly flags resize/orientation correctness; iPad rotation is a realistic trigger for this cross-ecosystem app.
+**Fix:** Use a `useMediaQuery` hook backed by `matchMedia.addEventListener('change', …)` so components re-render on breakpoint crossing; share a single `phone` value through context/hook so all call sites stay consistent.
+
+### WR-06: Timezone combobox `aria-activedescendant`/highlight can desync after filtering
+
+**File:** `apps/pwa/src/routes/AdminPage.tsx:819-821`, `833-837`, `839-845`, `912-919`
+**Issue:** `onChange` resets `tzActiveIndex` to 0 while `ArrowDown` clamps against `filteredZones.length - 1` from the *current render closure*. With batched updates, interleavings exist where `tzActiveIndex` (and thus `aria-activedescendant={tz-opt-${tzActiveIndex}}`, line 820) references an option index that no longer exists after the filtered list shrinks (e.g., active 12, then a keystroke filters to 3 rows before re-clamp). Separately, the visual highlight uses `i === tzActiveIndex` (line 913) while `aria-selected` uses `tz === effectiveTimezoneInput` (line 919) — two different bases, so the highlighted row and the AT-announced row can disagree.
+**Fix:** Derive a clamped active index in render and use it everywhere (visual + `aria-activedescendant`): `const activeIndex = Math.min(tzActiveIndex, Math.max(0, filteredZones.length - 1))`, or reset `tzActiveIndex` to 0 in a `useEffect` keyed on `tzSearch`.
+
+### WR-07: Timezone combobox drops Tab-to-commit and relies on a fragile blur timeout
+
+**File:** `apps/pwa/src/routes/AdminPage.tsx:838-865`, `927`
+**Issue:** (1) `onKeyDown` handles ArrowUp/Down/Enter/Escape but not `Tab`. Tabbing out with the listbox open and an option highlighted moves focus to Save without committing — the input/`effectiveTimezoneInput` still holds the raw search text, so the admin can attempt to save a partial string (server 400s, but the UX is a confusing failure). (2) The `onBlur` 120ms `setTimeout` to let an option's `onClick` fire is a race; since options already `onMouseDown` `preventDefault()` (line 927), blur won't fire on option click, so the 120ms hack may be unnecessary. The `tzBlurTimer` is cleared on focus/select but not on unmount.
+**Fix:** Commit the active option on `Tab` (without `preventDefault`, so focus still advances); clear `tzBlurTimer` in an unmount cleanup effect; reassess/remove the 120ms blur delay now that `onMouseDown` preventDefault is in place.
+
+### WR-08: `pwa:icons` script is non-portable and silently coupled to generated filenames
+
+**File:** `apps/pwa/package.json:16`
+**Issue:** `pwa:icons` chains the assets generator with five `cp` commands. (1) `cp` is Unix-only — breaks on Windows contributors and minimal CI containers. (2) It hard-codes the generator's output names (`pwa-192x192.png`, `maskable-icon-512x512.png`, `apple-touch-icon-180x180.png`); a generator version bump that renames outputs breaks it with an opaque `cp: cannot stat`. (3) The manifest icon entries in `vite.config.ts:38-42` (`/icon-192.png`, etc.) only stay in sync because of these manual renames — an invisible coupling with no test. Regenerating icons without running the full script leaves the manifest referencing stale files.
+**Fix:** Configure the generator to emit the final filenames directly, or replace the `cp` chain with a small cross-platform Node script (`fs.copyFileSync`). At minimum, add a comment in `vite.config.ts` by the icon entries pointing at the `pwa:icons` rename step so the coupling is discoverable.
+
+## Info
+
+### IN-01: `OidcRedirect` navigates as a render-phase side effect
+
+**File:** `apps/pwa/src/App.tsx:77-80`
+**Issue:** `OidcRedirect` calls `window.location.replace('/api/login')` directly in the function body (render phase). React may render a component more than once (StrictMode double-invoke in dev, concurrent re-renders); side effects in render are an anti-pattern. It works because `replace` is idempotent and the page unloads, but it is fragile.
+**Fix:** Move the navigation into `useEffect(() => { window.location.replace('/api/login'); }, [])` and render the placeholder.
+
+### IN-02: Inconsistent `exhaustive-deps` disables across sibling dialogs
+
+**File:** `apps/pwa/src/components/CredentialSheet.tsx:95`, `apps/pwa/src/components/SettingsSheet.tsx:605`
+**Issue:** The Escape `useEffect` disables `react-hooks/exhaustive-deps` (because `handleClose` is referenced but not listed), while the `LinkOidcSheet`/`ResetPasswordSheet` versions list `[isOpen, onClose]` with no disable. The blanket disable also hides any future missing dep added to that effect.
+**Fix:** Wrap `handleClose` in `useCallback` and add it to the dep array, removing the disable; make the pattern consistent across all sheets.
+
+### IN-03: `isPhone`/`phone` 767px check duplicated across ~6 sites
+
+**File:** `apps/pwa/src/App.tsx:64-66`, `CalendarShell.tsx:74-76`, `SettingsSheet.tsx:135`, `CredentialSheet.tsx:156`, `AdminPage.tsx:59`, `1378-1379`
+**Issue:** The same breakpoint check is reimplemented in two spellings (`isPhone()` helper vs inline `matchMedia`), and the JS hard-codes `767` while `tokens.css` declares `--bp-tablet: 768px`. Drift risk if the breakpoint changes.
+**Fix:** Extract one `useIsPhone()` hook (ideally the resize-aware one from WR-05) and import it everywhere; reference the breakpoint in a single place.
+
+### IN-04: Dead placeholder brand tokens retained
+
+**File:** `apps/pwa/src/styles/tokens.css:103-104,107`
+**Issue:** `--brand-logo-bg`, `--brand-logo-text`, and `--brand-app-name` are leftovers from the Phase 19 "FS initials circle." BrandSlot now renders `logo.svg` and reads only `--brand-logo-size`/`--brand-logo-border-radius`; `--brand-app-name` is commented "drives doc only — not used as CSS content." These are dead declarations.
+**Fix:** Remove them, or add a comment that they're retained intentionally for a planned fallback.
+
+### IN-05: Admin members-panel JSX has inconsistent indentation / stacked bottom margins
+
+**File:** `apps/pwa/src/routes/AdminPage.tsx:364-418`
+**Issue:** Inside `admin-panel-members`, `` and its children are indented inconsistently (section at one level, children shallower), and both the Members and Local Accounts sections carry `marginBottom: var(--space-8)`, adding trailing space at the panel boundary. Cosmetic, but will trip future edits.
+**Fix:** Reformat the panel JSX — Prettier should normalize it. Confirm `pnpm --filter @familysync/pwa lint`/format was run (a recurring pre-push gate on this project).
+
+### IN-06: Toast and dialog `zIndex` overlap (300/301)
+
+**File:** `apps/pwa/src/routes/AdminPage.tsx:1033` (toast 300) vs `CredentialSheet.tsx:169,189` (backdrop 300 / sheet 301), ResetPasswordSheet (300/301)
+**Issue:** The toast shares `zIndex: 300` with the sheet backdrops. If a toast lingers while a sheet opens within the 3s window, paint order becomes DOM-order-dependent and the toast can render under the backdrop dim. Low likelihood, but the z-index scale is not cleanly layered.
+**Fix:** Put the toast above dialogs (e.g. `zIndex: 400`) and document a named z-index scale (backdrop/sheet/toast) in `tokens.css`.
+
+### IN-07: `Intl.DateTimeFormat()` recomputed every render in the calendar-config path
+
+**File:** `apps/pwa/src/components/CalendarShell.tsx:159`, `apps/pwa/src/routes/AdminPage.tsx:146`
+**Issue:** `Intl.DateTimeFormat().resolvedOptions().timeZone` is called inline in render. Cheap, but in `CalendarShell` it feeds `useCalendarApp` config, whose stability the file's own comments warn about. (Flagged as a note, not a perf-scope item, because it touches the calendar-app config the code explicitly tries to keep stable.)
+**Fix:** `const displayTimeZone = useMemo(() => Intl.DateTimeFormat().resolvedOptions().timeZone, [])`.
+
+---
+
+_Reviewed: 2026-06-18T00:00:00Z_
+_Reviewer: Claude (gsd-code-reviewer)_
+_Depth: deep_
diff --git a/.planning/phases/17-ui-optimization-polish/17-REVIEW.iter3.md b/.planning/phases/17-ui-optimization-polish/17-REVIEW.iter3.md
new file mode 100644
index 0000000..70cf986
--- /dev/null
+++ b/.planning/phases/17-ui-optimization-polish/17-REVIEW.iter3.md
@@ -0,0 +1,95 @@
+---
+phase: 17-ui-optimization-polish
+reviewed: 2026-06-18T00:00:00Z
+depth: deep
+files_reviewed: 16
+files_reviewed_list:
+ - apps/pwa/e2e/admin.spec.ts
+ - apps/pwa/e2e/layout.spec.ts
+ - apps/pwa/index.html
+ - apps/pwa/package.json
+ - apps/pwa/pwa-assets.config.ts
+ - apps/pwa/scripts/copy-pwa-icons.mjs
+ - apps/pwa/src/App.tsx
+ - apps/pwa/src/components/BrandSlot.tsx
+ - apps/pwa/src/components/CalendarShell.tsx
+ - apps/pwa/src/components/CredentialSheet.tsx
+ - apps/pwa/src/components/SettingsSheet.tsx
+ - apps/pwa/src/hooks/useFocusTrap.ts
+ - apps/pwa/src/hooks/useIsPhone.ts
+ - apps/pwa/src/routes/AdminPage.tsx
+ - apps/pwa/src/styles/tokens.css
+ - apps/pwa/vite.config.ts
+findings:
+ critical: 0
+ warning: 1
+ info: 3
+ total: 4
+status: issues_found
+---
+
+# Phase 17: Code Review Report (Re-Review After Auto-Fix)
+
+**Reviewed:** 2026-06-18T00:00:00Z
+**Depth:** deep
+**Files Reviewed:** 16
+**Status:** issues_found
+
+## Summary
+
+This is a re-review of Phase 17 (UI optimization/polish) after auto-fixes were applied to the prior 15 findings (8 warnings, 7 info). I re-read every listed file at deep depth, traced the just-changed code (focus-trap wiring across the 5 sheets, the new `useIsPhone`/`useFocusTrap` hooks, admin tab keyboard handling, the toast re-announce/wrapping changes, the timezone combobox active-index/Tab-commit logic, and the cross-platform icon-copy script), and confirmed the fixes against the surrounding call sites for regressions.
+
+**All 8 prior warnings and all 7 prior info items are correctly resolved.** Both local gates pass clean: `pnpm --filter @familysync/pwa typecheck` (tsc + e2e tsconfig) and `pnpm --filter @familysync/pwa lint` (eslint `--max-warnings 0`) both succeed with no output. I found **no BLOCKERs** and **no regressions** introduced by the fixes.
+
+What the fixes got right and why they don't regress:
+- **Focus trap** (`useFocusTrap`) is wired into all five dialogs. The child sheets (`ChangePasswordSheet`/`LinkOidcSheet`) are rendered as DOM **siblings** of the `SettingsSheet` dialog div (after the ` ` at SettingsSheet.tsx:563), not descendants, so the parent trap's `querySelectorAll` cannot capture child-sheet focusables and there is no double-trap conflict — each sheet owns its own trap.
+- **Combobox desync** is genuinely fixed: `tzActiveIndexClamped` now drives the visual highlight (AdminPage.tsx:955), `aria-activedescendant` (:838), and the Enter/Tab commit (:879/:887) from one clamped source. `aria-selected` correctly stays bound to `effectiveTimezoneInput` (:961) — that is the right ARIA distinction (selected value vs. active option), not a residual bug.
+- **Tab-to-commit** commits the clamped option without `preventDefault`, the blur timer is now `setTimeout(…, 0)` and is cleared on focus, on select, and on unmount (AdminPage.tsx:115-119) — no setState-after-unmount path remains.
+- **Toast** is keyed on a unique `{id, msg}` so identical repeats remount and `aria-live` re-announces; `whiteSpace: nowrap` is removed so it wraps within `maxWidth: 90vw` (no Rule 2 overflow hazard); z-index raised to 400, above all sheet backdrops (max 303), resolving the prior overlap.
+- **`useIsPhone`/`useMediaQuery`** subscribe via `addEventListener('change', …)` and are now used at every former inline `matchMedia` site (App, CalendarShell, all sheets, AdminPage), so iPad rotation across 767px reflows correctly. SSR guard returns `false` cleanly.
+
+The one remaining WARNING is a pre-existing focus-trap robustness gap (not introduced this phase, but now load-bearing because `aria-modal` promises containment). The three INFO items are minor and non-blocking.
+
+## Warnings
+
+### WR-01: `useFocusTrap` only wraps at the boundaries — focus can still escape via hidden/zero-size focusables
+
+**File:** `apps/pwa/src/hooks/useFocusTrap.ts:25-48`
+**Issue:** The trap queries `button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])` and filters only `!disabled` and `tabindex !== '-1'`. It does not exclude elements that are `display:none`, `visibility:hidden`, `hidden`, or zero-size. In the current sheets every focusable is visible, so the trap works today. But the pattern has two latent escape paths: (1) if a dialog ever conditionally renders a focusable inside a `hidden`/collapsed block, that element joins the `first`/`last` computation and the wrap math targets an unfocusable node — `last.focus()` becomes a no-op and Tab leaks to background content (which `aria-modal="true"` asserts is impossible); (2) the trap only intervenes at the exact first/last boundary, so it relies on the browser's natural Tab order between them being correct and contained. This is the kind of half-implemented trap the prior WR-01 set out to eliminate; the fix is correct for the present DOM but fragile for future edits.
+**Fix:** Filter to genuinely focusable, rendered elements before computing first/last, e.g.:
+```ts
+.filter((el) => {
+ if (el.hasAttribute('disabled') || el.getAttribute('tabindex') === '-1') return false;
+ if (el.hasAttribute('hidden') || (el as HTMLElement).offsetParent === null) return false;
+ const r = el.getBoundingClientRect();
+ return r.width > 0 && r.height > 0;
+});
+```
+Alternatively, document that all dialog focusables must be unconditionally rendered and visible while the dialog is open.
+
+## Info
+
+### IN-01: Focus trap does not pull focus back when `activeElement` is already outside the dialog
+
+**File:** `apps/pwa/src/hooks/useFocusTrap.ts:36-47`
+**Issue:** The handler wraps only when `document.activeElement === first` (Shift+Tab) or `=== last` (Tab). Each sheet focuses its heading/close button on open, so the trap engages from inside. But `aria-modal="true"` does not actually prevent the background DOM (still mounted behind the backdrop) from receiving focus — e.g. a programmatic focus, or a browser quirk, could land focus outside the dialog, and then neither boundary condition matches, so Tab moves through background content until it happens to re-enter. This is the residual weakness of a boundary-only trap versus a containment trap (which checks `dialogRef.current.contains(document.activeElement)` and redirects when false). Low likelihood given the open-focus behavior; noted for completeness.
+**Fix:** Add a containment guard: if `!dialogRef.current.contains(document.activeElement)` on Tab, `preventDefault()` and focus `first`.
+
+### IN-02: `favicon.ico` is referenced by `index.html` but not produced by `pwa:icons`
+
+**File:** `apps/pwa/index.html:7`, `apps/pwa/scripts/copy-pwa-icons.mjs:21-27`
+**Issue:** `index.html` links `/favicon.ico`, and the file is committed in `public/` (967 bytes). The new `copy-pwa-icons.mjs` `COPIES` table generates `favicon.svg` (from `logo.svg`) and the PNGs, but the `minimal2023Preset` does not emit a `.ico`, so `favicon.ico` is hand-maintained outside the script. This is the same invisible-coupling class the prior WR-08 flagged, just narrowed: regenerating icons leaves `favicon.ico` stale relative to a new brand mark, with nothing to catch it. The script's own header says "Keep COPIES in sync with the manifest," but the `.ico` link in `index.html` has no such pointer.
+**Fix:** Either drop the `favicon.ico` link (the SVG favicon + `sizes="any"` covers modern browsers) or add a comment in `copy-pwa-icons.mjs`/`index.html` noting `favicon.ico` is hand-maintained and must be regenerated manually when the brand mark changes.
+
+### IN-03: `OidcRedirect` placeholder renders an empty `aria-hidden` div for a full render cycle
+
+**File:** `apps/pwa/src/App.tsx:74-82`
+**Issue:** The prior IN-01 fix correctly moved the navigation into `useEffect`. The component now renders `` and the redirect fires post-commit. For the OIDC-only-mode unauthenticated path this means a brief blank frame before `window.location.replace('/api/login')` unloads the page. Functionally fine and a strict improvement over the render-phase side effect, but the blank `aria-hidden` div gives screen-reader/keyboard users no "redirecting…" affordance during the gap.
+**Fix:** Render a minimal visible "Redirecting to sign in…" status (e.g. `role="status"`) instead of an empty `aria-hidden` div, so the transition is perceivable if the redirect is slow.
+
+---
+
+_Reviewed: 2026-06-18T00:00:00Z_
+_Reviewer: Claude (gsd-code-reviewer)_
+_Depth: deep_
+_Re-review: prior 15 findings all confirmed resolved; gates (typecheck + lint) pass clean_
diff --git a/.planning/phases/17-ui-optimization-polish/17-REVIEW.md b/.planning/phases/17-ui-optimization-polish/17-REVIEW.md
new file mode 100644
index 0000000..0a895d6
--- /dev/null
+++ b/.planning/phases/17-ui-optimization-polish/17-REVIEW.md
@@ -0,0 +1,128 @@
+---
+phase: 17-ui-optimization-polish
+reviewed: 2026-06-18T00:00:00Z
+depth: deep
+files_reviewed: 16
+files_reviewed_list:
+ - apps/pwa/e2e/admin.spec.ts
+ - apps/pwa/e2e/layout.spec.ts
+ - apps/pwa/index.html
+ - apps/pwa/package.json
+ - apps/pwa/pwa-assets.config.ts
+ - apps/pwa/scripts/copy-pwa-icons.mjs
+ - apps/pwa/src/App.tsx
+ - apps/pwa/src/components/BrandSlot.tsx
+ - apps/pwa/src/components/CalendarShell.tsx
+ - apps/pwa/src/components/CredentialSheet.tsx
+ - apps/pwa/src/components/SettingsSheet.tsx
+ - apps/pwa/src/hooks/useFocusTrap.ts
+ - apps/pwa/src/hooks/useIsPhone.ts
+ - apps/pwa/src/routes/AdminPage.tsx
+ - apps/pwa/src/styles/tokens.css
+ - apps/pwa/vite.config.ts
+findings:
+ critical: 1
+ warning: 0
+ info: 1
+ total: 2
+status: issues_found
+---
+
+# Phase 17: Code Review Report (Final Re-Review After Iter-3 Auto-Fixes)
+
+**Reviewed:** 2026-06-18T00:00:00Z
+**Depth:** deep
+**Files Reviewed:** 16
+**Status:** issues_found
+
+## Summary
+
+This is the final re-review of Phase 17 after the second round of auto-fixes, which targeted the three iter-3 findings:
+
+- **WR-01** — `useFocusTrap` hidden/zero-size focusable exclusion + containment guard.
+- **IN-03** — `App.tsx` `OidcRedirect` now renders a visible "Redirecting to sign in…" status.
+- **IN-02** — favicon.ico hand-maintained coupling documented in `copy-pwa-icons.mjs` and `index.html`.
+
+I re-read every listed file at deep depth and traced the changed code against its call sites and the existing test suite.
+
+**Two of the three fixes are correct and regression-free:**
+- **IN-03 (OidcRedirect):** Correct. The navigation stays in `useEffect` (no render-phase side effect), and the placeholder is now a perceivable `role="status"` "Redirecting to sign in…" (App.tsx:83-97). No regression.
+- **IN-02 (favicon.ico coupling):** Correct and complete. Both `copy-pwa-icons.mjs` (lines 13-17) and `index.html` (line 7) now carry the hand-maintained-`.ico` pointer. Verified on disk: `favicon.svg` is byte-identical to `logo.svg` (produced by the `COPIES` table), and `favicon.ico` (967 B) is committed separately. The invisible coupling is now documented at both ends.
+
+**The WR-01 fix introduces a CR-tier regression.** The new visibility filter in `useFocusTrap.ts` (lines 36-38) relies on `offsetParent` and `getBoundingClientRect()` width/height. Both are `null`/`0` under jsdom — the environment the existing focus-trap unit tests run in — so the filter now excludes **every** focusable, `focusable.length === 0` short-circuits, and the trap silently stops wrapping focus. This breaks the two pre-existing `EventForm.test.tsx` WR-07 tests and makes `pnpm test` (a CI gate per CLAUDE.md) fail.
+
+Gate status after the fixes:
+- `pnpm --filter @familysync/pwa typecheck` → **pass** (tsc + e2e tsconfig).
+- `pnpm --filter @familysync/pwa lint` → **pass** (eslint `--max-warnings 0`).
+- `pnpm --filter @familysync/pwa test` (vitest) → **FAIL**: 2 failed / 264 passed / 266 total. Both failures are the WR-07 focus-trap tests, caused directly by the WR-01 change under review.
+
+The IN-01 containment guard added alongside WR-01 is functionally inert (the handler is only wired to the dialog's `onKeyDown`, which cannot fire when focus is outside the dialog), but it is harmless — recorded as INFO.
+
+## Critical Issues
+
+### CR-01: `useFocusTrap` visibility filter excludes all focusables under jsdom — breaks the focus-trap test suite (CI gate fails)
+
+**File:** `apps/pwa/src/hooks/useFocusTrap.ts:36-38`
+**Issue:** The WR-01 fix added a "rendered/visible" filter to the focusable query:
+```ts
+if (el.hasAttribute('hidden') || el.offsetParent === null) return false;
+const r = el.getBoundingClientRect();
+return r.width > 0 && r.height > 0;
+```
+In a real browser this is correct. But the existing focus-trap regression tests (`apps/pwa/src/components/EventForm.test.tsx`, the two `WR-07` cases at lines 718-764) run under **jsdom**, where:
+- `getBoundingClientRect()` returns all-zero geometry for every element (`width === 0`, `height === 0`), and
+- `offsetParent` is `null` for every element.
+
+Either condition alone causes the filter to reject **every** focusable. `focusable.length` becomes `0`, the handler hits the `if (focusable.length === 0) return;` early-out (line 41), and Tab/Shift+Tab no longer wrap. Both WR-07 tests now fail:
+
+```
+FAIL src/components/EventForm.test.tsx > WR-07: Tab from last focusable element wraps focus to first inside dialog
+FAIL src/components/EventForm.test.tsx > WR-07: Shift+Tab from first focusable element wraps focus to last inside dialog
+Test Files 1 failed | 21 passed (22)
+ Tests 2 failed | 264 passed (266)
+```
+
+`pnpm test` (→ `vitest run`) is one of the CI gates the project requires to pass before push (CLAUDE.md "Frustrations" directive + the CI-checks-conformance memory). This regression ships as part of the file under review, so it is in scope even though `EventForm.test.tsx` is not in the listed-files set — those tests exist specifically to guard the changed behavior.
+
+**Fix:** Make the visibility filter tolerant of a non-layout (jsdom) environment, so it excludes genuinely hidden nodes in a browser without nuking all nodes in tests. Treat zero-geometry as "visible" when no layout engine is present, and gate on `offsetParent` only when geometry is meaningful:
+```ts
+.filter((el) => {
+ if (el.hasAttribute('disabled') || el.getAttribute('tabindex') === '-1') return false;
+ if (el.hasAttribute('hidden')) return false;
+ // jsdom has no layout: getBoundingClientRect() is all-zero and offsetParent is
+ // null for every node. Only apply the visibility heuristic when a real layout
+ // exists, so unit tests still see focusables.
+ const r = el.getBoundingClientRect();
+ const hasLayout = r.width > 0 || r.height > 0 || el.offsetParent !== null;
+ if (!hasLayout) return true; // no layout engine → don't filter on visibility
+ if (el.offsetParent === null) return false;
+ return r.width > 0 && r.height > 0;
+});
+```
+Alternatively, stub `getBoundingClientRect`/`offsetParent` in the test setup so jsdom reports non-zero geometry — but the production-side guard above is the safer minimal change, since other future tests will hit the same wall. Either way, re-run `pnpm --filter @familysync/pwa test` and confirm both WR-07 cases pass before considering this resolved.
+
+## Info
+
+### IN-01: Focus-trap containment guard is unreachable as wired (harmless dead branch)
+
+**File:** `apps/pwa/src/hooks/useFocusTrap.ts:50-54`
+**Issue:** The IN-01 fix added a containment guard:
+```ts
+if (!dialogRef.current.contains(document.activeElement)) {
+ e.preventDefault();
+ first.focus();
+ return;
+}
+```
+The comment claims this catches the case where "focus has somehow landed outside the dialog ... Tab would walk background content." But the handler is only attached to each dialog container's `onKeyDown` (verified across all 5 sheets + EventForm + SeriesEditPrompt — no `document`-level listener exists). React's synthetic `onKeyDown` on the dialog div only fires when the keydown event's target is **inside** the dialog subtree (the event must bubble up through that div). When `document.activeElement` is genuinely outside the dialog, the keydown fires on that outside element and bubbles through `document`, **not** through the dialog div — so `handleDialogKeyDown` never runs, and `dialogRef.current.contains(document.activeElement)` is effectively always `true` whenever this code executes. The guard is therefore a no-op in practice: it does not deliver the containment guarantee its comment promises.
+
+This is not a correctness bug (it never produces wrong behavior), so it is INFO, not a blocker. But it is worth noting that the IN-01 concern (focus escaping a boundary-only trap) is **not actually addressed** by this change.
+
+**Fix:** If true containment is desired, move the trap to a `document`-level `keydown` (or `focusin`) listener mounted while the dialog is open, so it can intercept Tab/focus originating outside the dialog. If the boundary-only trap is considered sufficient (it is, for the present always-focus-the-heading-on-open flows), drop the unreachable containment branch and its comment to avoid implying a guarantee the code does not provide.
+
+---
+
+_Reviewed: 2026-06-18T00:00:00Z_
+_Reviewer: Claude (gsd-code-reviewer)_
+_Depth: deep_
+_Re-review: IN-02 + IN-03 fixes confirmed clean; WR-01 fix regresses the focus-trap test suite (CR-01) and its IN-01 containment guard is inert. typecheck + lint pass; `pnpm test` FAILS (2 WR-07 tests)._
diff --git a/.planning/phases/17-ui-optimization-polish/17-SECURITY.md b/.planning/phases/17-ui-optimization-polish/17-SECURITY.md
new file mode 100644
index 0000000..eefcfe0
--- /dev/null
+++ b/.planning/phases/17-ui-optimization-polish/17-SECURITY.md
@@ -0,0 +1,92 @@
+---
+phase: 17
+slug: ui-optimization-polish
+status: verified
+threats_open: 0
+asvs_level: 1
+created: 2026-06-18
+---
+
+# Phase 17 — Security
+
+> Per-phase security contract: threat register, accepted risks, and audit trail.
+
+Phase 17 is a UI optimization & polish phase. Every plan carried a plan-time
+`` block (`register_authored_at_plan_time: true`). The work is
+client-side CSS/layout, static brand-asset wiring, and presentation-only React
+state — no new endpoints, no new authorization logic, no new runtime data flow.
+The single non-`accept` threat (logout wiring) reuses an endpoint already
+verified live in Phase 19.
+
+---
+
+## Trust Boundaries
+
+| Boundary | Description | Data Crossing |
+|----------|-------------|---------------|
+| Build tooling → repo (17-02) | `@vite-pwa/assets-generator` (+ sharp, sharp-ico) runs at design time and writes static images into `public/`. New devDependency = supply-chain surface. | Static image bytes; no secrets/PII |
+| Client UI → existing logout endpoint (17-05) | Sign out control calls the already-implemented, Phase-19-verified `POST /api/auth/local/logout` via `fetchLocalLogout()`. No new endpoint, no new auth logic. | Session cookie (cleared server-side) |
+| (none new) — 17-01, 17-03, 17-04, 17-06 | CSS-only restructure/offsets, static asset references, and presentation-only local `useState` (tab/toast). Server-side admin `403` enforcement unchanged. | None |
+
+---
+
+## Threat Register
+
+| Threat ID | Category | Component | Disposition | Mitigation | Status |
+|-----------|----------|-----------|-------------|------------|--------|
+| T-17-01-01 | Tampering | tokens.css selector restructure | accept | CSS custom properties carry no executable content and no user input; selector change cannot introduce injection. | closed |
+| T-17-02-SC | Tampering | npm devDependency install (@vite-pwa/assets-generator, sharp, sharp-ico) | accept | RESEARCH Package Legitimacy Audit rates all three Approved (official vite-pwa, 13-yr sharp, sharp-ico); no `[SLOP]`/unverified packages. devDependencies only; generated output is static images. | closed |
+| T-17-02-02 | Information disclosure | generated brand assets | accept | Assets are public-by-design brand images; no secrets or PII. | closed |
+| T-17-03-01 | Tampering | FAB/content CSS offsets | accept | Pure layout geometry via existing CSS custom property; no executable content, no input. | closed |
+| T-17-04-01 | Tampering | BrandSlot img / index.html links | accept | Logo img is decorative with empty `alt`; no `dangerouslySetInnerHTML` (T-05-24 invariant maintained); favicon/manifest entries point at committed static files. **Verified live:** BrandSlot renders ``, no `dangerouslySetInnerHTML` in source. | closed |
+| T-17-05-01 | Elevation of Privilege | logout control (D-07) | mitigate | `fetchLocalLogout()` clears the local-session cookie via the existing Phase-19-verified endpoint; client navigates to `/login` regardless of success/failure so a stale-cookie-with-logged-out-UI state cannot persist. **Verified:** `SettingsSheet.tsx:143-151` — `try { await fetchLocalLogout(); } catch {} onClose(); void navigate('/login');`. | closed |
+| T-17-05-02 | Tampering | sheet centering CSS (D-09) | accept | Position-only CSS branch; no input, no executable content. | closed |
+| T-17-06-01 | Tampering | toast message content (D-08) | accept | Toast copy is hardcoded JSX string constants ("Member added." / "Password reset."); no user-controlled content; no `dangerouslySetInnerHTML`. **Verified live:** toast rendered "Member added." from a `role=status` node on member creation. | closed |
+| T-17-06-02 | Elevation of Privilege | admin two-tab nav (D-10) | accept | Tab strip is presentation-only local `useState`; `isAdmin` nav visibility is UX-only — the real boundary is server-side `403` on `/api/admin/*` (unchanged). | closed |
+
+*Status: open · closed*
+*Disposition: mitigate (implementation required) · accept (documented risk) · transfer (third-party)*
+
+---
+
+## Accepted Risks Log
+
+| Risk ID | Threat Ref | Rationale | Accepted By | Date |
+|---------|------------|-----------|-------------|------|
+| AR-17-01 | T-17-01-01 | Static stylesheet selector restructure; zero runtime data flow. | Lucas Berger | 2026-06-18 |
+| AR-17-02 | T-17-02-SC | All new devDependencies Approved by RESEARCH package-legitimacy audit; design-time only. | Lucas Berger | 2026-06-18 |
+| AR-17-03 | T-17-02-02 | Brand assets are public-by-design; no secrets/PII. | Lucas Berger | 2026-06-18 |
+| AR-17-04 | T-17-03-01 | Pure CSS layout geometry; no input surface. | Lucas Berger | 2026-06-18 |
+| AR-17-05 | T-17-04-01 | Decorative img with empty alt; no `dangerouslySetInnerHTML`; committed static assets. | Lucas Berger | 2026-06-18 |
+| AR-17-06 | T-17-05-02 | Position-only CSS branch; no input/executable content. | Lucas Berger | 2026-06-18 |
+| AR-17-07 | T-17-06-01 | Hardcoded toast string constants; no user-controlled content. | Lucas Berger | 2026-06-18 |
+| AR-17-08 | T-17-06-02 | Presentation-only tab state; authorization enforced server-side (unchanged). | Lucas Berger | 2026-06-18 |
+
+*Accepted risks do not resurface in future audit runs.*
+
+---
+
+## Security Audit Trail
+
+| Audit Date | Threats Total | Closed | Open | Run By |
+|------------|---------------|--------|------|--------|
+| 2026-06-18 | 9 | 9 | 0 | /gsd-secure-phase (orchestrator, plan-time register verification) |
+
+Verification method: all 6 plans carried plan-time `` blocks
+(`register_authored_at_plan_time: true`). 8 `accept`-disposition threats are
+documented accepted risks; the 1 `mitigate` threat (T-17-05-01) had its
+mitigation verified present in `SettingsSheet.tsx`. Several dispositions were
+additionally corroborated at runtime during the Phase 17 UAT (playwright-cli):
+BrandSlot decorative img, hardcoded success toast, admin tab presentation-only
+state. `threats_open: 0` — short-circuit per workflow Step 3.
+
+---
+
+## Sign-Off
+
+- [x] All threats have a disposition (mitigate / accept / transfer)
+- [x] Accepted risks documented in Accepted Risks Log
+- [x] `threats_open: 0` confirmed
+- [x] `status: verified` set in frontmatter
+
+**Approval:** verified 2026-06-18
diff --git a/.planning/phases/17-ui-optimization-polish/17-UAT.md b/.planning/phases/17-ui-optimization-polish/17-UAT.md
new file mode 100644
index 0000000..3a7d887
--- /dev/null
+++ b/.planning/phases/17-ui-optimization-polish/17-UAT.md
@@ -0,0 +1,82 @@
+---
+status: complete
+phase: 17-ui-optimization-polish
+source:
+ - 17-01-SUMMARY.md
+ - 17-02-SUMMARY.md
+ - 17-03-SUMMARY.md
+ - 17-04-SUMMARY.md
+ - 17-05-SUMMARY.md
+ - 17-06-SUMMARY.md
+verification_method: playwright-cli (Chromium, host Vite @5173, Docker API/DB)
+started: 2026-06-18T18:26:00Z
+updated: 2026-06-18T18:31:00Z
+---
+
+## Current Test
+
+[testing complete]
+
+## Tests
+
+### 1. Cold Start Smoke Test
+expected: App boots and `/calendar` loads with live data — calendar grid, color legend, and primary controls render without console errors.
+result: pass
+evidence: PWA opened at http://localhost:5173/ → redirected to /calendar (dev-bypass). June 2026 grid rendered, color legend ("Dev User" #4A90D9, "Family" #F25C7A), New Event button + Today/nav present. 0 console errors. Docker API/MariaDB/Redis up.
+
+### 2. Login Page Branding — FamilySync logo (Plan 17-04)
+expected: Login page shows the approved family-house logo (BrandSlot), not the old "FS" text placeholder.
+result: pass
+evidence: /login renders `` at 48px. Old `aria-hidden` "FS" placeholder div is absent. `/logo.svg` serves 200 image/svg+xml.
+
+### 3. Favicon & Theme Color (Plan 17-04)
+expected: Browser tab favicon set (SVG + ICO + apple-touch) wired; warm-amber theme color applied.
+result: pass
+evidence: `` for /favicon.svg (image/svg+xml) + /favicon.ico + apple-touch-icon present. All of favicon.svg/favicon.ico/apple-touch-icon.png/icon-maskable-512.png fetch 200 with correct content-types. `` = #e8915a.
+
+### 4. Phone Layout Overlap Fix (Plan 17-03 / D-01)
+expected: At ≤767px, the New Event FAB sits above the fixed BottomTabBar (not occluded) and the color-legend chips remain fully visible.
+result: pass
+evidence: @390×844 — FAB bottom=764, BottomTabBar top=788 → FAB above bar with 24px gap (= --space-6). Color legend bottom=780 < nav top=788, visible:true, not occluded. Both chips ("Dev User", "Family") present. 0 console errors.
+
+### 5. Sign Out Control (Plan 17-05 / D-07)
+expected: Settings sheet exposes a reachable "Sign out" control.
+result: pass
+evidence: Settings dialog (opened from "Dev User — open settings") contains Account section, "Change password", and a "Sign out" button — all reachable.
+
+### 6. Settings Sheet Centering (Plan 17-05 / D-09)
+expected: On desktop, the settings sheet renders as a centered modal (not a bottom sheet).
+result: pass
+evidence: Settings dialog — position:fixed, width 480px, horizontal & vertical center offset = 0 on 1280×720, aria-modal="true".
+
+### 7. Modal Focus Trap (code-review CR-01 / WR-01 fix)
+expected: With a sheet open, Tab/Shift+Tab cycle focus within the dialog and never escape to background controls.
+result: pass
+evidence: Settings dialog (5 focusables). Tab from last ("Sign out") → wraps to "Close settings" (still inside). Shift+Tab from first → wraps to "Sign out" (still inside). Focus stayed contained both directions. Confirms the jsdom-tolerant visibility filter works correctly in a real (laid-out) browser — resolves the code-review human-verification flag.
+
+### 8. Admin Two-Tab Navigation (Plan 17-06 / D-10 + WR-02)
+expected: Admin page shows "Members & Accounts" / "Settings" tabs with full WAI-ARIA keyboard support (arrows wrap, Home/End).
+result: pass
+evidence: `role=tablist` with two `role=tab`s, "Members & Accounts" selected by default, tabpanels with regions. Keyboard: ArrowRight→Settings, ArrowRight wraps→Members, ArrowLeft→Settings, Home→Members, End→Settings. All transitions update aria-selected.
+
+### 9. Admin Success Toast (Plan 17-06 / D-08)
+expected: Creating a member shows a transient success toast announced to assistive tech.
+result: pass
+evidence: Filled + submitted the Add-member form (throwaway "ZZ Verify Toast"); a `role=status` aria-live="polite" toast read "Member added." Throwaway member removed from the dev DB afterward (verified 0 remaining).
+
+### 10. iOS Standalone PWA — install + home-screen icon + push
+expected: Installed-to-home-screen behavior and apple-touch/maskable icon appearance on a real iOS device.
+result: skipped
+reason: Genuinely device-only — cannot be driven by playwright-cli/Chromium (manifest is production-only and not injected in Vite dev). Icon assets and manifest config are verified at the asset/code level (Tests 2–3, code review). Real-device behavior remains a human checkpoint, already tracked in 17-VERIFICATION.md.
+
+## Summary
+
+total: 10
+passed: 9
+issues: 0
+skipped: 1
+pending: 0
+
+## Gaps
+
+[none — all automated checks passed; 1 device-only item deferred to existing human checkpoints]
diff --git a/.planning/phases/17-ui-optimization-polish/17-UI-SPEC.md b/.planning/phases/17-ui-optimization-polish/17-UI-SPEC.md
new file mode 100644
index 0000000..a636d2a
--- /dev/null
+++ b/.planning/phases/17-ui-optimization-polish/17-UI-SPEC.md
@@ -0,0 +1,851 @@
+---
+phase: 17
+slug: ui-optimization-polish
+status: draft
+shadcn_initialized: false
+preset: none
+created: 2026-06-18
+---
+
+# Phase 17 — UI Design Contract: UI Optimization & Polish
+
+> Visual and interaction contract for four bounded workstreams:
+> A — phone-layout overlap fix + small-viewport sweep,
+> B — branding assets (logo, favicon, PWA icon set),
+> C — theme-token groundwork (light-only, semantic layer),
+> D — UAT-surfaced UI fixes (logout control, admin success feedback,
+> dialog/sheet centering, admin two-tab nav).
+>
+> Generated by gsd-ui-researcher. Consume before planning or executing.
+
+---
+
+## Context & Approach
+
+This is a **polish + branding + theme-token-groundwork** phase on an **existing shipped**
+React 19 + Vite PWA. NOT greenfield, NOT a redesign. All design decisions extend the
+established token system in `apps/pwa/src/styles/tokens.css`.
+
+The no-hard-coded-values invariant is a hard constraint: **all hex/px values live in
+`tokens.css` as CSS custom properties; component files reference variables only.**
+
+The existing Phase 19 UI-SPEC (approved 2026-06-16) establishes the design-system
+baseline this phase builds on. No new tokens are introduced except the layout-chrome
+token added in Workstream A.
+
+---
+
+## Design System
+
+| Property | Value |
+|----------|-------|
+| Tool | none (existing CSS custom properties) |
+| Preset | not applicable |
+| Component library | none (hand-rolled inline `React.CSSProperties`, project convention) |
+| Icon library | lucide-react (already installed) |
+| Font | system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif (`var(--font-family-base)`) |
+
+Source: `apps/pwa/src/styles/tokens.css` — pre-populated from codebase scan.
+Pattern baseline: existing components (SettingsSheet, AdminPage, CredentialSheet, CalendarShell).
+
+---
+
+## Spacing Scale
+
+No new spacing tokens are introduced. Phase 17 uses the existing 4px-based scale unchanged.
+
+| Token | Value | Usage in this phase |
+|-------|-------|---------------------|
+| --space-1 | 4px | Icon gaps, tight label margins |
+| --space-2 | 8px | Tab strip inner gap, section label bottom margin |
+| --space-3 | 12px | Input row padding, tab content gap |
+| --space-4 | 16px | Toast horizontal padding, button padding, between-field gap |
+| --space-6 | 24px | Sheet/card padding, FAB clearance (base of calc expression) |
+| --space-8 | 32px | Section gap in admin two-tab content |
+| --space-12 | 48px | Page-level top/bottom padding |
+
+**New layout-chrome token (Workstream A):**
+
+```css
+/* Added to tokens.css :root alongside existing spacing scale */
+--bottom-chrome-h: calc(56px + env(safe-area-inset-bottom, 0px));
+```
+
+This single token is the source of truth for BottomTabBar height. It is consumed
+by the FAB offset (`bottom: calc(var(--bottom-chrome-h) + var(--space-6))`) and the
+phone content padding (`padding-bottom: var(--bottom-chrome-h)`). All three sites
+agree via one value.
+
+Exceptions:
+- FAB: `width: 56px; height: 56px` (Rule 1 minimum: ≥56×56px per layout.spec.ts). Not a
+ spacing-scale value — this is the FAB's own intrinsic size.
+- All interactive elements: `minHeight: 44px; minWidth: 44px` (WCAG 2.5.5 Touch Target).
+- Admin two-tab strip: tab items use `minHeight: 44px` to meet touch-target minimum.
+- Dialog/sheet (centered, D-09): `maxWidth: 480px` centered via
+ `left: 50%; transform: translateX(-50%)` (desktop); phone retains full-width
+ bottom-sheet `bottom: 0; left: 0; right: 0`.
+
+---
+
+## Typography
+
+All values from `tokens.css`. No new sizes or weights.
+
+| Role | Size | Weight | Line Height | Variable |
+|------|------|--------|-------------|----------|
+| Body | 15px | 400 | 1.5 | `var(--text-body-size)` / `var(--text-body-weight)` / `var(--text-body-line-height)` |
+| Label | 13px | 400 | 1.4 | `var(--text-label-size)` / `var(--text-label-weight)` / `var(--text-label-line-height)` |
+| Heading | 18px | 600 | 1.25 | `var(--text-heading-size)` / `var(--text-heading-weight)` / `var(--text-heading-line-height)` |
+| Display | 24px | 600 | 1.2 | `var(--text-display-size)` / `var(--text-display-weight)` / `var(--text-display-line-height)` |
+
+Usage in this phase:
+- Admin two-tab strip label: Label (13px/400/1.4) — inactive state; active state weight 600
+- Toast notification body: Label (13px/400/1.4)
+- Toast notification icon: 16px lucide icon
+- Logout button label: Body (15px/400/1.5) — matches existing SettingsSheet row pattern
+- Admin section content: inherits existing AdminPage typography (no change)
+
+---
+
+## Color
+
+All values from `tokens.css`. No new hex values in this phase.
+
+| Role | Value | Variable | Usage |
+|------|-------|----------|-------|
+| Dominant (60%) | #ffffff | `var(--color-surface)` | Page background, sheet background, tab strip background |
+| Secondary (30%) | #f7f7f8 | `var(--color-surface-dim)` | Tab strip inactive background, toast background |
+| Accent (10%) | #4a90d9 | `var(--color-member-0)` | Active tab indicator, active tab label, toast success icon, logout destructive separator |
+| Destructive | #dc2626 | `var(--color-destructive)` | Logout button text color (destructive row style) |
+
+Accent (`var(--color-member-0)`) reserved for:
+- Active tab bottom-border indicator in the admin two-tab strip (2px solid)
+- Active tab label text color
+- Toast icon for success feedback
+- Focus ring on all new interactive elements (`var(--color-focus-ring)`, 2px outline, 2px offset)
+
+Additional semantic colors (already in tokens.css — no new values):
+- `var(--color-border)` #e2e4e9 — tab strip bottom border, dialog border, toast border
+- `var(--color-border-subtle)` #eceef2 — separator above logout button in SettingsSheet
+- `var(--color-text-primary)` #111318 — tab labels (active), sheet headings
+- `var(--color-text-secondary)` #6b7280 — tab labels (inactive), toast body text
+- `var(--color-text-muted)` #9ca3af — section labels (uppercase, 13px/600/0.06em letter-spacing)
+- `var(--color-overlay)` rgba(0,0,0,0.32) — sheet/dialog backdrop
+
+### Brand accent checkpoint (answered question Q1)
+
+The accent direction is a **checkpoint decision** — both variants must be producible
+and comparable. The token restructure in Workstream C makes this a single-file swap.
+
+**Variant A — keep cool-blue:**
+- No token changes: `--color-member-0: #4a90d9`, `theme-color` stays `#4A90D9`
+
+**Variant B — warm rose/amber:**
+- `--color-member-0: #f25c7a` (rose, already the `--color-shared-family` value)
+ OR a warm amber `#e8915a` — one of these two candidates to compare at the checkpoint
+- Acceptance lens: warm/rounded/at-home; contrast ratio ≥3:1 on `#ffffff` (WCAG AA for
+ large text/UI components; the current rose #f25c7a passes at 3.0:1)
+- Files that flip for Variant B: `tokens.css` (`--color-member-0`), `index.html`
+ (`theme-color` meta content), `vite.config.ts` manifest (`theme_color`)
+- Note: `--sx-color-primary` already maps to `var(--color-member-0)` — it follows
+ the accent automatically
+
+**Default if checkpoint skipped:** keep Variant A (#4a90d9).
+
+Light-theme scope only. No dark palette values authored this phase.
+
+---
+
+## Workstream A — Phone-Layout Overlap Fix
+
+### Visual invariants (hard rules — must pass on iphone + pixel profiles)
+
+1. **FAB never intersects the BottomTabBar rect.** The FAB's bottom edge must be
+ at or above the BottomTabBar's top edge. On a 390×844 viewport with `safe-area-inset=0`:
+ BottomTabBar top edge = 844 - 56 = 788px. FAB bottom edge must be ≤ 788px.
+2. **Content fully scrollable above the bar.** The phone content area's scroll-bottom
+ must clear the BottomTabBar height so no content is occluded at rest. The colour-legend
+ chips ("Dev User" / member legend) and any bottom-of-page content must be visible
+ without needing to manually offset-scroll.
+3. **Safe-area-inset composes correctly.** On notched devices, `env(safe-area-inset-bottom)`
+ is non-zero; the token `calc(56px + env(safe-area-inset-bottom, 0px))` absorbs both the
+ bar height and the notch.
+4. **No horizontal overflow** — existing Rule 2 must continue to pass after the fix.
+5. **Tap targets preserved** — all existing ≥44px/≥56px assertions in layout.spec.ts
+ must pass after the fix.
+
+### Fix contract
+
+**New token added to `tokens.css` `:root`:**
+```css
+--bottom-chrome-h: calc(56px + env(safe-area-inset-bottom, 0px));
+```
+
+**FAB offset (CalendarShell.tsx):**
+- Before: `bottom: var(--space-6)` (~24px)
+- After: `bottom: calc(var(--bottom-chrome-h) + var(--space-6))`
+- The FAB sits `var(--space-6)` (24px) above the BottomTabBar top edge regardless
+ of safe-area-inset value.
+
+**Content padding (App.tsx `contentStyle`):**
+- Phone branch only (inside `if (phone)` or via `isPhone()` conditional)
+- Add: `paddingBottom: 'var(--bottom-chrome-h)'`
+- Desktop `contentStyle` is unchanged (no BottomTabBar on desktop).
+
+**BottomTabBar height (BottomTabBar.tsx):**
+- The bar's `height` calculation already uses `calc(56px + env(safe-area-inset-bottom, 0px))`
+ inline. This remains correct and unchanged — `--bottom-chrome-h` resolves to the same
+ value so both the token and the component agree. For consistency, the planner MAY choose
+ to reference the token from the bar's height property as well, but the visual invariant
+ is met either way.
+
+### Regression guard (D-02 decision)
+
+**Recommendation: add a permanent overlap CI assertion to `layout.spec.ts`.**
+
+Evidence basis: the defect was long-standing (Phase 04 — months), was invisible to desktop
+testing, and CI has iphone/pixel profiles running. Adding a geometry assertion to the
+existing spec is the lowest-regress mechanism. The assertion has no runtime cost beyond
+one `boundingBox()` call.
+
+**Assertion contract to add to `layout.spec.ts`:**
+
+```
+test('New Event FAB does not overlap BottomTabBar (A — phone only)', async ({ page }, testInfo) => {
+ test.skip(testInfo.project.name === 'desktop', 'Phone-only assertion');
+ await page.goto('/calendar');
+ const fab = page.getByRole('button', { name: 'New Event' });
+ const nav = page.getByRole('navigation', { name: 'Main navigation' });
+ const fabBox = await fab.boundingBox();
+ const navBox = await nav.boundingBox();
+ expect(fabBox).not.toBeNull();
+ expect(navBox).not.toBeNull();
+ // FAB bottom edge must be at or above the BottomTabBar top edge
+ expect(fabBox!.y + fabBox!.height).toBeLessThanOrEqual(navBox!.y);
+});
+```
+
+Run profiles: iphone + pixel (skipped on desktop).
+
+### Small-viewport sweep (D-01)
+
+After the FAB/content-padding fix, run the full `layout.spec.ts` suite on all three
+profiles. Fix any violations flagged (per D-01: checklist-driven, within no-behaviour-change
+boundary). Expected areas to verify:
+
+- Admin tab (when isAdmin=true): ensure it still meets ≥44px tap target after layout fix
+- ColorLegend chips: confirm they are fully visible (not occluded) once content padding is added
+- Any Phase 19 additions (LoginPage, SettingsSheet rows): no overflow on phone profiles
+
+---
+
+## Workstream B — Branding Assets
+
+### Brand brief (acceptance lens)
+
+All generated assets must feel: **warm / rounded / at-home / caricature-family vibes**.
+Not corporate, not geometric. The operator reviews and approves before assets are final.
+This is a **checkpoint** — the checkpoint fires before wiring is committed.
+
+### Logo asset contract
+
+| Asset | Dimensions | Format | Filename | Purpose |
+|-------|-----------|--------|----------|---------|
+| Logo mark | 192×192px (source; scale up for 512) | SVG preferred; PNG fallback | `logo.svg` or `logo.png` | BrandSlot `![]()
` + derivation source for icon set |
+| Favicon (modern) | 32×32px (scalable) | SVG | `favicon.svg` | Browser tab icon (modern browsers) |
+| Favicon (legacy) | 16×16 + 32×32 ICO | ICO | `favicon.ico` | Browser tab icon (legacy, IE/older Safari) |
+| PWA icon 192 | 192×192px | PNG | `icon-192.png` | PWA manifest — standard purpose |
+| PWA icon 512 | 512×512px | PNG | `icon-512.png` | PWA manifest — standard purpose (splash screen) |
+| PWA maskable 512 | 512×512px | PNG | `icon-maskable-512.png` | PWA manifest — maskable purpose (separate file) |
+| Apple touch icon | 180×180px | PNG | `apple-touch-icon.png` | iOS home screen icon |
+
+All files placed in `apps/pwa/public/`.
+
+**Maskable safe-zone rule:** The maskable icon (`icon-maskable-512.png`) must place
+the logo mark entirely within the 80% safe-zone circle (radius 204px on a 512×512 canvas,
+centered). The outer 10% on each edge may be cropped by the OS adaptive-icon mask. The
+current manifest incorrectly reuses `icon-512.png` (no safe zone) for the maskable
+purpose — this is the defect being fixed.
+
+### BrandSlot swap contract (D-05)
+
+**What changes in `BrandSlot.tsx`:**
+- Replace the placeholder `` with
+ ``
+- Apply the existing `--brand-logo-*` token dimensions to the `![]()
`:
+ `width: var(--brand-logo-size, 48px)`, `height: var(--brand-logo-size, 48px)`,
+ `borderRadius: var(--brand-logo-border-radius, 50%)`, aspect-ratio: 1/1
+- The `--brand-logo-bg` token (placeholder circle background) is no longer used
+ as a background when a real `![]()
` is present — it may be set to `transparent`
+ or removed from the element's style (keep the token in `tokens.css` for forward
+ compat if needed)
+- The `` with "FamilySync" text remains unchanged (screen readers still read the
+ name; the logo is purely decorative)
+- The tagline `
` remains unchanged
+- `LoginPage` layout is NOT touched — the seam contract from Phase 19 is honored
+
+**`--brand-logo-border-radius` update:**
+- The placeholder used `50%` (circle). The real logo may be a rounded square or have
+ its own shape baked in. Phase 17 sets this token to the shape that suits the logo:
+ - If the logo SVG is a circle/rounded shape by design: set to `0` (no extra clipping)
+ - If the logo is a square mark needing rounding: set to `12px` (warm/rounded brief)
+ - Final value determined when the logo is generated and reviewed at checkpoint
+
+**No `LoginPage` changes** — this is enforced by the Phase 19 seam contract.
+
+### `index.html` wiring contract
+
+Current state: one ``, one ``,
+no ``.
+
+After Phase 17:
+
+```html
+
+
+
+
+
+
+
+
+
+
+ FamilySync
+
+```
+
+`{ACCENT_HEX}` = the checkpoint-selected accent value (`#4A90D9` default or warm variant).
+
+The SVG favicon takes precedence in modern browsers; the ICO fallback covers legacy.
+Order matters: SVG first, ICO second (browsers pick the first supported type).
+
+### `vite.config.ts` manifest wiring contract
+
+Current state: 3 icon entries, last entry incorrectly reuses `icon-512.png` for maskable.
+
+After Phase 17:
+
+```ts
+icons: [
+ { src: '/icon-192.png', sizes: '192x192', type: 'image/png' },
+ { src: '/icon-512.png', sizes: '512x512', type: 'image/png' },
+ { src: '/icon-maskable-512.png', sizes: '512x512', type: 'image/png', purpose: 'maskable' },
+],
+```
+
+The `theme_color` value in the manifest must match the `index.html` `theme-color` meta
+and the checkpoint-selected accent. Change from `'#4A90D9'` to the chosen value at checkpoint.
+
+---
+
+## Workstream C — Theme-Token Groundwork
+
+### Contract
+
+**Groundwork only.** No dark palette values, no `prefers-color-scheme` media query wired
+to flip themes, no theme toggle UI. Light is and remains the only shipped theme.
+
+**Restructure `tokens.css` `:root` into a `data-theme`-capable pattern:**
+
+```css
+/* tokens.css — after restructure */
+
+:root,
+[data-theme="light"] {
+ /* All existing :root declarations move here verbatim. */
+ /* No value changes. */
+ /* ...all existing tokens... */
+}
+
+/* Dark theme stub — values intentionally absent (Phase 17 groundwork only).
+ Phase 999.20 fills these values and wires prefers-color-scheme. */
+/* [data-theme="dark"] { ... } */
+```
+
+The change is purely structural: `:root` is extended with `[data-theme="light"]` as a
+second selector on the same rule block. This allows a future `data-theme="dark"` attribute
+on `` to override without touching component files.
+
+**Schedule-X `--sx-color-*` overrides must remain working.** They are currently at the
+bottom of the same `:root` rule — after the restructure they remain inside the same
+combined `:root, [data-theme="light"]` rule block. The cascade order (after
+`@schedule-x/theme-default`) is unchanged; the overrides continue to win.
+
+**`--brand-logo-*` tokens** remain in the same `:root, [data-theme="light"]` block.
+Phase 17's logo swap updates their values here (e.g. `--brand-logo-border-radius`).
+
+**New token added in this workstream (in addition to Workstream A's
+`--bottom-chrome-h`):**
+
+No additional tokens beyond `--bottom-chrome-h` (Workstream A) and any updated
+`--brand-logo-*` values (Workstream B). The theme restructure introduces no new
+semantic names — only the selector change.
+
+**Invariant check:** after restructure, `grep -rn 'var(--' apps/pwa/src/components/`
+must show only `var(--token-name)` references, no hard-coded hex or px values in
+component files. This is the existing invariant; the restructure must not break it.
+
+---
+
+## Workstream D — UAT-Surfaced UI Fixes
+
+### D-07 — Logout control
+
+**Surfaces:** SettingsSheet (primary) and optionally AppNav phone header (secondary).
+
+**Primary placement: SettingsSheet.**
+A "Sign out" row is added below all existing SettingsSheet content, separated by a
+`var(--color-border-subtle)` horizontal rule (same divider pattern as the existing
+Account section). This mirrors the established section-separator pattern already used
+in SettingsSheet between Notifications and Account.
+
+Layout within SettingsSheet (bottom of sheet, after all other rows):
+```
+───────────────────────── ← 1px var(--color-border-subtle) divider, margin var(--space-4) top/bottom
+[LogOut icon 16px] Sign out ← full-width button, minHeight 44px, Body 15px/400, var(--color-destructive)
+```
+
+**Logout button style:**
+- `background: none; border: none; cursor: pointer`
+- Full width (`width: 100%`), `display: flex; alignItems: center; gap: var(--space-2)`
+- `LogOut` lucide icon (16px, `var(--color-destructive)`)
+- Label "Sign out" — Body (15px/400), `var(--color-destructive)`
+- `minHeight: 44px` (WCAG tap target)
+- `textAlign: left`, `padding: var(--space-2, 8px) 0`
+- On click: calls `fetchLocalLogout()` (already exists in `apps/pwa/src/api/client.ts:127`),
+ then navigates to `/login` (react-router `useNavigate` or `window.location.replace`)
+- No confirmation dialog — logout is not destructive in the "data loss" sense for a
+ household app; the user is simply signed out and can re-sign in immediately
+
+**Accessibility:**
+- `aria-label="Sign out"` on the button
+- Icon is `aria-hidden="true"`
+- Standard focus ring (`var(--color-focus-ring)`, 2px outline, 2px offset)
+
+**No backend work required** — `fetchLocalLogout()` calls the existing
+`POST /api/auth/local/logout` endpoint.
+
+### D-08 — Admin success feedback
+
+**Surfaces:** AdminPage.tsx — create-member and reset-password flows.
+
+**Toast notification design contract:**
+
+A lightweight transient toast appears after a successful admin action. Reuses the
+existing `SyncStateToast` visual pattern (already in the codebase) if possible; if not,
+implement a minimal inline variant.
+
+Toast style:
+- Position: `fixed; bottom: calc(var(--bottom-chrome-h) + var(--space-4))` on phone;
+ `fixed; bottom: var(--space-6); left: 50%; transform: translateX(-50%)` on desktop
+- Background: `var(--color-surface)`, border: `1px solid var(--color-border)`,
+ `borderRadius: var(--space-2)`, `boxShadow: 0 2px 8px rgba(0,0,0,0.12)`
+- Padding: `var(--space-3) var(--space-4)` (12px 16px)
+- Content: `CheckCircle` (16px, `var(--color-member-0)`) + toast message text (Label 13px/400,
+ `var(--color-text-primary)`)
+- Auto-dismiss: after 3 seconds (no dismiss button needed for a household app)
+- `role="status"`, `aria-live="polite"` — screen readers announce the success
+
+**Toast copy variants:**
+
+| Action | Toast copy |
+|--------|------------|
+| Create member success | "Member added." |
+| Reset password success | "Password reset." |
+
+**Placement note:** the toast bottom offset on phone uses `var(--bottom-chrome-h)`
+(introduced in Workstream A) so it clears the BottomTabBar.
+
+### D-09 — Dialog/sheet centering fix
+
+**Surfaces:** SettingsSheet, ChangePasswordSheet, LinkOidcSheet in SettingsSheet.tsx;
+AdminPage CredentialSheet; AdminPage reset-password sheet (Surface 11B).
+
+**Problem:** sheets currently use `bottom: 0; left: 0; right: 0; maxWidth: 480px;
+margin: 0 auto` — on desktop this places them bottom-center, not truly centered.
+
+**Fix contract:**
+
+Phone (`≤767px`): bottom-sheet behavior is correct and intentional. No change.
+- `position: fixed; bottom: 0; left: 0; right: 0; borderRadius: 12px 12px 0 0`
+
+Desktop (`≥768px`): centered modal.
+- `position: fixed; top: 50%; left: 50%; transform: translate(-50%, -50%)`
+- `maxWidth: 480px; width: calc(100% - var(--space-8)); borderRadius: 12px`
+- `maxHeight: calc(100dvh - var(--space-8)); overflowY: auto`
+- Remove `bottom: 0; left: 0; right: 0; margin: 0 auto; borderRadius: 12px 12px 0 0`
+- Box shadow: `0 8px 32px rgba(0,0,0,0.18)` (deeper shadow for centered modal feel)
+
+**Breakpoint:** use `window.matchMedia('(max-width: 767px)')` — same as `isPhone()`
+in the existing codebase. The behavior is determined at render time; no CSS-only
+media query approach is used (consistent with project pattern of inline React styles).
+
+**Applies to all sheets:** SettingsSheet, ChangePasswordSheet, LinkOidcSheet,
+CredentialSheet, AdminPage reset-password sheet. Each gets a phone/desktop style
+branch for its outer ``.
+
+**Backdrop:** unchanged — `position: fixed; inset: 0; background: var(--color-overlay)`.
+
+**Verification:** confirm via playwright-cli at both 390×844 (phone — bottom sheet) and
+1280×720 (desktop — centered modal) before merging.
+
+### D-10 — Admin two-tab navigation
+
+**Surface:** AdminPage.tsx
+
+**Structure:** horizontal tab strip at the top of the AdminPage content column,
+replacing the current single-page long-scroll layout.
+
+**Two tabs:**
+
+| Tab | Label | Contents |
+|-----|-------|----------|
+| Tab 1 | "Members & Accounts" | MEMBERS section (credential management) + LOCAL ACCOUNTS section (create member + reset-password) |
+| Tab 2 | "Settings" | SHARED CALENDAR section + TIMEZONE section |
+
+**Tab strip visual contract:**
+
+```
+┌────────────────────────────────────────────────────────────┐
+│ [Members & Accounts] [Settings] │
+│ ─────────────────── 2px active border-bottom │
+│ 1px var(--color-border-subtle) full-width rule below strip │
+└────────────────────────────────────────────────────────────┘
+```
+
+Tab strip container:
+- `display: flex; borderBottom: 1px solid var(--color-border-subtle)`
+- `marginBottom: var(--space-6)` (24px gap before first section)
+
+Individual tab button:
+- `background: none; border: none; cursor: pointer`
+- `padding: var(--space-3) var(--space-4)` (12px 16px)
+- `minHeight: 44px` (WCAG tap target)
+- `fontSize: var(--text-label-size, 13px)` (13px)
+- Inactive: `fontWeight: 400; color: var(--color-text-secondary); borderBottom: 2px solid transparent`
+- Active: `fontWeight: 600; color: var(--color-text-primary); borderBottom: 2px solid var(--color-member-0)`
+- `transition: color 0.1s ease, border-color 0.1s ease`
+- `fontFamily: var(--font-family-base)`
+
+**Accessibility (roving tabindex / ARIA tabs pattern):**
+- Tab strip container: `role="tablist"`
+- Each tab button: `role="tab"`, `aria-selected={isActive}`,
+ `aria-controls="{panel-id}"`, `id="{tab-id}"`
+- Inactive tabs: `tabIndex={-1}` (roving tabindex — only active tab is in tab order)
+- Active tab: `tabIndex={0}`
+- Keyboard navigation within the tablist: `ArrowLeft`/`ArrowRight` move focus + activate tab
+- Tab panel: `role="tabpanel"`, `aria-labelledby="{tab-id}"`, `id="{panel-id}"`
+ Each panel receives `tabIndex={0}` so keyboard users can enter the panel content after
+ the tablist
+
+**Tab IDs:**
+- `id="admin-tab-members"` / `aria-controls="admin-panel-members"`
+- `id="admin-tab-settings"` / `aria-controls="admin-panel-settings"`
+
+**Default active tab on mount:** "Members & Accounts" (Tab 1).
+
+**Phone behavior:** the two-tab strip eliminates the long-scroll on phone. Each tab's
+content replaces the other. The tab labels are short enough that both fit without
+overflow at 390px width (verify via playwright-cli). No horizontal scroll on the
+tab strip.
+
+**No new tokens** — the tab strip uses only existing spacing, color, and typography tokens.
+
+---
+
+## Copywriting Contract
+
+### Workstream D new copy
+
+| Element | Copy |
+|---------|------|
+| Logout button label | "Sign out" |
+| Logout button aria-label | "Sign out" |
+| Toast — create member success | "Member added." |
+| Toast — reset password success | "Password reset." |
+| Admin tab 1 label | "Members & Accounts" |
+| Admin tab 2 label | "Settings" |
+
+### Copywriting rules (inherited from Phase 19)
+
+- Never use "Authelia" in any user-facing copy.
+- Admin copy ("Reset password", "Sign out") is direct — admins are comfortable with the vocabulary.
+- End-user copy is warm and low-friction.
+- "Sign out" (not "Log out" or "Logout") — consistent with friendly household tone.
+- Toast copy is declarative past-tense ("Member added.") not celebratory — keeps the
+ admin UI professional.
+
+### Empty states
+
+No new empty states introduced by Phase 17. The existing AdminPage empty states
+(no members / no calendars synced) remain unchanged.
+
+### Error states
+
+No new error states introduced by Phase 17. Workstream D's logout has no error path
+(if the API call fails, the user is navigated to `/login` regardless —
+`fetchLocalLogout()` is fire-and-best-effort for a cookie clear).
+
+---
+
+## Surface Architecture
+
+### Surface A-1 — Phone layout (App.tsx `contentStyle`, phone branch)
+
+After fix:
+```ts
+const contentStyle: React.CSSProperties = {
+ flex: 1,
+ minWidth: 0,
+ minHeight: 0,
+ display: 'flex',
+ flexDirection: 'column',
+ overflow: 'hidden',
+ position: 'relative',
+ // Phone-only: reserve space for the fixed BottomTabBar
+ ...(phone ? { paddingBottom: 'var(--bottom-chrome-h)' } : {}),
+};
+```
+
+The `overflow: 'hidden'` on the outer contentStyle traps scroll. The inner route content
+(CalendarShell, ListsIndex, etc.) must handle its own scroll; the padding-bottom ensures
+their scrollable area clears the tab bar.
+
+### Surface A-2 — New Event FAB (CalendarShell.tsx)
+
+After fix (phone-only FAB style):
+```ts
+// Phone FAB positioning — clears BottomTabBar + adds breathing room
+position: 'fixed',
+bottom: 'calc(var(--bottom-chrome-h) + var(--space-6))',
+right: 'var(--space-6)',
+// size unchanged
+width: '56px',
+height: '56px',
+```
+
+### Surface B-1 — BrandSlot (BrandSlot.tsx)
+
+After swap:
+```tsx
+
+
+ {/* and
tagline unchanged */}
+
+```
+
+`--brand-logo-border-radius` updated in `tokens.css` to suit the logo shape
+(determined at checkpoint; likely `12px` for warm/rounded brief or `50%` if circular).
+
+### Surface C-1 — tokens.css structural change
+
+Before:
+```css
+:root { /* all tokens */ }
+```
+
+After:
+```css
+:root,
+[data-theme="light"] { /* all tokens, values unchanged */ }
+/* [data-theme="dark"] { ... } intentionally absent — Phase 999.20 fills this */
+```
+
+### Surface D-1 — SettingsSheet logout row
+
+After the existing Account section divider (or at the bottom of the sheet):
+```tsx
+{/* Sign out */}
+
+
+```
+
+`handleSignOut` calls `fetchLocalLogout()` then navigates to `/login`.
+
+### Surface D-2 — Admin two-tab strip (AdminPage.tsx)
+
+Rendered above all AdminPage content, inside the content column:
+- `` containing two `
+```
+
+**After fix — phone/desktop style branch:**
+```tsx
+// isPhone() from App.tsx pattern (same function defined identically in BottomTabBar.tsx)
+const phone = window.matchMedia('(max-width: 767px)').matches;
+
+
+```
+
+**This exact phone/desktop pattern applies to ALL sheets:**
+- `SettingsSheet` outer `
` (lines 184–202)
+- `ChangePasswordSheet` outer `
` (lines 598–616)
+- `LinkOidcSheet` outer `
` (lines 894–909)
+- `AdminPage.ResetPasswordSheet` outer `
` (lines 1262–1280)
+- `CredentialSheet` (separate file — apply same branch)
+
+**Logout row pattern — add after the Account section (after line 437 close tag, before the backdrop close):**
+```tsx
+{/* Sign out — bottom of sheet, after all other sections */}
+
+
+```
+
+**handleSignOut function — try/catch with navigate in both branches (pitfall 4):**
+```ts
+// Import: import { LogOut } from 'lucide-react'; (add to existing X, Bell, AlertCircle, Loader2)
+// Import: import { fetchLocalLogout } from '../api/client.js'; (add to existing fetchMe, etc.)
+// Import: import { useNavigate } from 'react-router'; (or use window.location.replace)
+
+async function handleSignOut() {
+ try {
+ await fetchLocalLogout();
+ } catch {
+ // Fire-and-best-effort: navigate regardless of whether the API call succeeded
+ }
+ // Always navigate — server-side cookie was cleared (or already expired)
+ navigate('/login');
+}
+```
+
+**Existing section divider pattern analog (lines 372–376) — same style for logout separator:**
+```tsx
+
+```
+
+---
+
+### `apps/pwa/src/routes/AdminPage.tsx` — success toasts + two-tab navigation
+
+**Analog:** self + `SyncStateToast.tsx`
+
+**Existing `createMemberMutation.onSuccess` (lines 213–221) — hook point for toast:**
+```ts
+onSuccess: () => {
+ // Clear form + refresh member list
+ setCreateDisplayName('');
+ setCreateUsername('');
+ setCreatePassword('');
+ setCreateConfirmPassword('');
+ setCreateError(null);
+ void queryClient.invalidateQueries({ queryKey: ['admin', 'members'] });
+ void queryClient.invalidateQueries({ queryKey: ['me'] });
+ // ← ADD: setToast('Member added.')
+},
+```
+
+**Existing `resetMutation.onSuccess` (lines 1230–1232) — hook point for toast:**
+```ts
+onSuccess: () => {
+ handleClose();
+ // ← ADD: setToast('Password reset.') — must propagate up from ResetPasswordSheet
+},
+```
+
+**Toast state pattern — inline in AdminPage (no new component needed; single use):**
+```ts
+// Local state — add at top of AdminPage()
+const [toast, setToast] = useState(null);
+
+// Auto-dismiss after 3 seconds — same useEffect pattern as SyncStateToast lines 72-79
+useEffect(() => {
+ if (!toast) return;
+ const timer = setTimeout(() => setToast(null), 3000);
+ return () => clearTimeout(timer);
+}, [toast]);
+```
+
+**Toast render — copy visual structure from SyncStateToast.tsx lines 159–189:**
+```tsx
+// SyncStateToast.tsx lines 159-189 — extract the wrapper div pattern
+{toast && (
+
+
+ {toast}
+
+)}
+```
+
+Note: `CheckCircle` is already imported in AdminPage.tsx line 28. `phone` constant needs adding (use `isPhone()` or inline `window.matchMedia`).
+
+**Two-tab strip pattern — add above MEMBERS section (after `Admin Settings
`):** +```tsx +// Local state — add at top of AdminPage() +const [activeTab, setActiveTab] = useState<'members' | 'settings'>('members'); + +// Keyboard nav for roving tabindex +function handleTabKeyDown(e: React.KeyboardEvent, current: 'members' | 'settings') { + if (e.key === 'ArrowRight') { + e.preventDefault(); + const next = current === 'members' ? 'settings' : 'members'; + setActiveTab(next); + (e.currentTarget.parentElement?.querySelector(`[id="admin-tab-${next}"]`) as HTMLElement)?.focus(); + } else if (e.key === 'ArrowLeft') { + e.preventDefault(); + const prev = current === 'settings' ? 'members' : 'settings'; + setActiveTab(prev); + (e.currentTarget.parentElement?.querySelector(`[id="admin-tab-${prev}"]`) as HTMLElement)?.focus(); + } +} + +// Tab strip render +
+ {(['members', 'settings'] as const).map((id) => (
+
+ ))}
+
+
+{/* Tab panels */}
+
+ {/* MEMBERS section + LOCAL ACCOUNTS section */}
+
+
+ {/* SHARED CALENDAR section + TIMEZONE section */}
+
+```
+
+**Existing `sectionLabelStyle` (lines 44–51) — reuse unchanged inside tab panels:**
+```ts
+const sectionLabelStyle: React.CSSProperties = {
+ fontSize: 'var(--text-label-size, 13px)',
+ fontWeight: 600,
+ color: 'var(--color-text-muted)',
+ textTransform: 'uppercase',
+ letterSpacing: '0.06em',
+ marginBottom: 'var(--space-2, 8px)',
+};
+```
+
+---
+
+### `apps/pwa/e2e/layout.spec.ts` — add FAB/BottomTabBar overlap assertion
+
+**Analog:** self, lines 30–60 (existing test structure pattern)
+
+**Existing test structure to follow (lines 31-60):**
+```ts
+test.describe('Rule 1/3/4 — BottomTabBar tap targets and in-viewport position', () => {
+ test.beforeEach(async ({ page }) => {
+ await page.goto('/calendar');
+ });
+
+ test('Calendar tab meets 44×44px touch-target minimum (Rule 1)', async ({ page }) => {
+ const nav = page.getByRole('navigation', { name: 'Main navigation' });
+ const calTab = nav.getByRole('link', { name: 'Calendar' });
+ const box = await calTab.boundingBox();
+ expect(box, 'Calendar tab bounding box must not be null').not.toBeNull();
+ expect(box!.width, 'Calendar tab width ≥ 44px').toBeGreaterThanOrEqual(44);
+ expect(box!.height, 'Calendar tab height ≥ 44px').toBeGreaterThanOrEqual(44);
+ });
+```
+
+**New overlap assertion to add:**
+```ts
+test('New Event FAB does not overlap BottomTabBar (A — phone only)', async ({ page }, testInfo) => {
+ test.skip(testInfo.project.name === 'desktop', 'Phone-only assertion');
+ await page.goto('/calendar');
+ const fab = page.getByRole('button', { name: 'New Event' });
+ const nav = page.getByRole('navigation', { name: 'Main navigation' });
+ const fabBox = await fab.boundingBox();
+ const navBox = await nav.boundingBox();
+ expect(fabBox, 'FAB bounding box must not be null').not.toBeNull();
+ expect(navBox, 'BottomTabBar bounding box must not be null').not.toBeNull();
+ // FAB bottom edge must be at or above the BottomTabBar top edge
+ expect(fabBox!.y + fabBox!.height).toBeLessThanOrEqual(navBox!.y);
+});
+```
+
+---
+
+### `apps/pwa/e2e/admin.spec.ts` (new file)
+
+**Analog:** `apps/pwa/e2e/layout.spec.ts` — copy file header pattern, test.describe structure, page.goto pattern
+
+**File header + structure pattern (layout.spec.ts lines 1–27):**
+```ts
+/**
+ * admin.spec.ts — TEST-XX
+ *
+ * Admin page UI assertions: two-tab ARIA pattern, success toasts, sheet centering.
+ * ...
+ *
+ * Runs on all three device profiles unless skipped via testInfo.project.name.
+ */
+import { test, expect } from '@playwright/test';
+
+test.describe('Admin tab strip — ARIA tabs pattern (D-10)', () => {
+ test.beforeEach(async ({ page }) => {
+ // Note: requires an admin session — playwright.config.ts storageState for admin
+ await page.goto('/admin');
+ });
+
+ test('Tab strip has correct ARIA roles', async ({ page }) => {
+ await expect(page.getByRole('tablist')).toBeVisible();
+ await expect(page.getByRole('tab', { name: 'Members & Accounts' })).toBeVisible();
+ await expect(page.getByRole('tab', { name: 'Settings' })).toBeVisible();
+ });
+
+ test('ArrowRight switches to Settings tab', async ({ page }) => {
+ const membersTab = page.getByRole('tab', { name: 'Members & Accounts' });
+ await membersTab.focus();
+ await page.keyboard.press('ArrowRight');
+ await expect(page.getByRole('tab', { name: 'Settings' })).toHaveAttribute('aria-selected', 'true');
+ });
+});
+```
+
+---
+
+## Shared Patterns
+
+### Phone/Desktop Breakpoint
+**Source:** `apps/pwa/src/components/BottomTabBar.tsx` lines 23–25; `apps/pwa/src/App.tsx` line 64
+**Apply to:** All sheet centering fixes (SettingsSheet, ChangePasswordSheet, LinkOidcSheet, ResetPasswordSheet, CredentialSheet), admin toast positioning, admin tab strip phone layout check
+
+```ts
+// Identical function defined in BottomTabBar.tsx, App.tsx, CalendarShell.tsx
+function isPhone(): boolean {
+ return typeof window !== 'undefined' && window.matchMedia('(max-width: 767px)').matches;
+}
+// Or inline: window.matchMedia('(max-width: 767px)').matches
+```
+
+### Sheet/Dialog Pattern
+**Source:** `apps/pwa/src/components/SettingsSheet.tsx` lines 170–202 (backdrop + dialog wrapper)
+**Apply to:** All sheets that need desktop-centering fix
+
+```tsx
+{/* Backdrop — unchanged across all sheets */}
+
+{/* Sheet outer wrapper — gains phone/desktop branch */}
+
+```
+
+### Section Divider Pattern
+**Source:** `apps/pwa/src/components/SettingsSheet.tsx` lines 372–376
+**Apply to:** Logout row separator in SettingsSheet
+
+```tsx
+
+```
+
+### Mutation + Toast Pattern
+**Source:** `apps/pwa/src/routes/AdminPage.tsx` lines 197–235 (`createMemberMutation`), `apps/pwa/src/components/SyncStateToast.tsx` lines 72–79 (auto-dismiss), lines 159–189 (toast render)
+**Apply to:** AdminPage create-member and reset-password success feedback
+
+Auto-dismiss pattern from SyncStateToast (lines 72–79):
+```ts
+useEffect(() => {
+ if (status !== 'done') return; // adapt: if (!toast) return;
+ const timer = setTimeout(() => {
+ setLastSyncedUid(null); // adapt: setToast(null)
+ }, 2000); // use 3000ms for admin toasts per UI-SPEC
+ return () => clearTimeout(timer);
+}, [status, setLastSyncedUid]);
+```
+
+### Accessible Button Row Pattern
+**Source:** `apps/pwa/src/components/SettingsSheet.tsx` lines 390–410 (Change password button row)
+**Apply to:** Logout button in SettingsSheet
+
+```tsx
+
+```
+
+---
+
+## No Analog Found
+
+| File | Role | Data Flow | Reason |
+|------|------|-----------|--------|
+| `apps/pwa/public/logo.svg` | asset | transform | New AI-generated SVG logo — no existing brand mark in codebase |
+| `apps/pwa/public/favicon.svg`, `favicon.ico`, `icon-maskable-512.png` | asset | transform | New generated assets — none exist in `public/` yet |
+| `apps/pwa/pwa-assets.config.ts` | config | transform | New `@vite-pwa/assets-generator` config — no prior asset-generation config in repo |
+
+---
+
+## Critical Pitfalls (for Planner)
+
+1. **Maskable icon must be a separate file.** `icon-maskable-512.png` is a distinct generated asset with safe-zone padding — the defect is reusing `icon-512.png` for the maskable purpose. Fix by generating `icon-maskable-512.png` via `@vite-pwa/assets-generator`.
+
+2. **`paddingBottom` in `contentStyle` is phone-only.** The `...(phone ? {...} : {})` spread pattern (from outerStyle at App.tsx lines 144–152) ensures desktop gets no extra bottom padding.
+
+3. **`--sx-color-*` overrides must stay inside the combined `tokens.css` rule block.** Do not split them to a separate selector — they must override the `@schedule-x/theme-default` values by staying in the same specificity context.
+
+4. **`fetchLocalLogout` error must not prevent navigation.** Wrap in try/catch and call `navigate('/login')` in both branches — fire-and-best-effort semantics per UI-SPEC §D-07.
+
+5. **`--brand-logo-border-radius` update required after logo approval.** The current `50%` value (circle) clips an SVG logo that draws its own shape. Update to `12px` (warm/rounded) or `0` (if SVG has own border-radius) at the checkpoint — before wiring.
+
+6. **Admin tab state is not URL-persisted.** Tab state is `useState` only — navigating away and back resets to Tab 1 ("Members & Accounts"). This is intentional per UI-SPEC §D-10.
+
+---
+
+## Metadata
+
+**Analog search scope:** `apps/pwa/src/components/`, `apps/pwa/src/routes/`, `apps/pwa/src/api/`, `apps/pwa/e2e/`, `apps/pwa/`
+**Files read:** 10 source files
+**Pattern extraction date:** 2026-06-18
diff --git a/.planning/phases/17-ui-optimization-polish/17-RESEARCH.md b/.planning/phases/17-ui-optimization-polish/17-RESEARCH.md
new file mode 100644
index 0000000..a51b25a
--- /dev/null
+++ b/.planning/phases/17-ui-optimization-polish/17-RESEARCH.md
@@ -0,0 +1,515 @@
+# Phase 17: UI Optimization & Polish — Research
+
+**Researched:** 2026-06-18
+**Domain:** React PWA polish, branding asset toolchain, CSS token architecture
+**Confidence:** HIGH (fix surfaces grounded against actual codebase; toolchain decision based on registry verification and official documentation)
+
+---
+
+
+## User Constraints (from CONTEXT.md)
+
+### Locked Decisions
+- **D-01:** Fix BottomTabBar/FAB/colour-legend overlap AND run bounded small-viewport sweep using layout.spec.ts assertions as the checklist. Fix what they flag; no free-form audit.
+- **D-03:** Logo + full icon set are AI-generated in-phase by Claude. User approves before assets are finalised. No external designer / user-supplied art.
+- **D-04:** Deliver the complete icon set: `favicon.ico` + `favicon.svg`, `icon-192.png`, `icon-512.png`, a proper maskable `icon-maskable-512.png` (safe-zone padded), `apple-touch-icon.png` (180×180). Update `index.html` and `vite.config.ts` manifest.
+- **D-05:** Drive logo through the existing BrandSlot seam: swap placeholder `
` for `![]()
`, override `--brand-logo-*` tokens. No LoginPage layout changes. Accessibility shape unchanged (`` carries name, logo is decorative `alt="" aria-hidden`).
+- **D-06:** Restructure `tokens.css` into a themeable layer (`:root, [data-theme="light"]` combined selector). Groundwork only — no dark palette values, no `prefers-color-scheme` wiring, no toggle. Schedule-X `--sx-color-*` overrides must remain working.
+- **D-07 (F-02):** Wire logout control in SettingsSheet (and/or AppNav) calling existing `fetchLocalLogout()` (client.ts:124) then navigate to `/login`. No backend work.
+- **D-08 (F-01):** Add success toast/confirmation to AdminPage create-member and reset-password flows. No backend work.
+- **D-09 (F-03):** Fix dialog/sheet centering — bottom-sheet on phone (unchanged), centered modal on desktop. Applies to SettingsSheet, ChangePasswordSheet, LinkOidcSheet, CredentialSheet, admin reset-password sheet.
+- **D-10 (F-04):** Rework admin navigation as a two-tab strip ("Members & Accounts" / "Settings") with full ARIA tabs pattern (roving tabindex, ArrowLeft/Right keyboard).
+- **D-02:** Fix technique and regression-guard mechanism are researcher/planner's call. (Resolved by UI-SPEC: shared `--bottom-chrome-h` token + permanent overlap assertion in `layout.spec.ts`.)
+
+### Claude's Discretion
+- D-02: fix technique + regression guard (resolved by UI-SPEC to: shared token + CI assertion).
+- Exact small-viewport issues surfaced by layout.spec sweep — fix as found, within no-behaviour-change boundary.
+- Logo visual execution within the brand brief — subject to user approval at checkpoint.
+
+### Deferred Ideas (OUT OF SCOPE)
+- **Shipped dark theme + light/dark/system toggle** → backlog 999.20. Phase 17 ships enabling groundwork only.
+- **Modern visual styling refresh** (login/calendar/event-form/lists/admin restyle) → backlog 999.21.
+
+
+---
+
+## Summary
+
+Phase 17 is a well-specified, bounded polish and branding pass across four workstreams on an existing shipped React 19 + Vite PWA. The UI-SPEC (17-UI-SPEC.md, approved 2026-06-18) resolves all design decisions. This research focuses on the one genuine implementation gap — the branding asset-generation toolchain — plus validation architecture and a grounded code-surface audit.
+
+**Workstream A (phone layout):** The defect is confirmed in source: `CalendarShell.tsx` FAB uses `bottom: 'var(--space-6)'` (24px), which places it behind the 56px BottomTabBar. The fix is a shared CSS custom property `--bottom-chrome-h` consumed by both the FAB offset and `App.tsx contentStyle`. This is a CSS-only change touching three files.
+
+**Workstream B (branding assets):** Sharp is not installed in this monorepo. The recommended toolchain is `@vite-pwa/assets-generator` (CLI mode, `minimal-2023` preset) which depends on `sharp` and `sharp-ico` internally, generates all seven required assets from a single source SVG, and is purpose-built for the vite-plugin-pwa ecosystem. The source logo is hand-authored SVG (warm/rounded/caricature-family brief) — this is the most reproducible, version-controlled, deterministic path.
+
+**Workstream C (token groundwork):** The `tokens.css` restructure is a single-selector change: `:root` becomes `:root, [data-theme="light"]`. The Schedule-X overrides remain inside the same rule block; no cascade order changes.
+
+**Workstream D (UAT fixes):** All four fixes are confirmed wirable against existing symbols — `fetchLocalLogout()` exists at `client.ts:124`, `SyncStateToast.tsx` provides the visual toast pattern, `AdminPage.tsx` has `useMutation` infrastructure already, and dialog centering is a `window.matchMedia` branch on the outer `
` carries name, logo is decorative `alt="" aria-hidden`).
+- **D-06:** Restructure `tokens.css` into a themeable layer (`:root, [data-theme="light"]` combined selector). Groundwork only — no dark palette values, no `prefers-color-scheme` wiring, no toggle. Schedule-X `--sx-color-*` overrides must remain working.
+- **D-07 (F-02):** Wire logout control in SettingsSheet (and/or AppNav) calling existing `fetchLocalLogout()` (client.ts:124) then navigate to `/login`. No backend work.
+- **D-08 (F-01):** Add success toast/confirmation to AdminPage create-member and reset-password flows. No backend work.
+- **D-09 (F-03):** Fix dialog/sheet centering — bottom-sheet on phone (unchanged), centered modal on desktop. Applies to SettingsSheet, ChangePasswordSheet, LinkOidcSheet, CredentialSheet, admin reset-password sheet.
+- **D-10 (F-04):** Rework admin navigation as a two-tab strip ("Members & Accounts" / "Settings") with full ARIA tabs pattern (roving tabindex, ArrowLeft/Right keyboard).
+- **D-02:** Fix technique and regression-guard mechanism are researcher/planner's call. (Resolved by UI-SPEC: shared `--bottom-chrome-h` token + permanent overlap assertion in `layout.spec.ts`.)
+
+### Claude's Discretion
+- D-02: fix technique + regression guard (resolved by UI-SPEC to: shared token + CI assertion).
+- Exact small-viewport issues surfaced by layout.spec sweep — fix as found, within no-behaviour-change boundary.
+- Logo visual execution within the brand brief — subject to user approval at checkpoint.
+
+### Deferred Ideas (OUT OF SCOPE)
+- **Shipped dark theme + light/dark/system toggle** → backlog 999.20. Phase 17 ships enabling groundwork only.
+- **Modern visual styling refresh** (login/calendar/event-form/lists/admin restyle) → backlog 999.21.
+
+
+---
+
+## Summary
+
+Phase 17 is a well-specified, bounded polish and branding pass across four workstreams on an existing shipped React 19 + Vite PWA. The UI-SPEC (17-UI-SPEC.md, approved 2026-06-18) resolves all design decisions. This research focuses on the one genuine implementation gap — the branding asset-generation toolchain — plus validation architecture and a grounded code-surface audit.
+
+**Workstream A (phone layout):** The defect is confirmed in source: `CalendarShell.tsx` FAB uses `bottom: 'var(--space-6)'` (24px), which places it behind the 56px BottomTabBar. The fix is a shared CSS custom property `--bottom-chrome-h` consumed by both the FAB offset and `App.tsx contentStyle`. This is a CSS-only change touching three files.
+
+**Workstream B (branding assets):** Sharp is not installed in this monorepo. The recommended toolchain is `@vite-pwa/assets-generator` (CLI mode, `minimal-2023` preset) which depends on `sharp` and `sharp-ico` internally, generates all seven required assets from a single source SVG, and is purpose-built for the vite-plugin-pwa ecosystem. The source logo is hand-authored SVG (warm/rounded/caricature-family brief) — this is the most reproducible, version-controlled, deterministic path.
+
+**Workstream C (token groundwork):** The `tokens.css` restructure is a single-selector change: `:root` becomes `:root, [data-theme="light"]`. The Schedule-X overrides remain inside the same rule block; no cascade order changes.
+
+**Workstream D (UAT fixes):** All four fixes are confirmed wirable against existing symbols — `fetchLocalLogout()` exists at `client.ts:124`, `SyncStateToast.tsx` provides the visual toast pattern, `AdminPage.tsx` has `useMutation` infrastructure already, and dialog centering is a `window.matchMedia` branch on the outer `` style.
+
+**Primary recommendation:** Use `@vite-pwa/assets-generator` CLI (v1.0.2) with the `minimal-2023` preset + `overrideManifestIcons: false` (manual manifest update for explicit control). Source logo: hand-authored SVG committed to `apps/pwa/public/logo.svg`.
+
+---
+
+## Architectural Responsibility Map
+
+| Capability | Primary Tier | Secondary Tier | Rationale |
+|------------|-------------|----------------|-----------|
+| FAB/BottomTabBar overlap fix | Browser / Client (CSS) | — | Pure layout geometry; CSS custom property token on the client; no server involvement |
+| Icon/favicon asset generation | Build tooling (Node.js CLI) | Static/CDN | Run once at design time; assets committed to `public/`; served as static files |
+| Token restructure (tokens.css) | Browser / Client (CSS) | — | CSS-only structural change; no server data |
+| BrandSlot logo swap | Browser / Client (React) | — | Component-internal change; logo served from `public/logo.svg` static file |
+| Logout control | Frontend + API | — | UI calls existing `POST /api/auth/local/logout` (already implemented); no new backend |
+| Admin success toast | Browser / Client (React) | — | Client-side state (`useState` + `setTimeout`); mutation already exists |
+| Dialog centering | Browser / Client (CSS/React) | — | Breakpoint-conditional inline style on existing dialog wrappers |
+| Admin two-tab nav | Browser / Client (React) | — | Local `useState` in AdminPage; ARIA tabs pattern; no routing change |
+
+---
+
+## Standard Stack
+
+### Core (already installed — no new runtime dependencies required)
+
+| Library | Version | Purpose | Status |
+|---------|---------|---------|--------|
+| React 19 | ^19.0.0 | PWA component framework | Installed |
+| lucide-react | 1.17.0 | Icon library (`LogOut`, `CheckCircle` for D-07/D-08) | Installed; `LogOut` not yet imported anywhere |
+| @tanstack/react-query | 5.101.0 | Mutation infrastructure for admin toasts | Installed |
+| vite-plugin-pwa | ^1.3.0 | Manifest icons wiring | Installed |
+
+### Build-time toolchain (new devDependency, `apps/pwa` scope)
+
+| Package | Version | Purpose | Verdict |
+|---------|---------|---------|---------|
+| `@vite-pwa/assets-generator` | 1.0.2 | CLI: generates all PWA icon assets from SVG source | OK [VERIFIED: npm registry] |
+| `sharp` | 0.35.1 (latest) | Raster processing engine (pulled as dependency of assets-generator) | SUS (see audit) — well-known package, seam flagged as too-new due to version date |
+| `sharp-ico` | 0.1.5 | ICO encoder used internally by assets-generator | OK [VERIFIED: npm registry] |
+
+**Note on `sharp` SUS verdict:** The seam flagged it `too-new` because the latest publish date (2026-06-11) is within 30 days. This is a 12-year-old package (created 2013-08-20) with 65.6M weekly downloads at `github.com/lovell/sharp` — it is the canonical Node.js image processing library. The `too-new` signal reflects the latest version's publish date, not the package age. The planner should note this but may treat it as approved. [ASSUMED: confidence assessment of seam verdict vs. package age]
+
+**No new runtime dependencies.** Zero npm packages are added to `dependencies` — only devDependencies for the asset generation script.
+
+### Alternatives Considered
+
+| Instead of | Could Use | Why not |
+|------------|-----------|---------|
+| `@vite-pwa/assets-generator` | `pwa-asset-generator` (v8.1.5) | pwa-asset-generator uses Puppeteer/Chromium to generate assets (heavier); last meaningful update 2026-06-01; not the official vite-pwa project's tool |
+| `@vite-pwa/assets-generator` | `sharp` directly + custom script | More code to maintain; assets-generator is purpose-built for this stack and already handles maskable safe-zone, ICO via sharp-ico |
+| `@vite-pwa/assets-generator` | ImageMagick `convert` | ImageMagick is not installed on this machine (confirmed via `which convert`) |
+| Hand-authored SVG source | Raster PNG source + trace | SVG is version-controllable, infinitely scalable, editable as text; no round-trip through a raster format |
+
+---
+
+## Package Legitimacy Audit
+
+| Package | Registry | Age | Downloads | Source Repo | Verdict | Disposition |
+|---------|----------|-----|-----------|-------------|---------|-------------|
+| `@vite-pwa/assets-generator` | npm | ~7 mo (2025-10-14) | 231K/wk | github.com/vite-pwa/assets-generator | OK | Approved |
+| `sharp` | npm | 13 yrs (2013-08-20) | 65.6M/wk | github.com/lovell/sharp | SUS (too-new flag on latest version) | Approved — package age and download volume override seam's version-recency signal; see note above |
+| `sharp-ico` | npm | ~4 yrs (2022-08-30) | 431K/wk | github.com/ssnangua/sharp-ico | OK | Approved |
+
+**Packages removed due to SLOP verdict:** none
+**Packages flagged as suspicious SUS:** `sharp` — seam flagged due to latest version publish date (2026-06-11 within 30-day window). This is a false positive given 13-year age and 65M weekly downloads. Planner does NOT need to add `checkpoint:human-verify` for this package; document the assessment and proceed.
+
+---
+
+## Architecture Patterns
+
+### Recommended Asset-Generation Script Shape
+
+```
+apps/pwa/
+├── pwa-assets.config.ts # @vite-pwa/assets-generator config
+└── public/
+ ├── logo.svg # Source — hand-authored SVG (warm/rounded; committed)
+ ├── favicon.svg # Generated (copy of source SVG)
+ ├── favicon.ico # Generated (48×48 ICO via sharp-ico)
+ ├── icon-192.png # Generated (192×192 transparent PNG)
+ ├── icon-512.png # Generated (512×512 transparent PNG)
+ ├── icon-maskable-512.png # Generated (512×512 maskable, safe-zone padded)
+ └── apple-touch-icon.png # Generated (180×180 PNG)
+```
+
+**Minimal pwa-assets.config.ts:**
+
+```ts
+// Source: @vite-pwa/assets-generator official docs / vite-pwa-org.netlify.app
+import { defineConfig, minimal2023Preset } from '@vite-pwa/assets-generator/config'
+
+export default defineConfig({
+ preset: {
+ ...minimal2023Preset,
+ // The minimal-2023 preset generates:
+ // - favicon.ico (48x48 via sharp-ico)
+ // - favicon.svg (copy of source)
+ // - icon-64.png (64×64 transparent)
+ // - icon-192.png (192×192 transparent)
+ // - icon-512.png (512×512 transparent, purpose: 'any')
+ // - icon-maskable-512.png (512×512 maskable, white bg, safe-zone padded, purpose: 'maskable')
+ // - apple-touch-icon.png (180×180)
+ },
+ images: ['public/logo.svg'],
+})
+```
+
+**Generate command:**
+
+```bash
+# Run from apps/pwa/
+npx --yes @vite-pwa/assets-generator generate
+```
+
+Or add to `package.json` scripts:
+
+```json
+"pwa:icons": "pwa-assets-generator generate"
+```
+
+**Maskable safe-zone math (confirmed by minimal-2023 preset):** The preset produces a 512×512 maskable PNG with the logo scaled to fit within the 80% safe zone (410px effective canvas) centered on the canvas, with a solid background fill. The outer 10% on each edge may be cropped by adaptive-icon masks. The source `logo.svg` viewBox should be square; the tool handles all padding arithmetic. [CITED: vite-pwa-org.netlify.app/assets-generator/]
+
+**ICO generation:** `sharp-ico` (a dependency of `@vite-pwa/assets-generator`) produces the `.ico` file. The `minimal-2023` preset emits a 48×48 single-size ICO. The UI-SPEC calls for 16+32 multi-size — this is a minor gap. Resolution: the favicon.ico produced at 48px is adequate for modern use; multi-size ICO adds complexity with negligible real-world benefit for a household app. The `favicon.svg` (higher priority) covers modern browsers. [ASSUMED: 48px single-size ICO is sufficient vs. 16+32 multi-size for this use case]
+
+**vite.config.ts manifest update (after generation):**
+
+```ts
+icons: [
+ { src: '/icon-192.png', sizes: '192x192', type: 'image/png' },
+ { src: '/icon-512.png', sizes: '512x512', type: 'image/png' },
+ { src: '/icon-maskable-512.png', sizes: '512x512', type: 'image/png', purpose: 'maskable' },
+],
+```
+
+**index.html wiring (after generation):**
+
+```html
+
+
+
+
+```
+
+### Pattern 1: Shared Bottom-Chrome Token (Workstream A)
+
+**What:** Single CSS custom property `--bottom-chrome-h` defines the BottomTabBar's effective height including the safe-area-inset. Three sites consume it — the bar's own height, the FAB bottom offset, and the content area padding-bottom.
+
+**Fix contract:**
+
+```css
+/* tokens.css — add to :root */
+--bottom-chrome-h: calc(56px + env(safe-area-inset-bottom, 0px));
+```
+
+```ts
+// CalendarShell.tsx — FAB bottom offset (phone branch only)
+bottom: 'calc(var(--bottom-chrome-h) + var(--space-6))',
+```
+
+```ts
+// App.tsx — contentStyle (phone branch only)
+...(phone ? { paddingBottom: 'var(--bottom-chrome-h)' } : {}),
+```
+
+The BottomTabBar.tsx `height` already uses the same arithmetic inline (`calc(56px + env(safe-area-inset-bottom, 0px))`); it may optionally reference the token for consistency, but neither path changes the visual geometry.
+
+### Pattern 2: Overlap Regression Assertion (Workstream A)
+
+**Add to `layout.spec.ts`:**
+
+```ts
+// Source: UI-SPEC §Regression Guard (D-02)
+test('New Event FAB does not overlap BottomTabBar (A — phone only)', async ({ page }, testInfo) => {
+ test.skip(testInfo.project.name === 'desktop', 'Phone-only assertion');
+ await page.goto('/calendar');
+ const fab = page.getByRole('button', { name: 'New Event' });
+ const nav = page.getByRole('navigation', { name: 'Main navigation' });
+ const fabBox = await fab.boundingBox();
+ const navBox = await nav.boundingBox();
+ expect(fabBox).not.toBeNull();
+ expect(navBox).not.toBeNull();
+ expect(fabBox!.y + fabBox!.height).toBeLessThanOrEqual(navBox!.y);
+});
+```
+
+### Pattern 3: Admin Tabs ARIA Pattern (Workstream D-10)
+
+```tsx
+// AdminPage.tsx — roving tabindex ARIA tabs
+
+ {(['members', 'settings'] as const).map((id) => (
+
+ ))}
+
+
+ {/* active panel content */}
+
+```
+
+`handleTabKeyDown` moves focus + activates on ArrowLeft/ArrowRight using `document.querySelector('[role="tab"]')` siblings or a ref array.
+
+### Anti-Patterns to Avoid
+
+- **Do not add `data-theme="light"` attribute to ``** in Phase 17. The groundwork is CSS-only; the attribute is added by Phase 999.20 when the toggle is shipped. The combined `:root, [data-theme="light"]` selector means light tokens apply regardless — no attribute needed for light-only.
+- **Do not use `pwa-asset-generator` (the older v8 package)** — it uses Puppeteer/Chromium and is not the official vite-pwa project tool.
+- **Do not run `@vite-pwa/assets-generator` with `overrideManifestIcons: true`** in this project — the manifest is manually maintained in `vite.config.ts`; auto-overwrite would stomp the explicit entries.
+- **Do not modify `LoginPage.tsx`** when swapping BrandSlot internals — the seam contract from Phase 19 explicitly forbids layout changes to LoginPage.
+- **Do not use `dangerouslySetInnerHTML`** in any new components (T-05-24 invariant, enforced project-wide).
+
+---
+
+## Don't Hand-Roll
+
+| Problem | Don't Build | Use Instead | Why |
+|---------|-------------|-------------|-----|
+| Maskable icon safe-zone padding | Custom canvas/sharp script | `@vite-pwa/assets-generator` minimal-2023 preset | Safe-zone math, ICO encoding, maskable background fill already implemented and tested |
+| ICO encoding | Custom bit-packing | `sharp-ico` (dependency of assets-generator) | ICO is a non-trivial multi-image container format; sharp-ico handles it correctly |
+| Toast state management | Custom event bus | Local `useState` + `setTimeout` in AdminPage | Single-component use; TanStack Query `onSuccess` callback feeds the state directly |
+| ARIA tabs keyboard nav | Custom focus-trap | Roving tabindex pattern (standard ARIA spec) | Two tabs; ArrowLeft/ArrowRight with `tabIndex={-1}` on inactive tabs is 10 lines of code |
+
+---
+
+## Code Surface Audit (Fix Surfaces Verified Against Source)
+
+All files and symbols confirmed to exist as described in CONTEXT.md and UI-SPEC. No drift found.
+
+### Workstream A
+
+| File | Finding | Status |
+|------|---------|--------|
+| `apps/pwa/src/App.tsx` | `contentStyle` (lines 155–163): no `paddingBottom`; phone split done via `isPhone()` function defined at line 64 | CONFIRMED — `paddingBottom` absent, fix is additive |
+| `apps/pwa/src/components/BottomTabBar.tsx` | `height: 'calc(56px + env(safe-area-inset-bottom, 0px))'` at line 72; `position: fixed; bottom: 0; z-index: 200` | CONFIRMED — matches UI-SPEC description exactly |
+| `apps/pwa/src/components/CalendarShell.tsx` | FAB at lines 463–484: `position: 'fixed', bottom: 'var(--space-6)', right: 'var(--space-6)'` — the defect | CONFIRMED — FAB bottom is `var(--space-6)` (24px), not clearing the 56px bar |
+| `apps/pwa/e2e/layout.spec.ts` | Existing assertions cover tap targets, overflow, in-viewport; no overlap assertion yet | CONFIRMED — overlap assertion is missing; file is the correct home for it |
+| `apps/pwa/playwright.config.ts` | Three profiles: iphone (390×844 WebKit), pixel (412×915 Chromium), desktop (1280×720 Chrome) | CONFIRMED |
+
+### Workstream B
+
+| File | Finding | Status |
+|------|---------|--------|
+| `apps/pwa/public/` | Three stubs: `apple-touch-icon.png` (617 B), `icon-192.png` (699 B), `icon-512.png` (4086 B). No `favicon.ico`, no `favicon.svg`, no `icon-maskable-512.png` | CONFIRMED — stubs only; all need replacement |
+| `apps/pwa/index.html` | One ``, one ``, no `` | CONFIRMED — favicon links entirely absent |
+| `apps/pwa/vite.config.ts` | `icons` array (lines 38–42): 3 entries; last entry incorrectly reuses `icon-512.png` for maskable purpose | CONFIRMED — `{ src: '/icon-512.png', sizes: '512x512', type: 'image/png', purpose: 'maskable' }` is the defect |
+| `apps/pwa/src/components/BrandSlot.tsx` | Placeholder `` with `--brand-logo-*` token consumption; `FamilySync
` and tagline `` present | CONFIRMED — swap internals only; seam is correct |
+| `sharp` in monorepo | Not installed anywhere in monorepo — not in `apps/pwa/package.json`, `apps/api/package.json`, or root; `node_modules/sharp` absent | CONFIRMED — must install `@vite-pwa/assets-generator` as devDependency |
+
+### Workstream C
+
+| File | Finding | Status |
+|------|---------|--------|
+| `apps/pwa/src/styles/tokens.css` | Single `:root { ... }` block with all tokens including `--brand-logo-*` tokens and Schedule-X `--sx-color-*` overrides at bottom | CONFIRMED — restructure is selector-only; token values unchanged |
+
+### Workstream D
+
+| Symbol | File | Line | Status |
+|--------|------|------|--------|
+| `fetchLocalLogout()` | `apps/pwa/src/api/client.ts` | 124–134 | CONFIRMED — `POST /api/auth/local/logout`, `credentials: 'include'`, `redirect: 'manual'`; handles opaqueredirect |
+| `SyncStateToast` visual pattern | `apps/pwa/src/components/SyncStateToast.tsx` | 1–60 | CONFIRMED — toast renders with `role="status"` or `role="alert"`, bottom-center position; reuse the visual style |
+| `AdminPage.tsx` | `apps/pwa/src/routes/AdminPage.tsx` | 1–80 | CONFIRMED — `useMutation` imports from TanStack Query present; `sectionLabelStyle` defined; currently single-scroll layout |
+| `SettingsSheet.tsx` sheet structure | `apps/pwa/src/components/SettingsSheet.tsx` | 1–60 | CONFIRMED — `role="dialog"` pattern exists; `LogOut` lucide icon NOT yet imported (needs adding) |
+
+---
+
+## Common Pitfalls
+
+### Pitfall 1: Maskable Icon Without Safe Zone
+**What goes wrong:** Reusing the non-maskable 512 PNG as the maskable icon (the current defect in `vite.config.ts`) — the logo gets cropped at the edges on Android adaptive icons.
+**Why it happens:** The manifest `purpose: 'maskable'` flag is easy to add without understanding that maskable requires the logo to be inset within the 80% safe zone.
+**How to avoid:** Generate a separate `icon-maskable-512.png` using `@vite-pwa/assets-generator` which pads the logo to the safe zone automatically with a solid background fill.
+**Warning signs:** `maskable` and `any` entries pointing to the same file in the manifest.
+
+### Pitfall 2: FAB Position Regression on Desktop
+**What goes wrong:** Applying `paddingBottom: 'var(--bottom-chrome-h)'` to `contentStyle` unconditionally — on desktop, this adds 56px+ of empty space below content where there is no BottomTabBar.
+**Why it happens:** `contentStyle` in `App.tsx` is shared across phone and desktop layouts.
+**How to avoid:** Apply the padding-bottom only in the phone branch — `...(phone ? { paddingBottom: 'var(--bottom-chrome-h)' } : {})`. The existing `phone` boolean (computed from `isPhone()` at line 84 of `App.tsx`) is the correct gate.
+**Warning signs:** layout.spec.ts desktop profile shows content area with unexpected bottom padding.
+
+### Pitfall 3: Schedule-X Token Override Cascade Break
+**What goes wrong:** Moving the `--sx-color-*` overrides OUTSIDE the `:root, [data-theme="light"]` block during the tokens.css restructure — they no longer override the `@schedule-x/theme-default` values.
+**Why it happens:** The tokens.css comment says "must come after the theme-default import" (import order in main.tsx), but that refers to the stylesheet import order. If the overrides move to a new rule block that comes before `:root` in cascade order (e.g., a bare `[data-theme="light"]` block without `:root`), specificity changes could affect the Schedule-X defaults.
+**How to avoid:** Keep ALL tokens — including `--sx-color-*` — inside the combined `:root, [data-theme="light"]` block. Do not split them across multiple rule blocks.
+**Warning signs:** Schedule-X calendar grid loses custom colors (event chips revert to the Schedule-X default blue/green).
+
+### Pitfall 4: `fetchLocalLogout` Error Swallowed on Navigate
+**What goes wrong:** If `fetchLocalLogout()` rejects (e.g., server error, network timeout), a naive `await fetchLocalLogout(); navigate('/login')` would navigate away without clearing the cookie. The user would believe they logged out but the session cookie may still be valid.
+**Why it happens:** Async error propagation on a fire-and-forget logout.
+**How to avoid:** Wrap in `try/catch` and call `navigate('/login')` in both the `try` (success) and `catch` (failure) branches — the UI-SPEC documents this as "fire-and-best-effort for a cookie clear." The server already handles the 401 case by expiring the cookie; the navigate is always safe.
+**Warning signs:** `fetchLocalLogout` throws and the SettingsSheet stays open.
+
+### Pitfall 5: `--brand-logo-border-radius` Not Updated
+**What goes wrong:** After swapping the BrandSlot `
` for an `![]()
`, the `--brand-logo-border-radius: 50%` token (currently in tokens.css) clips the `![]()
` into a circle regardless of the logo's own shape.
+**Why it happens:** The token was set for the initials-circle placeholder; it is inherited by the `![]()
` element via the BrandSlot swap contract.
+**How to avoid:** After the logo art is approved at the checkpoint, update `--brand-logo-border-radius` in tokens.css to match the logo shape (likely `12px` for a warm/rounded brief, or `0` if the SVG draws its own shape).
+**Warning signs:** The real logo looks cropped or forced into a circle shape in the login view.
+
+---
+
+## Runtime State Inventory
+
+SKIPPED — this is a greenfield polish phase, not a rename/refactor/migration. No stored data, live service config, OS-registered state, secrets, or build artifacts carry strings being changed.
+
+---
+
+## Environment Availability
+
+| Dependency | Required By | Available | Version | Fallback |
+|------------|------------|-----------|---------|----------|
+| Node.js | Asset generation script | ✓ | 22 LTS | — |
+| pnpm | Monorepo package management | ✓ | (installed) | — |
+| `@vite-pwa/assets-generator` | Workstream B icon generation | ✗ (not installed) | 1.0.2 (latest) | Install as devDependency in `apps/pwa` |
+| `sharp` | Transitive dep of assets-generator | ✗ (not installed) | 0.35.1 (latest) | Installed automatically with assets-generator |
+| ImageMagick `convert` | Alternative ICO generation | ✗ | — | Not needed — using assets-generator instead |
+| Playwright | Workstream A regression assertions | ✓ | 1.60.0 | — |
+| Vitest | Unit tests | ✓ | ^4.1.8 | — |
+
+**Missing dependencies with no fallback:** none
+**Missing dependencies with fallback:** `@vite-pwa/assets-generator` — install as devDependency in `apps/pwa`.
+
+---
+
+## Validation Architecture
+
+### Test Framework
+
+| Property | Value |
+|----------|-------|
+| E2E Framework | Playwright 1.60.0 |
+| Unit Framework | Vitest ^4.1.8 |
+| E2E Config | `apps/pwa/playwright.config.ts` |
+| Unit Config | `apps/pwa/vitest.config.ts` |
+| E2E quick run | `pnpm --filter @familysync/pwa exec playwright test --project=pixel layout.spec.ts` |
+| E2E full suite | `pnpm --filter @familysync/pwa test:e2e` |
+
+### Phase Requirements → Validation Map
+
+| Workstream | Behavior | Test Type | Command / Method | Automated? |
+|------------|----------|-----------|------------------|------------|
+| A — FAB overlap | FAB bottom edge ≤ BottomTabBar top edge on iphone/pixel | Playwright geometry assertion | New assertion in `layout.spec.ts` | CI (iphone + pixel profiles) |
+| A — Content clearance | Color legend chips visible; content scrollable above bar | Playwright + playwright-cli sweep | `layout.spec.ts` full suite + manual scroll | Partially automated |
+| A — No horizontal overflow | `scrollWidth ≤ clientWidth` after fix | Playwright Rule 2 | Existing `layout.spec.ts` Rule 2 tests | CI (all profiles) |
+| A — Tap targets preserved | All existing ≥44px/≥56px assertions pass | Playwright Rule 1 | Existing `layout.spec.ts` Rule 1 tests | CI (all profiles) |
+| B — Asset existence | All 7 files present in `apps/pwa/public/` | Shell `ls` / existence check | `ls apps/pwa/public/{favicon.svg,favicon.ico,icon-192.png,icon-512.png,icon-maskable-512.png,apple-touch-icon.png,logo.svg}` | CI gate / Wave 0 check |
+| B — Manifest references resolve | PWA manifest icons all 200 in browser | Playwright | `page.goto('/')` then check `navigator.serviceWorker` / devtools manifest tab | playwright-cli |
+| B — Maskable dimensions | `icon-maskable-512.png` is exactly 512×512 | Node.js check using `sharp` | `node -e "require('sharp')('/path/icon-maskable-512.png').metadata().then(m => console.log(m.width, m.height))"` | Scripted |
+| B — ICO is not zero-byte | `favicon.ico` exists and is >100 bytes | Shell | `test $(wc -c < apps/pwa/public/favicon.ico) -gt 100` | CI gate |
+| B — Visual logo approval | Logo meets warm/rounded brief | Human review | playwright-cli screenshot + operator approval | Human checkpoint (checkpoint:human-verify) |
+| C — No hard-coded values in components | `grep` finds no hex/px literals in component files | `grep` | `grep -rn '#[0-9a-fA-F]\{3,6\}\|[0-9]\+px' apps/pwa/src/components/ apps/pwa/src/routes/` | CI gate |
+| C — Schedule-X colors unchanged | Calendar grid retains custom colors post-restructure | Playwright + playwright-cli | playwright-cli visual sweep of /calendar | playwright-cli |
+| C — Build succeeds | TypeScript + Vite build exits 0 | Build | `pnpm --filter @familysync/pwa build` | CI |
+| D-07 — Logout control renders | "Sign out" button visible in SettingsSheet | Playwright + playwright-cli | playwright-cli: open settings sheet, confirm button visible | playwright-cli |
+| D-07 — Logout wiring | `fetchLocalLogout` called on click; navigate to /login | Playwright interaction | playwright-cli: click Sign out, confirm redirect to /login | playwright-cli |
+| D-08 — Admin create toast | "Member added." toast appears after create success | Playwright interaction | playwright-cli: create member, confirm toast | playwright-cli (admin session) |
+| D-08 — Admin reset toast | "Password reset." toast appears after reset success | Playwright interaction | playwright-cli: reset password, confirm toast | playwright-cli (admin session) |
+| D-08 — Toast auto-dismiss | Toast disappears after ~3 seconds | Playwright interaction | playwright-cli: wait 3.5s after toast appears | playwright-cli |
+| D-09 — Dialog desktop centering | Sheet renders centered (`top: 50%; left: 50%; transform`) on desktop | Playwright geometry | playwright-cli at 1280×720: open SettingsSheet, confirm geometry | playwright-cli (desktop) |
+| D-09 — Dialog phone bottom-sheet | Sheet renders at bottom on phone | Playwright geometry | playwright-cli at 390×844: open SettingsSheet, confirm bottom-sheet | playwright-cli (phone) |
+| D-10 — Admin tabs render | Two-tab strip visible with correct labels | Playwright | playwright-cli at /admin: confirm "Members & Accounts" and "Settings" tabs | playwright-cli (admin session) |
+| D-10 — Admin tabs keyboard | ArrowLeft/ArrowRight switches tabs | Playwright keyboard | playwright-cli: focus tab, ArrowRight, confirm second tab active | playwright-cli |
+| D-10 — Admin tab ARIA | `role="tablist"`, `role="tab"`, `aria-selected`, `role="tabpanel"` present | Playwright | `page.getByRole('tablist')`, `page.getByRole('tab', {name: ...})` | Playwright test (add to layout.spec.ts or admin.spec.ts) |
+
+### Sampling Rate
+
+- **Per task commit:** `pnpm --filter @familysync/pwa exec playwright test --project=pixel layout.spec.ts` (fast; phone profile covers the primary fix geometry)
+- **Per wave merge:** `pnpm --filter @familysync/pwa test:e2e` (full 3-profile suite)
+- **Phase gate:** Full Playwright suite green + playwright-cli visual sweeps passed + human logo approval received before `/gsd-verify-work`
+
+### Wave 0 Gaps
+
+- [ ] The overlap regression assertion does not exist yet — add to `apps/pwa/e2e/layout.spec.ts` (Workstream A)
+- [ ] Admin tab ARIA assertions — add to a new `apps/pwa/e2e/admin.spec.ts` or append to `layout.spec.ts` (Workstream D-10)
+- [ ] Asset existence check script — can be a Wave 0 npm script or inline CI step
+
+---
+
+## Security Domain
+
+`security_enforcement: true` in `.planning/config.json`. ASVS level 1.
+
+| ASVS Category | Applies | Control |
+|---------------|---------|---------|
+| V2 Authentication | No — no auth changes; logout calls existing endpoint | Existing endpoint (`POST /api/auth/local/logout`) already verified in Phase 19 |
+| V3 Session Management | Indirect — logout clears session cookie | `fetchLocalLogout` posts to existing endpoint; cookie clearance is server-side |
+| V4 Access Control | No — admin page UX gating unchanged; server 403 unchanged | No new routes or authorization changes |
+| V5 Input Validation | Minimal — admin tab state, toast message strings are hardcoded constants | No user input reaches new UI surfaces except the existing admin forms (unchanged) |
+| V6 Cryptography | No | No new crypto |
+
+### Known Threat Patterns
+
+| Pattern | STRIDE | Mitigation |
+|---------|--------|------------|
+| XSS via toast message content | Spoofing/Tampering | Toast copy is hardcoded JSX string constants ("Member added." / "Password reset.") — no user-controlled content; T-05-24 invariant maintained |
+| Session fixation after logout | Elevation of Privilege | `fetchLocalLogout` clears the `local-session` cookie server-side; client navigates to `/login` regardless of success/failure |
+| Admin route access without OIDC | Elevation of Privilege | No change — `isAdmin` check in App.tsx is UX-only; server enforces 403 on all `/api/admin/*` (unchanged) |
+
+---
+
+## Assumptions Log
+
+| # | Claim | Section | Risk if Wrong |
+|---|-------|---------|---------------|
+| A1 | `@vite-pwa/assets-generator` `minimal-2023` preset generates a maskable icon with the logo properly inset in the 80% safe zone (not just solid-color fill) | Standard Stack / Asset Toolchain | If the preset only fills the 512×512 with a background and does not inset the logo, the maskable icon will have the logo cropped on adaptive-icon masks — require custom `padding` option in config |
+| A2 | The 48×48 single-size `favicon.ico` from `@vite-pwa/assets-generator` is adequate for this household app (vs. 16+32 multi-size) | Standard Stack | Negligible visual risk — legacy browsers (IE, old Safari) may show a slightly blurry icon; no functional impact for modern browsers which prefer `favicon.svg` |
+| A3 | `sharp` SUS verdict is a false positive due to version recency window; the package is safe to use | Package Legitimacy Audit | Near-zero risk — 13-year-old package, 65.6M weekly downloads, lovell/sharp well-known author; risk if the seam has additional signals not surfaced in the output |
+| A4 | Hand-authoring SVG for the logo (warm/rounded family vibes) in-phase by Claude produces a logo that meets the brand brief to the operator's satisfaction at the checkpoint | Workstream B | If operator rejects the generated logo, the phase stalls at the checkpoint; the plan must include a checkpoint:human-verify before assets are wired in |
+
+---
+
+## Open Questions
+
+1. **`@vite-pwa/assets-generator` maskable padding behavior**
+ - What we know: the `minimal-2023` preset produces a `maskable` 512×512 PNG with a white background; the documentation describes it as "safe zone padded"
+ - What's unclear: whether the preset option allows overriding the background color to a warm brand color (e.g., `#fef3ec`) matching the logo palette, vs. always producing white
+ - Recommendation: use white background for the maskable icon in Wave 1; if the operator wants a brand-color background, add a `maskableIconOptions` config in `pwa-assets.config.ts` at the checkpoint
+
+2. **Brand accent checkpoint outcome**
+ - What we know: two candidates (Variant A: `#4a90d9` cool blue; Variant B: warm rose `#f25c7a` or amber `#e8915a`) per UI-SPEC §Color
+ - What's unclear: which the operator will select after seeing the logo
+ - Recommendation: produce the logo, show both accent variants in context (the token restructure in C makes it a one-line swap), checkpoint before committing accent to `index.html`/`vite.config.ts`/`tokens.css`
+
+---
+
+## Sources
+
+### Primary (HIGH confidence — official project documentation)
+- `apps/pwa/src/App.tsx` — `contentStyle`, `isPhone()`, phone/desktop branch; confirmed missing `paddingBottom` [VERIFIED: codebase grep]
+- `apps/pwa/src/components/CalendarShell.tsx:469–470` — FAB `bottom: 'var(--space-6)'` defect [VERIFIED: codebase grep]
+- `apps/pwa/src/components/BottomTabBar.tsx:72` — bar `height: 'calc(56px + env(safe-area-inset-bottom, 0px))'` [VERIFIED: codebase grep]
+- `apps/pwa/src/api/client.ts:124–134` — `fetchLocalLogout()` exists, POST, credentials include [VERIFIED: codebase grep]
+- `apps/pwa/src/styles/tokens.css` — single `:root {}` block confirmed; `--sx-color-*` overrides at bottom [VERIFIED: codebase grep]
+- `apps/pwa/vite.config.ts:38–42` — maskable icon defect (reusing `icon-512.png`) confirmed [VERIFIED: codebase grep]
+- `apps/pwa/index.html` — no `` entries confirmed [VERIFIED: codebase grep]
+- `apps/pwa/public/` — only 3 stub files, none maskable, no favicon.ico/svg [VERIFIED: codebase grep]
+- `.planning/config.json` — `nyquist_validation: true`, `security_enforcement: true` [VERIFIED: codebase grep]
+
+### Secondary (MEDIUM confidence — official package docs)
+- `@vite-pwa/assets-generator` v1.0.2 — vite-pwa-org.netlify.app/assets-generator/ [CITED: vite-pwa-org.netlify.app/assets-generator/]
+- `sharp` v0.35.1 — sharp.pixelplumbing.com; github.com/lovell/sharp [CITED: npm registry metadata]
+- `vite-plugin-pwa` v1.3.0 — peer-depends on `@vite-pwa/assets-generator ^1.0.0` [CITED: npm registry peerDependencies]
+
+### Tertiary (LOW confidence — training knowledge)
+- ARIA tabs pattern (roving tabindex, `role="tablist"/"tab"/"tabpanel"`) — standard W3C ARIA spec [ASSUMED — widely documented, no drift risk]
+
+---
+
+## Metadata
+
+**Confidence breakdown:**
+- Fix surfaces: HIGH — directly confirmed against codebase source
+- Asset toolchain: MEDIUM — based on official vite-pwa documentation and npm registry; `minimal-2023` preset maskable behavior [ASSUMED] pending a test run
+- Architecture patterns: HIGH — Workstreams A/C/D are CSS/React patterns with no external dependencies
+- Pitfalls: HIGH — drawn from confirmed code structure and known project conventions
+
+**Research date:** 2026-06-18
+**Valid until:** 2026-08-18 (stable APIs; vite-plugin-pwa and @vite-pwa/assets-generator are stable releases)
diff --git a/.planning/phases/17-ui-optimization-polish/17-REVIEW-FIX.iter2.md b/.planning/phases/17-ui-optimization-polish/17-REVIEW-FIX.iter2.md
new file mode 100644
index 0000000..0eb8662
--- /dev/null
+++ b/.planning/phases/17-ui-optimization-polish/17-REVIEW-FIX.iter2.md
@@ -0,0 +1,125 @@
+---
+phase: 17-ui-optimization-polish
+fixed_at: 2026-06-18T00:00:00Z
+review_path: .planning/phases/17-ui-optimization-polish/17-REVIEW.md
+iteration: 1
+findings_in_scope: 15
+fixed: 15
+skipped: 0
+status: all_fixed
+---
+
+# Phase 17: Code Review Fix Report
+
+**Fixed at:** 2026-06-18T00:00:00Z
+**Source review:** .planning/phases/17-ui-optimization-polish/17-REVIEW.md
+**Iteration:** 1
+
+**Summary:**
+- Findings in scope: 15 (fix_scope: all — includes Info)
+- Fixed: 15
+- Skipped: 0
+
+All fixes were verified with `tsc --noEmit` (clean) and `eslint --max-warnings 0`
+(clean) on every touched file; the PWA also builds (`vite build` succeeds). A new
+shared hook `apps/pwa/src/hooks/useIsPhone.ts` was created to back WR-05/IN-03.
+
+## Fixed Issues
+
+### WR-01: Modal dialogs declare `aria-modal="true"` but do not trap focus
+
+**Files modified:** `apps/pwa/src/components/CredentialSheet.tsx`, `apps/pwa/src/components/SettingsSheet.tsx`, `apps/pwa/src/routes/AdminPage.tsx`
+**Commit:** fb30800
+**Applied fix:** Reused the existing `useFocusTrap(dialogRef)` hook (already used by EventForm/SeriesEditPrompt). Added a `dialogRef` + `onKeyDown={handleDialogKeyDown}` to every modal sheet that asserts `aria-modal="true"`: CredentialSheet, SettingsSheet, ChangePasswordSheet, LinkOidcSheet, and ResetPasswordSheet. Tab/Shift-Tab now cycle within the dialog instead of escaping to occluded background controls.
+
+### WR-02: Admin tab strip keyboard nav is incomplete (no Home/End, no explicit wrap)
+
+**Files modified:** `apps/pwa/src/routes/AdminPage.tsx`
+**Commit:** f601c0c
+**Applied fix:** Rewrote `handleTabKeyDown` to the full WAI-ARIA tabs pattern: ArrowLeft/Right now wrap around the ends using modular arithmetic over the `['members','settings']` order, and Home/End jump to the first/last tab.
+
+### WR-03: Success toast does not re-announce repeated identical messages
+
+**Files modified:** `apps/pwa/src/routes/AdminPage.tsx`
+**Commit:** f601c0c
+**Applied fix:** Changed toast state from `string | null` to `{ id: number; msg: string } | null` with a `showToast(msg)` helper that mints a fresh `id` (Date.now()) per call. The rendered toast `` is now keyed on `toast.id` so an identical repeated message remounts and `aria-live` re-announces it; the auto-dismiss effect depends on the fresh object reference so the 3s timer restarts.
+
+### WR-04: Toast `whiteSpace: nowrap` is a latent horizontal-overflow regression
+
+**Files modified:** `apps/pwa/src/routes/AdminPage.tsx`
+**Commit:** f601c0c
+**Applied fix:** Removed `whiteSpace: 'nowrap'` from the toast style so a longer/localized message wraps within `maxWidth: 90vw` instead of overflowing `documentElement.scrollWidth` (which would trip the layout suite's no-horizontal-overflow rule).
+
+### WR-05: `matchMedia(...)` read at render time does not react to resize/orientation
+
+**Files modified:** `apps/pwa/src/hooks/useIsPhone.ts` (new), `apps/pwa/src/App.tsx`, `apps/pwa/src/components/CalendarShell.tsx`, `apps/pwa/src/components/SettingsSheet.tsx`, `apps/pwa/src/components/CredentialSheet.tsx`, `apps/pwa/src/routes/AdminPage.tsx`
+**Commit:** a4a7438
+**Applied fix:** Added a resize-aware `useMediaQuery`/`useIsPhone` hook backed by `matchMedia.addEventListener('change', …)`. Replaced all six synchronous `matchMedia('(max-width: 767px)')` render-time reads with `useIsPhone()`. Hook calls were placed before any early `return null` to respect the Rules of Hooks. Components now re-render when the 767px breakpoint is crossed (iPad rotation, desktop resize).
+
+### WR-06: Timezone combobox `aria-activedescendant`/highlight can desync after filtering
+
+**Files modified:** `apps/pwa/src/routes/AdminPage.tsx`
+**Commit:** 1c0f357
+**Applied fix:** Derived a clamped `tzActiveIndexClamped = Math.min(tzActiveIndex, max(0, filteredZones.length - 1))` in render and used it for `aria-activedescendant`, the Enter-to-commit lookup, and the visual highlight (`i === tzActiveIndexClamped`). ArrowUp/ArrowDown clamp the current index before moving so they never start from a stale position past the end of a freshly-shrunk list.
+**Note:** Combobox interaction logic — recommend a quick manual/keyboard pass (type to filter, arrow, Enter) to confirm behavior.
+
+### WR-07: Timezone combobox drops Tab-to-commit and relies on a fragile blur timeout
+
+**Files modified:** `apps/pwa/src/routes/AdminPage.tsx`
+**Commit:** 1c0f357
+**Applied fix:** Added a `Tab` branch to the combobox `onKeyDown` that commits the highlighted option WITHOUT `preventDefault` (focus still advances to Save). Added an unmount cleanup effect that clears `tzBlurTimer`. Reduced the blur-close `setTimeout` from 120ms to 0ms now that options `preventDefault()` on `onMouseDown` (so a click never blurs the input first).
+**Note:** Interaction logic — recommend a manual check that tabbing out of the open listbox commits the highlighted zone and that clicking an option still selects it.
+
+### WR-08: `pwa:icons` script is non-portable and silently coupled to generated filenames
+
+**Files modified:** `apps/pwa/scripts/copy-pwa-icons.mjs` (new), `apps/pwa/package.json`, `apps/pwa/vite.config.ts`
+**Commit:** dd0b761
+**Applied fix:** Replaced the five-`cp` Unix-only chain with a cross-platform Node script (`fs.copyFileSync`) that maps each generated filename to its stable manifest name and fails loudly with a named error if a generated file is missing (generator rename guard). Added a discoverability comment beside the manifest `icons` array in `vite.config.ts` pointing at the script's COPIES table.
+
+### IN-01: `OidcRedirect` navigates as a render-phase side effect
+
+**Files modified:** `apps/pwa/src/App.tsx`
+**Commit:** a4a7438
+**Applied fix:** Moved `window.location.replace('/api/login')` into a `useEffect(() => {...}, [])` so the navigation is no longer a render-phase side effect.
+
+### IN-02: Inconsistent `exhaustive-deps` disables across sibling dialogs
+
+**Files modified:** `apps/pwa/src/components/CredentialSheet.tsx`, `apps/pwa/src/components/SettingsSheet.tsx`
+**Commit:** 3f4b7ea
+**Applied fix:** Wrapped `handleClose` in `useCallback` in CredentialSheet and ChangePasswordSheet, added it to the Escape effect's dependency array, and removed the `// eslint-disable-line react-hooks/exhaustive-deps` comments — matching the LinkOidc/Reset sheet pattern.
+
+### IN-03: `isPhone`/`phone` 767px check duplicated across ~6 sites
+
+**Files modified:** (same as WR-05)
+**Commit:** a4a7438
+**Applied fix:** Resolved together with WR-05 — the single `useIsPhone()` hook now backs all call sites, and the `(max-width: 767px)` query lives in one place (`PHONE_MAX_QUERY` in the hook). The old standalone `isPhone()` helpers in App.tsx and CalendarShell.tsx were deleted.
+
+### IN-04: Dead placeholder brand tokens retained
+
+**Files modified:** `apps/pwa/src/styles/tokens.css`
+**Commit:** 2317833
+**Applied fix:** Removed the unused `--brand-logo-bg`, `--brand-logo-text`, and `--brand-app-name` declarations (verified via grep that nothing references them); left a short comment explaining the removal and that BrandSlot only reads `--brand-logo-size`/`--brand-logo-border-radius`.
+
+### IN-05: Admin members-panel JSX has inconsistent indentation / stacked bottom margins
+
+**Files modified:** `apps/pwa/src/routes/AdminPage.tsx`
+**Commit:** 4bc1e2a
+**Applied fix:** Ran Prettier (project `.prettierrc`) over AdminPage.tsx, normalizing the members-panel indentation and the rest of the file's drift; `prettier --check` now passes on the file. The stacked `marginBottom: var(--space-8)` on the last panel section was left intentionally — the review flagged it only as a minor cosmetic note, and changing section spacing risks a visual regression outside the finding's scope.
+
+### IN-06: Toast and dialog `zIndex` overlap (300/301)
+
+**Files modified:** `apps/pwa/src/routes/AdminPage.tsx`
+**Commit:** f601c0c
+**Applied fix:** Raised the toast `zIndex` from 300 to 400 so it always paints above sheet backdrops (300) and sheets (301), removing the DOM-order-dependent paint ambiguity.
+
+### IN-07: `Intl.DateTimeFormat()` recomputed every render in the calendar-config path
+
+**Files modified:** `apps/pwa/src/components/CalendarShell.tsx`, `apps/pwa/src/routes/AdminPage.tsx`
+**Commit:** 11b6b36
+**Applied fix:** Wrapped both `Intl.DateTimeFormat().resolvedOptions().timeZone` reads in `useMemo(…, [])` — `displayTimeZone` in CalendarShell (feeds the stable `useCalendarApp` config) and `detectedTz` in AdminPage.
+
+---
+
+_Fixed: 2026-06-18T00:00:00Z_
+_Fixer: Claude (gsd-code-fixer)_
+_Iteration: 1_
diff --git a/.planning/phases/17-ui-optimization-polish/17-REVIEW-FIX.iter3.md b/.planning/phases/17-ui-optimization-polish/17-REVIEW-FIX.iter3.md
new file mode 100644
index 0000000..0eb8662
--- /dev/null
+++ b/.planning/phases/17-ui-optimization-polish/17-REVIEW-FIX.iter3.md
@@ -0,0 +1,125 @@
+---
+phase: 17-ui-optimization-polish
+fixed_at: 2026-06-18T00:00:00Z
+review_path: .planning/phases/17-ui-optimization-polish/17-REVIEW.md
+iteration: 1
+findings_in_scope: 15
+fixed: 15
+skipped: 0
+status: all_fixed
+---
+
+# Phase 17: Code Review Fix Report
+
+**Fixed at:** 2026-06-18T00:00:00Z
+**Source review:** .planning/phases/17-ui-optimization-polish/17-REVIEW.md
+**Iteration:** 1
+
+**Summary:**
+- Findings in scope: 15 (fix_scope: all — includes Info)
+- Fixed: 15
+- Skipped: 0
+
+All fixes were verified with `tsc --noEmit` (clean) and `eslint --max-warnings 0`
+(clean) on every touched file; the PWA also builds (`vite build` succeeds). A new
+shared hook `apps/pwa/src/hooks/useIsPhone.ts` was created to back WR-05/IN-03.
+
+## Fixed Issues
+
+### WR-01: Modal dialogs declare `aria-modal="true"` but do not trap focus
+
+**Files modified:** `apps/pwa/src/components/CredentialSheet.tsx`, `apps/pwa/src/components/SettingsSheet.tsx`, `apps/pwa/src/routes/AdminPage.tsx`
+**Commit:** fb30800
+**Applied fix:** Reused the existing `useFocusTrap(dialogRef)` hook (already used by EventForm/SeriesEditPrompt). Added a `dialogRef` + `onKeyDown={handleDialogKeyDown}` to every modal sheet that asserts `aria-modal="true"`: CredentialSheet, SettingsSheet, ChangePasswordSheet, LinkOidcSheet, and ResetPasswordSheet. Tab/Shift-Tab now cycle within the dialog instead of escaping to occluded background controls.
+
+### WR-02: Admin tab strip keyboard nav is incomplete (no Home/End, no explicit wrap)
+
+**Files modified:** `apps/pwa/src/routes/AdminPage.tsx`
+**Commit:** f601c0c
+**Applied fix:** Rewrote `handleTabKeyDown` to the full WAI-ARIA tabs pattern: ArrowLeft/Right now wrap around the ends using modular arithmetic over the `['members','settings']` order, and Home/End jump to the first/last tab.
+
+### WR-03: Success toast does not re-announce repeated identical messages
+
+**Files modified:** `apps/pwa/src/routes/AdminPage.tsx`
+**Commit:** f601c0c
+**Applied fix:** Changed toast state from `string | null` to `{ id: number; msg: string } | null` with a `showToast(msg)` helper that mints a fresh `id` (Date.now()) per call. The rendered toast `` is now keyed on `toast.id` so an identical repeated message remounts and `aria-live` re-announces it; the auto-dismiss effect depends on the fresh object reference so the 3s timer restarts.
+
+### WR-04: Toast `whiteSpace: nowrap` is a latent horizontal-overflow regression
+
+**Files modified:** `apps/pwa/src/routes/AdminPage.tsx`
+**Commit:** f601c0c
+**Applied fix:** Removed `whiteSpace: 'nowrap'` from the toast style so a longer/localized message wraps within `maxWidth: 90vw` instead of overflowing `documentElement.scrollWidth` (which would trip the layout suite's no-horizontal-overflow rule).
+
+### WR-05: `matchMedia(...)` read at render time does not react to resize/orientation
+
+**Files modified:** `apps/pwa/src/hooks/useIsPhone.ts` (new), `apps/pwa/src/App.tsx`, `apps/pwa/src/components/CalendarShell.tsx`, `apps/pwa/src/components/SettingsSheet.tsx`, `apps/pwa/src/components/CredentialSheet.tsx`, `apps/pwa/src/routes/AdminPage.tsx`
+**Commit:** a4a7438
+**Applied fix:** Added a resize-aware `useMediaQuery`/`useIsPhone` hook backed by `matchMedia.addEventListener('change', …)`. Replaced all six synchronous `matchMedia('(max-width: 767px)')` render-time reads with `useIsPhone()`. Hook calls were placed before any early `return null` to respect the Rules of Hooks. Components now re-render when the 767px breakpoint is crossed (iPad rotation, desktop resize).
+
+### WR-06: Timezone combobox `aria-activedescendant`/highlight can desync after filtering
+
+**Files modified:** `apps/pwa/src/routes/AdminPage.tsx`
+**Commit:** 1c0f357
+**Applied fix:** Derived a clamped `tzActiveIndexClamped = Math.min(tzActiveIndex, max(0, filteredZones.length - 1))` in render and used it for `aria-activedescendant`, the Enter-to-commit lookup, and the visual highlight (`i === tzActiveIndexClamped`). ArrowUp/ArrowDown clamp the current index before moving so they never start from a stale position past the end of a freshly-shrunk list.
+**Note:** Combobox interaction logic — recommend a quick manual/keyboard pass (type to filter, arrow, Enter) to confirm behavior.
+
+### WR-07: Timezone combobox drops Tab-to-commit and relies on a fragile blur timeout
+
+**Files modified:** `apps/pwa/src/routes/AdminPage.tsx`
+**Commit:** 1c0f357
+**Applied fix:** Added a `Tab` branch to the combobox `onKeyDown` that commits the highlighted option WITHOUT `preventDefault` (focus still advances to Save). Added an unmount cleanup effect that clears `tzBlurTimer`. Reduced the blur-close `setTimeout` from 120ms to 0ms now that options `preventDefault()` on `onMouseDown` (so a click never blurs the input first).
+**Note:** Interaction logic — recommend a manual check that tabbing out of the open listbox commits the highlighted zone and that clicking an option still selects it.
+
+### WR-08: `pwa:icons` script is non-portable and silently coupled to generated filenames
+
+**Files modified:** `apps/pwa/scripts/copy-pwa-icons.mjs` (new), `apps/pwa/package.json`, `apps/pwa/vite.config.ts`
+**Commit:** dd0b761
+**Applied fix:** Replaced the five-`cp` Unix-only chain with a cross-platform Node script (`fs.copyFileSync`) that maps each generated filename to its stable manifest name and fails loudly with a named error if a generated file is missing (generator rename guard). Added a discoverability comment beside the manifest `icons` array in `vite.config.ts` pointing at the script's COPIES table.
+
+### IN-01: `OidcRedirect` navigates as a render-phase side effect
+
+**Files modified:** `apps/pwa/src/App.tsx`
+**Commit:** a4a7438
+**Applied fix:** Moved `window.location.replace('/api/login')` into a `useEffect(() => {...}, [])` so the navigation is no longer a render-phase side effect.
+
+### IN-02: Inconsistent `exhaustive-deps` disables across sibling dialogs
+
+**Files modified:** `apps/pwa/src/components/CredentialSheet.tsx`, `apps/pwa/src/components/SettingsSheet.tsx`
+**Commit:** 3f4b7ea
+**Applied fix:** Wrapped `handleClose` in `useCallback` in CredentialSheet and ChangePasswordSheet, added it to the Escape effect's dependency array, and removed the `// eslint-disable-line react-hooks/exhaustive-deps` comments — matching the LinkOidc/Reset sheet pattern.
+
+### IN-03: `isPhone`/`phone` 767px check duplicated across ~6 sites
+
+**Files modified:** (same as WR-05)
+**Commit:** a4a7438
+**Applied fix:** Resolved together with WR-05 — the single `useIsPhone()` hook now backs all call sites, and the `(max-width: 767px)` query lives in one place (`PHONE_MAX_QUERY` in the hook). The old standalone `isPhone()` helpers in App.tsx and CalendarShell.tsx were deleted.
+
+### IN-04: Dead placeholder brand tokens retained
+
+**Files modified:** `apps/pwa/src/styles/tokens.css`
+**Commit:** 2317833
+**Applied fix:** Removed the unused `--brand-logo-bg`, `--brand-logo-text`, and `--brand-app-name` declarations (verified via grep that nothing references them); left a short comment explaining the removal and that BrandSlot only reads `--brand-logo-size`/`--brand-logo-border-radius`.
+
+### IN-05: Admin members-panel JSX has inconsistent indentation / stacked bottom margins
+
+**Files modified:** `apps/pwa/src/routes/AdminPage.tsx`
+**Commit:** 4bc1e2a
+**Applied fix:** Ran Prettier (project `.prettierrc`) over AdminPage.tsx, normalizing the members-panel indentation and the rest of the file's drift; `prettier --check` now passes on the file. The stacked `marginBottom: var(--space-8)` on the last panel section was left intentionally — the review flagged it only as a minor cosmetic note, and changing section spacing risks a visual regression outside the finding's scope.
+
+### IN-06: Toast and dialog `zIndex` overlap (300/301)
+
+**Files modified:** `apps/pwa/src/routes/AdminPage.tsx`
+**Commit:** f601c0c
+**Applied fix:** Raised the toast `zIndex` from 300 to 400 so it always paints above sheet backdrops (300) and sheets (301), removing the DOM-order-dependent paint ambiguity.
+
+### IN-07: `Intl.DateTimeFormat()` recomputed every render in the calendar-config path
+
+**Files modified:** `apps/pwa/src/components/CalendarShell.tsx`, `apps/pwa/src/routes/AdminPage.tsx`
+**Commit:** 11b6b36
+**Applied fix:** Wrapped both `Intl.DateTimeFormat().resolvedOptions().timeZone` reads in `useMemo(…, [])` — `displayTimeZone` in CalendarShell (feeds the stable `useCalendarApp` config) and `detectedTz` in AdminPage.
+
+---
+
+_Fixed: 2026-06-18T00:00:00Z_
+_Fixer: Claude (gsd-code-fixer)_
+_Iteration: 1_
diff --git a/.planning/phases/17-ui-optimization-polish/17-REVIEW-FIX.md b/.planning/phases/17-ui-optimization-polish/17-REVIEW-FIX.md
new file mode 100644
index 0000000..cf13a44
--- /dev/null
+++ b/.planning/phases/17-ui-optimization-polish/17-REVIEW-FIX.md
@@ -0,0 +1,56 @@
+---
+phase: 17-ui-optimization-polish
+fixed_at: 2026-06-18T14:04:00Z
+review_path: .planning/phases/17-ui-optimization-polish/17-REVIEW.md
+iteration: 3
+findings_in_scope: 2
+fixed: 2
+skipped: 0
+status: all_fixed
+---
+
+# Phase 17: Code Review Fix Report (Iteration 3)
+
+**Fixed at:** 2026-06-18T14:04:00Z
+**Source review:** .planning/phases/17-ui-optimization-polish/17-REVIEW.md
+**Iteration:** 3
+
+**Summary:**
+- Findings in scope: 2 (fix_scope: all — includes Info)
+- Fixed: 2
+- Skipped: 0
+
+**Gate status after fixes (all pass):**
+- `pnpm --filter @familysync/pwa test` → pass (22 files, 266 passed / 0 failed)
+- `pnpm --filter @familysync/pwa typecheck` → pass (tsc + e2e tsconfig)
+- `pnpm --filter @familysync/pwa lint` → pass (eslint `--max-warnings 0`)
+
+## Fixed Issues
+
+### CR-01: `useFocusTrap` visibility filter excluded all focusables under jsdom (CI gate failed)
+
+**Files modified:** `apps/pwa/src/hooks/useFocusTrap.ts`
+**Commit:** 287ecae
+**Applied fix:** The prior iter-3 auto-fix (WR-01) rejected every focusable under jsdom because there `getBoundingClientRect()` returns all-zero geometry and `offsetParent` is `null` for every node, which short-circuited the trap (`focusable.length === 0`) and broke the two pre-existing WR-07 focus-trap regression tests — making `pnpm test` (a CI gate) fail at 2 failed / 264 passed.
+
+Made the visibility heuristic tolerant of a non-layout environment: it now derives `hasLayout = r.width > 0 || r.height > 0 || el.offsetParent !== null`, and when there is no evidence of a layout engine (jsdom) it treats the node as visible instead of filtering it. Only when a real layout exists does it apply the `offsetParent === null` / zero-geometry exclusion, so genuinely hidden/collapsed nodes are still excluded in a real browser. The `hidden`-attribute exclusion is unambiguous regardless of layout, so it was hoisted out and kept unconditional. Result: all 266 PWA tests pass, including both WR-07 cases.
+
+### IN-01: Focus-trap containment guard was unreachable as wired (harmless dead branch)
+
+**Files modified:** `apps/pwa/src/hooks/useFocusTrap.ts`
+**Commit:** 287ecae
+**Applied fix:** The handler is wired only to each dialog's own `onKeyDown`, so it can only run while focus is already inside the dialog subtree; the `!dialogRef.current.contains(document.activeElement)` containment branch could therefore never evaluate true and delivered no actual containment guarantee. Per the review's recommendation, removed the inert branch and replaced its misleading comment with an accurate note: this is a deliberate boundary-only trap (a `document`-level `keydown`/`focusin` listener would be required for true containment, and is unnecessary for the current always-focus-the-heading-on-open flows). No behavior change in any real scenario — it only removes a comment that implied a guarantee the wiring cannot provide.
+
+## Skipped Issues
+
+None.
+
+## Prior Iterations
+
+Iterations 1 and 2 fixed the earlier batches of findings (15 in iter-1, then the iter-3 review's WR-01/IN-02/IN-03 set). The IN-02 (favicon.ico coupling) and IN-03 (OidcRedirect visible status) fixes were confirmed clean by the final re-review. This iteration-3 report supersedes those and records the final state: the WR-01 regression (CR-01) and its inert containment guard (IN-01) are now resolved, with all CI gates green.
+
+---
+
+_Fixed: 2026-06-18T14:04:00Z_
+_Fixer: Claude (gsd-code-fixer)_
+_Iteration: 3_
diff --git a/.planning/phases/17-ui-optimization-polish/17-REVIEW.iter2.md b/.planning/phases/17-ui-optimization-polish/17-REVIEW.iter2.md
new file mode 100644
index 0000000..60ec5fd
--- /dev/null
+++ b/.planning/phases/17-ui-optimization-polish/17-REVIEW.iter2.md
@@ -0,0 +1,167 @@
+---
+phase: 17-ui-optimization-polish
+reviewed: 2026-06-18T00:00:00Z
+depth: deep
+files_reviewed: 13
+files_reviewed_list:
+ - apps/pwa/e2e/admin.spec.ts
+ - apps/pwa/e2e/layout.spec.ts
+ - apps/pwa/index.html
+ - apps/pwa/package.json
+ - apps/pwa/pwa-assets.config.ts
+ - apps/pwa/src/App.tsx
+ - apps/pwa/src/components/BrandSlot.tsx
+ - apps/pwa/src/components/CalendarShell.tsx
+ - apps/pwa/src/components/CredentialSheet.tsx
+ - apps/pwa/src/components/SettingsSheet.tsx
+ - apps/pwa/src/routes/AdminPage.tsx
+ - apps/pwa/src/styles/tokens.css
+ - apps/pwa/vite.config.ts
+findings:
+ critical: 0
+ warning: 8
+ info: 7
+ total: 15
+status: issues_found
+---
+
+# Phase 17: Code Review Report
+
+**Reviewed:** 2026-06-18T00:00:00Z
+**Depth:** deep
+**Files Reviewed:** 13
+**Status:** issues_found
+
+## Summary
+
+Phase 17 is UI optimization/polish: brand logo swap, PWA manifest/icon hand-maintenance, an admin two-tab ARIA strip, a success toast, and a searchable timezone combobox, plus structural layout/admin Playwright suites. No structural-findings pre-pass was provided.
+
+The code is generally careful — XSS surfaces are plain-text JSX, password fields use `new-password` autocomplete and are never pre-filled, the OIDC `authorizationUrl` null is guarded before navigation, and touch targets are consistently ≥44px. I found **no BLOCKERs** (no injection, no secret leakage, no data-loss path, no crash on the happy path).
+
+There are real correctness/robustness defects worth fixing before ship: the **admin tab keyboard handler half-implements the WAI-ARIA tabs pattern** (no Home/End, no wrap); the **timezone combobox `aria-activedescendant`/highlight can desync after filtering** and **drops Tab-to-commit**; the **success toast does not re-announce** repeated identical messages and its `whiteSpace: nowrap` is a latent Rule-2 horizontal-overflow hazard against the project's own layout suite; **none of the modal dialogs trap focus** despite `aria-modal="true"`; and several `window.matchMedia` reads at render time **do not react to resize/orientation**, a stale-UI class this project explicitly cares about (iPad rotation).
+
+## Warnings
+
+### WR-01: Modal dialogs declare `aria-modal="true"` but do not trap focus
+
+**File:** `apps/pwa/src/components/CredentialSheet.tsx:173-176`, `apps/pwa/src/components/SettingsSheet.tsx:199-202` (plus ChangePasswordSheet ~667-701 and LinkOidcSheet ~979-1013), `apps/pwa/src/routes/AdminPage.tsx:1420-1423` (ResetPasswordSheet)
+**Issue:** Every sheet sets `role="dialog"` + `aria-modal="true"` and focuses the heading/close button on open, but none implements a focus trap. Tab/Shift-Tab can move focus out of the dialog to content behind the backdrop (still in the DOM). `aria-modal="true"` asserts to assistive tech that focus is contained — it is not. The app's stated UX hard-constraint is "slick and low-friction for a non-technical Apple member"; VoiceOver/keyboard users will escape the dialog silently and interact with occluded background controls.
+**Fix:** Add a focus trap — capture Tab/Shift-Tab in the dialog keydown handler and cycle between first/last focusable descendants, ideally as a shared `useFocusTrap(ref)` hook reused by all sheets:
+```tsx
+onKeyDown={(e) => {
+ if (e.key !== 'Tab') return;
+ const f = dialogRef.current?.querySelectorAll(
+ 'a[href],button:not([disabled]),input:not([disabled]),[tabindex]:not([tabindex="-1"])');
+ if (!f?.length) return;
+ const first = f[0], last = f[f.length - 1];
+ if (e.shiftKey && document.activeElement === first) { e.preventDefault(); last.focus(); }
+ else if (!e.shiftKey && document.activeElement === last) { e.preventDefault(); first.focus(); }
+}}
+```
+
+### WR-02: Admin tab strip keyboard nav is incomplete (no Home/End, no explicit wrap)
+
+**File:** `apps/pwa/src/routes/AdminPage.tsx:205-225`
+**Issue:** `handleTabKeyDown` handles only `ArrowRight`/`ArrowLeft`, and the next/prev computation is a two-state toggle that does not wrap (ArrowRight on the Settings tab is a no-op rather than wrapping to Members). The WAI-ARIA tabs pattern requires `Home`/`End` to jump to first/last tab. `admin.spec.ts` (lines 134-152) only exercises the Arrow keys, so this gap is untested and ships a half-pattern.
+**Fix:** Handle `Home`/`End` and decide wrap behavior explicitly:
+```tsx
+const order = ['members', 'settings'] as const;
+const idx = order.indexOf(current);
+let next: typeof order[number] | null = null;
+if (e.key === 'ArrowRight') next = order[(idx + 1) % order.length];
+else if (e.key === 'ArrowLeft') next = order[(idx - 1 + order.length) % order.length];
+else if (e.key === 'Home') next = order[0];
+else if (e.key === 'End') next = order[order.length - 1];
+if (next) { e.preventDefault(); setActiveTab(next); /* focus #admin-tab-${next} */ }
+```
+
+### WR-03: Success toast does not re-announce repeated identical messages
+
+**File:** `apps/pwa/src/routes/AdminPage.tsx:62-69`, `1028-1065`
+**Issue:** The toast is a single `role="status" aria-live="polite"` region rendering the `toast` string. If the same message fires twice (two password resets, two "Member added.") and the second `setToast('…')` lands before the first cleared, React's state-equality short-circuit means the DOM text does not change, so `aria-live` does not re-announce — the second success is silent to screen-reader users, and the 3s auto-dismiss timer (keyed on `toast` identity) does not reset for an identical string.
+**Fix:** Make each toast a distinct value and remount it so AT re-announces and the timer resets:
+```tsx
+const [toast, setToast] = useState<{ id: number; msg: string } | null>(null);
+const show = (msg: string) => setToast({ id: Date.now(), msg });
+// effect dep: [toast?.id]; render: {toast.msg}
+```
+
+### WR-04: Toast `whiteSpace: nowrap` is a latent horizontal-overflow regression against Rule 2
+
+**File:** `apps/pwa/src/routes/AdminPage.tsx:1054-1055`
+**Issue:** The toast sets `whiteSpace: 'nowrap'` with `maxWidth: '90vw'`. `nowrap` + `maxWidth` does not shrink text; it overflows. A longer/localized toast on a 390px viewport will exceed 90vw and, because the toast is `position: fixed`, contribute to `documentElement.scrollWidth` — violating `layout.spec.ts` Rule 2 (lines 176-200), which asserts no horizontal overflow on `/calendar` and `/lists`. Current strings are short, so the bug is latent, not active, but it is a direct hazard to the project's own quality bar.
+**Fix:** Remove `whiteSpace: 'nowrap'` (let it wrap), or bound the width and use `overflow:hidden; text-overflow:ellipsis`. Wrapping is safer for a toast that may localize.
+
+### WR-05: `matchMedia(...)` read at render time does not react to resize/orientation
+
+**File:** `apps/pwa/src/App.tsx:64-66` (`isPhone()`), `apps/pwa/src/components/CalendarShell.tsx:74-76`, `apps/pwa/src/components/SettingsSheet.tsx:135`, `apps/pwa/src/components/CredentialSheet.tsx:156`, `apps/pwa/src/routes/AdminPage.tsx:59`, `1378-1379`
+**Issue:** These components compute `phone` once per render via synchronous `matchMedia('(max-width: 767px)').matches`, with no `change` listener. Rotating an iPad across 767px (or resizing a desktop window across the breakpoint) does not trigger a re-render, so the layout (FAB vs toolbar button in `CalendarShell`, bottom-sheet vs centered modal in the sheets, content `paddingBottom` in `App`) stays stale until an unrelated state change forces a re-render. The developer profile explicitly flags resize/orientation correctness; iPad rotation is a realistic trigger for this cross-ecosystem app.
+**Fix:** Use a `useMediaQuery` hook backed by `matchMedia.addEventListener('change', …)` so components re-render on breakpoint crossing; share a single `phone` value through context/hook so all call sites stay consistent.
+
+### WR-06: Timezone combobox `aria-activedescendant`/highlight can desync after filtering
+
+**File:** `apps/pwa/src/routes/AdminPage.tsx:819-821`, `833-837`, `839-845`, `912-919`
+**Issue:** `onChange` resets `tzActiveIndex` to 0 while `ArrowDown` clamps against `filteredZones.length - 1` from the *current render closure*. With batched updates, interleavings exist where `tzActiveIndex` (and thus `aria-activedescendant={tz-opt-${tzActiveIndex}}`, line 820) references an option index that no longer exists after the filtered list shrinks (e.g., active 12, then a keystroke filters to 3 rows before re-clamp). Separately, the visual highlight uses `i === tzActiveIndex` (line 913) while `aria-selected` uses `tz === effectiveTimezoneInput` (line 919) — two different bases, so the highlighted row and the AT-announced row can disagree.
+**Fix:** Derive a clamped active index in render and use it everywhere (visual + `aria-activedescendant`): `const activeIndex = Math.min(tzActiveIndex, Math.max(0, filteredZones.length - 1))`, or reset `tzActiveIndex` to 0 in a `useEffect` keyed on `tzSearch`.
+
+### WR-07: Timezone combobox drops Tab-to-commit and relies on a fragile blur timeout
+
+**File:** `apps/pwa/src/routes/AdminPage.tsx:838-865`, `927`
+**Issue:** (1) `onKeyDown` handles ArrowUp/Down/Enter/Escape but not `Tab`. Tabbing out with the listbox open and an option highlighted moves focus to Save without committing — the input/`effectiveTimezoneInput` still holds the raw search text, so the admin can attempt to save a partial string (server 400s, but the UX is a confusing failure). (2) The `onBlur` 120ms `setTimeout` to let an option's `onClick` fire is a race; since options already `onMouseDown` `preventDefault()` (line 927), blur won't fire on option click, so the 120ms hack may be unnecessary. The `tzBlurTimer` is cleared on focus/select but not on unmount.
+**Fix:** Commit the active option on `Tab` (without `preventDefault`, so focus still advances); clear `tzBlurTimer` in an unmount cleanup effect; reassess/remove the 120ms blur delay now that `onMouseDown` preventDefault is in place.
+
+### WR-08: `pwa:icons` script is non-portable and silently coupled to generated filenames
+
+**File:** `apps/pwa/package.json:16`
+**Issue:** `pwa:icons` chains the assets generator with five `cp` commands. (1) `cp` is Unix-only — breaks on Windows contributors and minimal CI containers. (2) It hard-codes the generator's output names (`pwa-192x192.png`, `maskable-icon-512x512.png`, `apple-touch-icon-180x180.png`); a generator version bump that renames outputs breaks it with an opaque `cp: cannot stat`. (3) The manifest icon entries in `vite.config.ts:38-42` (`/icon-192.png`, etc.) only stay in sync because of these manual renames — an invisible coupling with no test. Regenerating icons without running the full script leaves the manifest referencing stale files.
+**Fix:** Configure the generator to emit the final filenames directly, or replace the `cp` chain with a small cross-platform Node script (`fs.copyFileSync`). At minimum, add a comment in `vite.config.ts` by the icon entries pointing at the `pwa:icons` rename step so the coupling is discoverable.
+
+## Info
+
+### IN-01: `OidcRedirect` navigates as a render-phase side effect
+
+**File:** `apps/pwa/src/App.tsx:77-80`
+**Issue:** `OidcRedirect` calls `window.location.replace('/api/login')` directly in the function body (render phase). React may render a component more than once (StrictMode double-invoke in dev, concurrent re-renders); side effects in render are an anti-pattern. It works because `replace` is idempotent and the page unloads, but it is fragile.
+**Fix:** Move the navigation into `useEffect(() => { window.location.replace('/api/login'); }, [])` and render the placeholder.
+
+### IN-02: Inconsistent `exhaustive-deps` disables across sibling dialogs
+
+**File:** `apps/pwa/src/components/CredentialSheet.tsx:95`, `apps/pwa/src/components/SettingsSheet.tsx:605`
+**Issue:** The Escape `useEffect` disables `react-hooks/exhaustive-deps` (because `handleClose` is referenced but not listed), while the `LinkOidcSheet`/`ResetPasswordSheet` versions list `[isOpen, onClose]` with no disable. The blanket disable also hides any future missing dep added to that effect.
+**Fix:** Wrap `handleClose` in `useCallback` and add it to the dep array, removing the disable; make the pattern consistent across all sheets.
+
+### IN-03: `isPhone`/`phone` 767px check duplicated across ~6 sites
+
+**File:** `apps/pwa/src/App.tsx:64-66`, `CalendarShell.tsx:74-76`, `SettingsSheet.tsx:135`, `CredentialSheet.tsx:156`, `AdminPage.tsx:59`, `1378-1379`
+**Issue:** The same breakpoint check is reimplemented in two spellings (`isPhone()` helper vs inline `matchMedia`), and the JS hard-codes `767` while `tokens.css` declares `--bp-tablet: 768px`. Drift risk if the breakpoint changes.
+**Fix:** Extract one `useIsPhone()` hook (ideally the resize-aware one from WR-05) and import it everywhere; reference the breakpoint in a single place.
+
+### IN-04: Dead placeholder brand tokens retained
+
+**File:** `apps/pwa/src/styles/tokens.css:103-104,107`
+**Issue:** `--brand-logo-bg`, `--brand-logo-text`, and `--brand-app-name` are leftovers from the Phase 19 "FS initials circle." BrandSlot now renders `logo.svg` and reads only `--brand-logo-size`/`--brand-logo-border-radius`; `--brand-app-name` is commented "drives doc only — not used as CSS content." These are dead declarations.
+**Fix:** Remove them, or add a comment that they're retained intentionally for a planned fallback.
+
+### IN-05: Admin members-panel JSX has inconsistent indentation / stacked bottom margins
+
+**File:** `apps/pwa/src/routes/AdminPage.tsx:364-418`
+**Issue:** Inside `admin-panel-members`, `` and its children are indented inconsistently (section at one level, children shallower), and both the Members and Local Accounts sections carry `marginBottom: var(--space-8)`, adding trailing space at the panel boundary. Cosmetic, but will trip future edits.
+**Fix:** Reformat the panel JSX — Prettier should normalize it. Confirm `pnpm --filter @familysync/pwa lint`/format was run (a recurring pre-push gate on this project).
+
+### IN-06: Toast and dialog `zIndex` overlap (300/301)
+
+**File:** `apps/pwa/src/routes/AdminPage.tsx:1033` (toast 300) vs `CredentialSheet.tsx:169,189` (backdrop 300 / sheet 301), ResetPasswordSheet (300/301)
+**Issue:** The toast shares `zIndex: 300` with the sheet backdrops. If a toast lingers while a sheet opens within the 3s window, paint order becomes DOM-order-dependent and the toast can render under the backdrop dim. Low likelihood, but the z-index scale is not cleanly layered.
+**Fix:** Put the toast above dialogs (e.g. `zIndex: 400`) and document a named z-index scale (backdrop/sheet/toast) in `tokens.css`.
+
+### IN-07: `Intl.DateTimeFormat()` recomputed every render in the calendar-config path
+
+**File:** `apps/pwa/src/components/CalendarShell.tsx:159`, `apps/pwa/src/routes/AdminPage.tsx:146`
+**Issue:** `Intl.DateTimeFormat().resolvedOptions().timeZone` is called inline in render. Cheap, but in `CalendarShell` it feeds `useCalendarApp` config, whose stability the file's own comments warn about. (Flagged as a note, not a perf-scope item, because it touches the calendar-app config the code explicitly tries to keep stable.)
+**Fix:** `const displayTimeZone = useMemo(() => Intl.DateTimeFormat().resolvedOptions().timeZone, [])`.
+
+---
+
+_Reviewed: 2026-06-18T00:00:00Z_
+_Reviewer: Claude (gsd-code-reviewer)_
+_Depth: deep_
diff --git a/.planning/phases/17-ui-optimization-polish/17-REVIEW.iter3.md b/.planning/phases/17-ui-optimization-polish/17-REVIEW.iter3.md
new file mode 100644
index 0000000..70cf986
--- /dev/null
+++ b/.planning/phases/17-ui-optimization-polish/17-REVIEW.iter3.md
@@ -0,0 +1,95 @@
+---
+phase: 17-ui-optimization-polish
+reviewed: 2026-06-18T00:00:00Z
+depth: deep
+files_reviewed: 16
+files_reviewed_list:
+ - apps/pwa/e2e/admin.spec.ts
+ - apps/pwa/e2e/layout.spec.ts
+ - apps/pwa/index.html
+ - apps/pwa/package.json
+ - apps/pwa/pwa-assets.config.ts
+ - apps/pwa/scripts/copy-pwa-icons.mjs
+ - apps/pwa/src/App.tsx
+ - apps/pwa/src/components/BrandSlot.tsx
+ - apps/pwa/src/components/CalendarShell.tsx
+ - apps/pwa/src/components/CredentialSheet.tsx
+ - apps/pwa/src/components/SettingsSheet.tsx
+ - apps/pwa/src/hooks/useFocusTrap.ts
+ - apps/pwa/src/hooks/useIsPhone.ts
+ - apps/pwa/src/routes/AdminPage.tsx
+ - apps/pwa/src/styles/tokens.css
+ - apps/pwa/vite.config.ts
+findings:
+ critical: 0
+ warning: 1
+ info: 3
+ total: 4
+status: issues_found
+---
+
+# Phase 17: Code Review Report (Re-Review After Auto-Fix)
+
+**Reviewed:** 2026-06-18T00:00:00Z
+**Depth:** deep
+**Files Reviewed:** 16
+**Status:** issues_found
+
+## Summary
+
+This is a re-review of Phase 17 (UI optimization/polish) after auto-fixes were applied to the prior 15 findings (8 warnings, 7 info). I re-read every listed file at deep depth, traced the just-changed code (focus-trap wiring across the 5 sheets, the new `useIsPhone`/`useFocusTrap` hooks, admin tab keyboard handling, the toast re-announce/wrapping changes, the timezone combobox active-index/Tab-commit logic, and the cross-platform icon-copy script), and confirmed the fixes against the surrounding call sites for regressions.
+
+**All 8 prior warnings and all 7 prior info items are correctly resolved.** Both local gates pass clean: `pnpm --filter @familysync/pwa typecheck` (tsc + e2e tsconfig) and `pnpm --filter @familysync/pwa lint` (eslint `--max-warnings 0`) both succeed with no output. I found **no BLOCKERs** and **no regressions** introduced by the fixes.
+
+What the fixes got right and why they don't regress:
+- **Focus trap** (`useFocusTrap`) is wired into all five dialogs. The child sheets (`ChangePasswordSheet`/`LinkOidcSheet`) are rendered as DOM **siblings** of the `SettingsSheet` dialog div (after the ` ` at SettingsSheet.tsx:563), not descendants, so the parent trap's `querySelectorAll` cannot capture child-sheet focusables and there is no double-trap conflict — each sheet owns its own trap.
+- **Combobox desync** is genuinely fixed: `tzActiveIndexClamped` now drives the visual highlight (AdminPage.tsx:955), `aria-activedescendant` (:838), and the Enter/Tab commit (:879/:887) from one clamped source. `aria-selected` correctly stays bound to `effectiveTimezoneInput` (:961) — that is the right ARIA distinction (selected value vs. active option), not a residual bug.
+- **Tab-to-commit** commits the clamped option without `preventDefault`, the blur timer is now `setTimeout(…, 0)` and is cleared on focus, on select, and on unmount (AdminPage.tsx:115-119) — no setState-after-unmount path remains.
+- **Toast** is keyed on a unique `{id, msg}` so identical repeats remount and `aria-live` re-announces; `whiteSpace: nowrap` is removed so it wraps within `maxWidth: 90vw` (no Rule 2 overflow hazard); z-index raised to 400, above all sheet backdrops (max 303), resolving the prior overlap.
+- **`useIsPhone`/`useMediaQuery`** subscribe via `addEventListener('change', …)` and are now used at every former inline `matchMedia` site (App, CalendarShell, all sheets, AdminPage), so iPad rotation across 767px reflows correctly. SSR guard returns `false` cleanly.
+
+The one remaining WARNING is a pre-existing focus-trap robustness gap (not introduced this phase, but now load-bearing because `aria-modal` promises containment). The three INFO items are minor and non-blocking.
+
+## Warnings
+
+### WR-01: `useFocusTrap` only wraps at the boundaries — focus can still escape via hidden/zero-size focusables
+
+**File:** `apps/pwa/src/hooks/useFocusTrap.ts:25-48`
+**Issue:** The trap queries `button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])` and filters only `!disabled` and `tabindex !== '-1'`. It does not exclude elements that are `display:none`, `visibility:hidden`, `hidden`, or zero-size. In the current sheets every focusable is visible, so the trap works today. But the pattern has two latent escape paths: (1) if a dialog ever conditionally renders a focusable inside a `hidden`/collapsed block, that element joins the `first`/`last` computation and the wrap math targets an unfocusable node — `last.focus()` becomes a no-op and Tab leaks to background content (which `aria-modal="true"` asserts is impossible); (2) the trap only intervenes at the exact first/last boundary, so it relies on the browser's natural Tab order between them being correct and contained. This is the kind of half-implemented trap the prior WR-01 set out to eliminate; the fix is correct for the present DOM but fragile for future edits.
+**Fix:** Filter to genuinely focusable, rendered elements before computing first/last, e.g.:
+```ts
+.filter((el) => {
+ if (el.hasAttribute('disabled') || el.getAttribute('tabindex') === '-1') return false;
+ if (el.hasAttribute('hidden') || (el as HTMLElement).offsetParent === null) return false;
+ const r = el.getBoundingClientRect();
+ return r.width > 0 && r.height > 0;
+});
+```
+Alternatively, document that all dialog focusables must be unconditionally rendered and visible while the dialog is open.
+
+## Info
+
+### IN-01: Focus trap does not pull focus back when `activeElement` is already outside the dialog
+
+**File:** `apps/pwa/src/hooks/useFocusTrap.ts:36-47`
+**Issue:** The handler wraps only when `document.activeElement === first` (Shift+Tab) or `=== last` (Tab). Each sheet focuses its heading/close button on open, so the trap engages from inside. But `aria-modal="true"` does not actually prevent the background DOM (still mounted behind the backdrop) from receiving focus — e.g. a programmatic focus, or a browser quirk, could land focus outside the dialog, and then neither boundary condition matches, so Tab moves through background content until it happens to re-enter. This is the residual weakness of a boundary-only trap versus a containment trap (which checks `dialogRef.current.contains(document.activeElement)` and redirects when false). Low likelihood given the open-focus behavior; noted for completeness.
+**Fix:** Add a containment guard: if `!dialogRef.current.contains(document.activeElement)` on Tab, `preventDefault()` and focus `first`.
+
+### IN-02: `favicon.ico` is referenced by `index.html` but not produced by `pwa:icons`
+
+**File:** `apps/pwa/index.html:7`, `apps/pwa/scripts/copy-pwa-icons.mjs:21-27`
+**Issue:** `index.html` links `/favicon.ico`, and the file is committed in `public/` (967 bytes). The new `copy-pwa-icons.mjs` `COPIES` table generates `favicon.svg` (from `logo.svg`) and the PNGs, but the `minimal2023Preset` does not emit a `.ico`, so `favicon.ico` is hand-maintained outside the script. This is the same invisible-coupling class the prior WR-08 flagged, just narrowed: regenerating icons leaves `favicon.ico` stale relative to a new brand mark, with nothing to catch it. The script's own header says "Keep COPIES in sync with the manifest," but the `.ico` link in `index.html` has no such pointer.
+**Fix:** Either drop the `favicon.ico` link (the SVG favicon + `sizes="any"` covers modern browsers) or add a comment in `copy-pwa-icons.mjs`/`index.html` noting `favicon.ico` is hand-maintained and must be regenerated manually when the brand mark changes.
+
+### IN-03: `OidcRedirect` placeholder renders an empty `aria-hidden` div for a full render cycle
+
+**File:** `apps/pwa/src/App.tsx:74-82`
+**Issue:** The prior IN-01 fix correctly moved the navigation into `useEffect`. The component now renders `` and the redirect fires post-commit. For the OIDC-only-mode unauthenticated path this means a brief blank frame before `window.location.replace('/api/login')` unloads the page. Functionally fine and a strict improvement over the render-phase side effect, but the blank `aria-hidden` div gives screen-reader/keyboard users no "redirecting…" affordance during the gap.
+**Fix:** Render a minimal visible "Redirecting to sign in…" status (e.g. `role="status"`) instead of an empty `aria-hidden` div, so the transition is perceivable if the redirect is slow.
+
+---
+
+_Reviewed: 2026-06-18T00:00:00Z_
+_Reviewer: Claude (gsd-code-reviewer)_
+_Depth: deep_
+_Re-review: prior 15 findings all confirmed resolved; gates (typecheck + lint) pass clean_
diff --git a/.planning/phases/17-ui-optimization-polish/17-REVIEW.md b/.planning/phases/17-ui-optimization-polish/17-REVIEW.md
new file mode 100644
index 0000000..0a895d6
--- /dev/null
+++ b/.planning/phases/17-ui-optimization-polish/17-REVIEW.md
@@ -0,0 +1,128 @@
+---
+phase: 17-ui-optimization-polish
+reviewed: 2026-06-18T00:00:00Z
+depth: deep
+files_reviewed: 16
+files_reviewed_list:
+ - apps/pwa/e2e/admin.spec.ts
+ - apps/pwa/e2e/layout.spec.ts
+ - apps/pwa/index.html
+ - apps/pwa/package.json
+ - apps/pwa/pwa-assets.config.ts
+ - apps/pwa/scripts/copy-pwa-icons.mjs
+ - apps/pwa/src/App.tsx
+ - apps/pwa/src/components/BrandSlot.tsx
+ - apps/pwa/src/components/CalendarShell.tsx
+ - apps/pwa/src/components/CredentialSheet.tsx
+ - apps/pwa/src/components/SettingsSheet.tsx
+ - apps/pwa/src/hooks/useFocusTrap.ts
+ - apps/pwa/src/hooks/useIsPhone.ts
+ - apps/pwa/src/routes/AdminPage.tsx
+ - apps/pwa/src/styles/tokens.css
+ - apps/pwa/vite.config.ts
+findings:
+ critical: 1
+ warning: 0
+ info: 1
+ total: 2
+status: issues_found
+---
+
+# Phase 17: Code Review Report (Final Re-Review After Iter-3 Auto-Fixes)
+
+**Reviewed:** 2026-06-18T00:00:00Z
+**Depth:** deep
+**Files Reviewed:** 16
+**Status:** issues_found
+
+## Summary
+
+This is the final re-review of Phase 17 after the second round of auto-fixes, which targeted the three iter-3 findings:
+
+- **WR-01** — `useFocusTrap` hidden/zero-size focusable exclusion + containment guard.
+- **IN-03** — `App.tsx` `OidcRedirect` now renders a visible "Redirecting to sign in…" status.
+- **IN-02** — favicon.ico hand-maintained coupling documented in `copy-pwa-icons.mjs` and `index.html`.
+
+I re-read every listed file at deep depth and traced the changed code against its call sites and the existing test suite.
+
+**Two of the three fixes are correct and regression-free:**
+- **IN-03 (OidcRedirect):** Correct. The navigation stays in `useEffect` (no render-phase side effect), and the placeholder is now a perceivable `role="status"` "Redirecting to sign in…" (App.tsx:83-97). No regression.
+- **IN-02 (favicon.ico coupling):** Correct and complete. Both `copy-pwa-icons.mjs` (lines 13-17) and `index.html` (line 7) now carry the hand-maintained-`.ico` pointer. Verified on disk: `favicon.svg` is byte-identical to `logo.svg` (produced by the `COPIES` table), and `favicon.ico` (967 B) is committed separately. The invisible coupling is now documented at both ends.
+
+**The WR-01 fix introduces a CR-tier regression.** The new visibility filter in `useFocusTrap.ts` (lines 36-38) relies on `offsetParent` and `getBoundingClientRect()` width/height. Both are `null`/`0` under jsdom — the environment the existing focus-trap unit tests run in — so the filter now excludes **every** focusable, `focusable.length === 0` short-circuits, and the trap silently stops wrapping focus. This breaks the two pre-existing `EventForm.test.tsx` WR-07 tests and makes `pnpm test` (a CI gate per CLAUDE.md) fail.
+
+Gate status after the fixes:
+- `pnpm --filter @familysync/pwa typecheck` → **pass** (tsc + e2e tsconfig).
+- `pnpm --filter @familysync/pwa lint` → **pass** (eslint `--max-warnings 0`).
+- `pnpm --filter @familysync/pwa test` (vitest) → **FAIL**: 2 failed / 264 passed / 266 total. Both failures are the WR-07 focus-trap tests, caused directly by the WR-01 change under review.
+
+The IN-01 containment guard added alongside WR-01 is functionally inert (the handler is only wired to the dialog's `onKeyDown`, which cannot fire when focus is outside the dialog), but it is harmless — recorded as INFO.
+
+## Critical Issues
+
+### CR-01: `useFocusTrap` visibility filter excludes all focusables under jsdom — breaks the focus-trap test suite (CI gate fails)
+
+**File:** `apps/pwa/src/hooks/useFocusTrap.ts:36-38`
+**Issue:** The WR-01 fix added a "rendered/visible" filter to the focusable query:
+```ts
+if (el.hasAttribute('hidden') || el.offsetParent === null) return false;
+const r = el.getBoundingClientRect();
+return r.width > 0 && r.height > 0;
+```
+In a real browser this is correct. But the existing focus-trap regression tests (`apps/pwa/src/components/EventForm.test.tsx`, the two `WR-07` cases at lines 718-764) run under **jsdom**, where:
+- `getBoundingClientRect()` returns all-zero geometry for every element (`width === 0`, `height === 0`), and
+- `offsetParent` is `null` for every element.
+
+Either condition alone causes the filter to reject **every** focusable. `focusable.length` becomes `0`, the handler hits the `if (focusable.length === 0) return;` early-out (line 41), and Tab/Shift+Tab no longer wrap. Both WR-07 tests now fail:
+
+```
+FAIL src/components/EventForm.test.tsx > WR-07: Tab from last focusable element wraps focus to first inside dialog
+FAIL src/components/EventForm.test.tsx > WR-07: Shift+Tab from first focusable element wraps focus to last inside dialog
+Test Files 1 failed | 21 passed (22)
+ Tests 2 failed | 264 passed (266)
+```
+
+`pnpm test` (→ `vitest run`) is one of the CI gates the project requires to pass before push (CLAUDE.md "Frustrations" directive + the CI-checks-conformance memory). This regression ships as part of the file under review, so it is in scope even though `EventForm.test.tsx` is not in the listed-files set — those tests exist specifically to guard the changed behavior.
+
+**Fix:** Make the visibility filter tolerant of a non-layout (jsdom) environment, so it excludes genuinely hidden nodes in a browser without nuking all nodes in tests. Treat zero-geometry as "visible" when no layout engine is present, and gate on `offsetParent` only when geometry is meaningful:
+```ts
+.filter((el) => {
+ if (el.hasAttribute('disabled') || el.getAttribute('tabindex') === '-1') return false;
+ if (el.hasAttribute('hidden')) return false;
+ // jsdom has no layout: getBoundingClientRect() is all-zero and offsetParent is
+ // null for every node. Only apply the visibility heuristic when a real layout
+ // exists, so unit tests still see focusables.
+ const r = el.getBoundingClientRect();
+ const hasLayout = r.width > 0 || r.height > 0 || el.offsetParent !== null;
+ if (!hasLayout) return true; // no layout engine → don't filter on visibility
+ if (el.offsetParent === null) return false;
+ return r.width > 0 && r.height > 0;
+});
+```
+Alternatively, stub `getBoundingClientRect`/`offsetParent` in the test setup so jsdom reports non-zero geometry — but the production-side guard above is the safer minimal change, since other future tests will hit the same wall. Either way, re-run `pnpm --filter @familysync/pwa test` and confirm both WR-07 cases pass before considering this resolved.
+
+## Info
+
+### IN-01: Focus-trap containment guard is unreachable as wired (harmless dead branch)
+
+**File:** `apps/pwa/src/hooks/useFocusTrap.ts:50-54`
+**Issue:** The IN-01 fix added a containment guard:
+```ts
+if (!dialogRef.current.contains(document.activeElement)) {
+ e.preventDefault();
+ first.focus();
+ return;
+}
+```
+The comment claims this catches the case where "focus has somehow landed outside the dialog ... Tab would walk background content." But the handler is only attached to each dialog container's `onKeyDown` (verified across all 5 sheets + EventForm + SeriesEditPrompt — no `document`-level listener exists). React's synthetic `onKeyDown` on the dialog div only fires when the keydown event's target is **inside** the dialog subtree (the event must bubble up through that div). When `document.activeElement` is genuinely outside the dialog, the keydown fires on that outside element and bubbles through `document`, **not** through the dialog div — so `handleDialogKeyDown` never runs, and `dialogRef.current.contains(document.activeElement)` is effectively always `true` whenever this code executes. The guard is therefore a no-op in practice: it does not deliver the containment guarantee its comment promises.
+
+This is not a correctness bug (it never produces wrong behavior), so it is INFO, not a blocker. But it is worth noting that the IN-01 concern (focus escaping a boundary-only trap) is **not actually addressed** by this change.
+
+**Fix:** If true containment is desired, move the trap to a `document`-level `keydown` (or `focusin`) listener mounted while the dialog is open, so it can intercept Tab/focus originating outside the dialog. If the boundary-only trap is considered sufficient (it is, for the present always-focus-the-heading-on-open flows), drop the unreachable containment branch and its comment to avoid implying a guarantee the code does not provide.
+
+---
+
+_Reviewed: 2026-06-18T00:00:00Z_
+_Reviewer: Claude (gsd-code-reviewer)_
+_Depth: deep_
+_Re-review: IN-02 + IN-03 fixes confirmed clean; WR-01 fix regresses the focus-trap test suite (CR-01) and its IN-01 containment guard is inert. typecheck + lint pass; `pnpm test` FAILS (2 WR-07 tests)._
diff --git a/.planning/phases/17-ui-optimization-polish/17-SECURITY.md b/.planning/phases/17-ui-optimization-polish/17-SECURITY.md
new file mode 100644
index 0000000..eefcfe0
--- /dev/null
+++ b/.planning/phases/17-ui-optimization-polish/17-SECURITY.md
@@ -0,0 +1,92 @@
+---
+phase: 17
+slug: ui-optimization-polish
+status: verified
+threats_open: 0
+asvs_level: 1
+created: 2026-06-18
+---
+
+# Phase 17 — Security
+
+> Per-phase security contract: threat register, accepted risks, and audit trail.
+
+Phase 17 is a UI optimization & polish phase. Every plan carried a plan-time
+`` block (`register_authored_at_plan_time: true`). The work is
+client-side CSS/layout, static brand-asset wiring, and presentation-only React
+state — no new endpoints, no new authorization logic, no new runtime data flow.
+The single non-`accept` threat (logout wiring) reuses an endpoint already
+verified live in Phase 19.
+
+---
+
+## Trust Boundaries
+
+| Boundary | Description | Data Crossing |
+|----------|-------------|---------------|
+| Build tooling → repo (17-02) | `@vite-pwa/assets-generator` (+ sharp, sharp-ico) runs at design time and writes static images into `public/`. New devDependency = supply-chain surface. | Static image bytes; no secrets/PII |
+| Client UI → existing logout endpoint (17-05) | Sign out control calls the already-implemented, Phase-19-verified `POST /api/auth/local/logout` via `fetchLocalLogout()`. No new endpoint, no new auth logic. | Session cookie (cleared server-side) |
+| (none new) — 17-01, 17-03, 17-04, 17-06 | CSS-only restructure/offsets, static asset references, and presentation-only local `useState` (tab/toast). Server-side admin `403` enforcement unchanged. | None |
+
+---
+
+## Threat Register
+
+| Threat ID | Category | Component | Disposition | Mitigation | Status |
+|-----------|----------|-----------|-------------|------------|--------|
+| T-17-01-01 | Tampering | tokens.css selector restructure | accept | CSS custom properties carry no executable content and no user input; selector change cannot introduce injection. | closed |
+| T-17-02-SC | Tampering | npm devDependency install (@vite-pwa/assets-generator, sharp, sharp-ico) | accept | RESEARCH Package Legitimacy Audit rates all three Approved (official vite-pwa, 13-yr sharp, sharp-ico); no `[SLOP]`/unverified packages. devDependencies only; generated output is static images. | closed |
+| T-17-02-02 | Information disclosure | generated brand assets | accept | Assets are public-by-design brand images; no secrets or PII. | closed |
+| T-17-03-01 | Tampering | FAB/content CSS offsets | accept | Pure layout geometry via existing CSS custom property; no executable content, no input. | closed |
+| T-17-04-01 | Tampering | BrandSlot img / index.html links | accept | Logo img is decorative with empty `alt`; no `dangerouslySetInnerHTML` (T-05-24 invariant maintained); favicon/manifest entries point at committed static files. **Verified live:** BrandSlot renders ``, no `dangerouslySetInnerHTML` in source. | closed |
+| T-17-05-01 | Elevation of Privilege | logout control (D-07) | mitigate | `fetchLocalLogout()` clears the local-session cookie via the existing Phase-19-verified endpoint; client navigates to `/login` regardless of success/failure so a stale-cookie-with-logged-out-UI state cannot persist. **Verified:** `SettingsSheet.tsx:143-151` — `try { await fetchLocalLogout(); } catch {} onClose(); void navigate('/login');`. | closed |
+| T-17-05-02 | Tampering | sheet centering CSS (D-09) | accept | Position-only CSS branch; no input, no executable content. | closed |
+| T-17-06-01 | Tampering | toast message content (D-08) | accept | Toast copy is hardcoded JSX string constants ("Member added." / "Password reset."); no user-controlled content; no `dangerouslySetInnerHTML`. **Verified live:** toast rendered "Member added." from a `role=status` node on member creation. | closed |
+| T-17-06-02 | Elevation of Privilege | admin two-tab nav (D-10) | accept | Tab strip is presentation-only local `useState`; `isAdmin` nav visibility is UX-only — the real boundary is server-side `403` on `/api/admin/*` (unchanged). | closed |
+
+*Status: open · closed*
+*Disposition: mitigate (implementation required) · accept (documented risk) · transfer (third-party)*
+
+---
+
+## Accepted Risks Log
+
+| Risk ID | Threat Ref | Rationale | Accepted By | Date |
+|---------|------------|-----------|-------------|------|
+| AR-17-01 | T-17-01-01 | Static stylesheet selector restructure; zero runtime data flow. | Lucas Berger | 2026-06-18 |
+| AR-17-02 | T-17-02-SC | All new devDependencies Approved by RESEARCH package-legitimacy audit; design-time only. | Lucas Berger | 2026-06-18 |
+| AR-17-03 | T-17-02-02 | Brand assets are public-by-design; no secrets/PII. | Lucas Berger | 2026-06-18 |
+| AR-17-04 | T-17-03-01 | Pure CSS layout geometry; no input surface. | Lucas Berger | 2026-06-18 |
+| AR-17-05 | T-17-04-01 | Decorative img with empty alt; no `dangerouslySetInnerHTML`; committed static assets. | Lucas Berger | 2026-06-18 |
+| AR-17-06 | T-17-05-02 | Position-only CSS branch; no input/executable content. | Lucas Berger | 2026-06-18 |
+| AR-17-07 | T-17-06-01 | Hardcoded toast string constants; no user-controlled content. | Lucas Berger | 2026-06-18 |
+| AR-17-08 | T-17-06-02 | Presentation-only tab state; authorization enforced server-side (unchanged). | Lucas Berger | 2026-06-18 |
+
+*Accepted risks do not resurface in future audit runs.*
+
+---
+
+## Security Audit Trail
+
+| Audit Date | Threats Total | Closed | Open | Run By |
+|------------|---------------|--------|------|--------|
+| 2026-06-18 | 9 | 9 | 0 | /gsd-secure-phase (orchestrator, plan-time register verification) |
+
+Verification method: all 6 plans carried plan-time `` blocks
+(`register_authored_at_plan_time: true`). 8 `accept`-disposition threats are
+documented accepted risks; the 1 `mitigate` threat (T-17-05-01) had its
+mitigation verified present in `SettingsSheet.tsx`. Several dispositions were
+additionally corroborated at runtime during the Phase 17 UAT (playwright-cli):
+BrandSlot decorative img, hardcoded success toast, admin tab presentation-only
+state. `threats_open: 0` — short-circuit per workflow Step 3.
+
+---
+
+## Sign-Off
+
+- [x] All threats have a disposition (mitigate / accept / transfer)
+- [x] Accepted risks documented in Accepted Risks Log
+- [x] `threats_open: 0` confirmed
+- [x] `status: verified` set in frontmatter
+
+**Approval:** verified 2026-06-18
diff --git a/.planning/phases/17-ui-optimization-polish/17-UAT.md b/.planning/phases/17-ui-optimization-polish/17-UAT.md
new file mode 100644
index 0000000..3a7d887
--- /dev/null
+++ b/.planning/phases/17-ui-optimization-polish/17-UAT.md
@@ -0,0 +1,82 @@
+---
+status: complete
+phase: 17-ui-optimization-polish
+source:
+ - 17-01-SUMMARY.md
+ - 17-02-SUMMARY.md
+ - 17-03-SUMMARY.md
+ - 17-04-SUMMARY.md
+ - 17-05-SUMMARY.md
+ - 17-06-SUMMARY.md
+verification_method: playwright-cli (Chromium, host Vite @5173, Docker API/DB)
+started: 2026-06-18T18:26:00Z
+updated: 2026-06-18T18:31:00Z
+---
+
+## Current Test
+
+[testing complete]
+
+## Tests
+
+### 1. Cold Start Smoke Test
+expected: App boots and `/calendar` loads with live data — calendar grid, color legend, and primary controls render without console errors.
+result: pass
+evidence: PWA opened at http://localhost:5173/ → redirected to /calendar (dev-bypass). June 2026 grid rendered, color legend ("Dev User" #4A90D9, "Family" #F25C7A), New Event button + Today/nav present. 0 console errors. Docker API/MariaDB/Redis up.
+
+### 2. Login Page Branding — FamilySync logo (Plan 17-04)
+expected: Login page shows the approved family-house logo (BrandSlot), not the old "FS" text placeholder.
+result: pass
+evidence: /login renders `` at 48px. Old `aria-hidden` "FS" placeholder div is absent. `/logo.svg` serves 200 image/svg+xml.
+
+### 3. Favicon & Theme Color (Plan 17-04)
+expected: Browser tab favicon set (SVG + ICO + apple-touch) wired; warm-amber theme color applied.
+result: pass
+evidence: `` for /favicon.svg (image/svg+xml) + /favicon.ico + apple-touch-icon present. All of favicon.svg/favicon.ico/apple-touch-icon.png/icon-maskable-512.png fetch 200 with correct content-types. `` = #e8915a.
+
+### 4. Phone Layout Overlap Fix (Plan 17-03 / D-01)
+expected: At ≤767px, the New Event FAB sits above the fixed BottomTabBar (not occluded) and the color-legend chips remain fully visible.
+result: pass
+evidence: @390×844 — FAB bottom=764, BottomTabBar top=788 → FAB above bar with 24px gap (= --space-6). Color legend bottom=780 < nav top=788, visible:true, not occluded. Both chips ("Dev User", "Family") present. 0 console errors.
+
+### 5. Sign Out Control (Plan 17-05 / D-07)
+expected: Settings sheet exposes a reachable "Sign out" control.
+result: pass
+evidence: Settings dialog (opened from "Dev User — open settings") contains Account section, "Change password", and a "Sign out" button — all reachable.
+
+### 6. Settings Sheet Centering (Plan 17-05 / D-09)
+expected: On desktop, the settings sheet renders as a centered modal (not a bottom sheet).
+result: pass
+evidence: Settings dialog — position:fixed, width 480px, horizontal & vertical center offset = 0 on 1280×720, aria-modal="true".
+
+### 7. Modal Focus Trap (code-review CR-01 / WR-01 fix)
+expected: With a sheet open, Tab/Shift+Tab cycle focus within the dialog and never escape to background controls.
+result: pass
+evidence: Settings dialog (5 focusables). Tab from last ("Sign out") → wraps to "Close settings" (still inside). Shift+Tab from first → wraps to "Sign out" (still inside). Focus stayed contained both directions. Confirms the jsdom-tolerant visibility filter works correctly in a real (laid-out) browser — resolves the code-review human-verification flag.
+
+### 8. Admin Two-Tab Navigation (Plan 17-06 / D-10 + WR-02)
+expected: Admin page shows "Members & Accounts" / "Settings" tabs with full WAI-ARIA keyboard support (arrows wrap, Home/End).
+result: pass
+evidence: `role=tablist` with two `role=tab`s, "Members & Accounts" selected by default, tabpanels with regions. Keyboard: ArrowRight→Settings, ArrowRight wraps→Members, ArrowLeft→Settings, Home→Members, End→Settings. All transitions update aria-selected.
+
+### 9. Admin Success Toast (Plan 17-06 / D-08)
+expected: Creating a member shows a transient success toast announced to assistive tech.
+result: pass
+evidence: Filled + submitted the Add-member form (throwaway "ZZ Verify Toast"); a `role=status` aria-live="polite" toast read "Member added." Throwaway member removed from the dev DB afterward (verified 0 remaining).
+
+### 10. iOS Standalone PWA — install + home-screen icon + push
+expected: Installed-to-home-screen behavior and apple-touch/maskable icon appearance on a real iOS device.
+result: skipped
+reason: Genuinely device-only — cannot be driven by playwright-cli/Chromium (manifest is production-only and not injected in Vite dev). Icon assets and manifest config are verified at the asset/code level (Tests 2–3, code review). Real-device behavior remains a human checkpoint, already tracked in 17-VERIFICATION.md.
+
+## Summary
+
+total: 10
+passed: 9
+issues: 0
+skipped: 1
+pending: 0
+
+## Gaps
+
+[none — all automated checks passed; 1 device-only item deferred to existing human checkpoints]
diff --git a/.planning/phases/17-ui-optimization-polish/17-UI-SPEC.md b/.planning/phases/17-ui-optimization-polish/17-UI-SPEC.md
new file mode 100644
index 0000000..a636d2a
--- /dev/null
+++ b/.planning/phases/17-ui-optimization-polish/17-UI-SPEC.md
@@ -0,0 +1,851 @@
+---
+phase: 17
+slug: ui-optimization-polish
+status: draft
+shadcn_initialized: false
+preset: none
+created: 2026-06-18
+---
+
+# Phase 17 — UI Design Contract: UI Optimization & Polish
+
+> Visual and interaction contract for four bounded workstreams:
+> A — phone-layout overlap fix + small-viewport sweep,
+> B — branding assets (logo, favicon, PWA icon set),
+> C — theme-token groundwork (light-only, semantic layer),
+> D — UAT-surfaced UI fixes (logout control, admin success feedback,
+> dialog/sheet centering, admin two-tab nav).
+>
+> Generated by gsd-ui-researcher. Consume before planning or executing.
+
+---
+
+## Context & Approach
+
+This is a **polish + branding + theme-token-groundwork** phase on an **existing shipped**
+React 19 + Vite PWA. NOT greenfield, NOT a redesign. All design decisions extend the
+established token system in `apps/pwa/src/styles/tokens.css`.
+
+The no-hard-coded-values invariant is a hard constraint: **all hex/px values live in
+`tokens.css` as CSS custom properties; component files reference variables only.**
+
+The existing Phase 19 UI-SPEC (approved 2026-06-16) establishes the design-system
+baseline this phase builds on. No new tokens are introduced except the layout-chrome
+token added in Workstream A.
+
+---
+
+## Design System
+
+| Property | Value |
+|----------|-------|
+| Tool | none (existing CSS custom properties) |
+| Preset | not applicable |
+| Component library | none (hand-rolled inline `React.CSSProperties`, project convention) |
+| Icon library | lucide-react (already installed) |
+| Font | system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif (`var(--font-family-base)`) |
+
+Source: `apps/pwa/src/styles/tokens.css` — pre-populated from codebase scan.
+Pattern baseline: existing components (SettingsSheet, AdminPage, CredentialSheet, CalendarShell).
+
+---
+
+## Spacing Scale
+
+No new spacing tokens are introduced. Phase 17 uses the existing 4px-based scale unchanged.
+
+| Token | Value | Usage in this phase |
+|-------|-------|---------------------|
+| --space-1 | 4px | Icon gaps, tight label margins |
+| --space-2 | 8px | Tab strip inner gap, section label bottom margin |
+| --space-3 | 12px | Input row padding, tab content gap |
+| --space-4 | 16px | Toast horizontal padding, button padding, between-field gap |
+| --space-6 | 24px | Sheet/card padding, FAB clearance (base of calc expression) |
+| --space-8 | 32px | Section gap in admin two-tab content |
+| --space-12 | 48px | Page-level top/bottom padding |
+
+**New layout-chrome token (Workstream A):**
+
+```css
+/* Added to tokens.css :root alongside existing spacing scale */
+--bottom-chrome-h: calc(56px + env(safe-area-inset-bottom, 0px));
+```
+
+This single token is the source of truth for BottomTabBar height. It is consumed
+by the FAB offset (`bottom: calc(var(--bottom-chrome-h) + var(--space-6))`) and the
+phone content padding (`padding-bottom: var(--bottom-chrome-h)`). All three sites
+agree via one value.
+
+Exceptions:
+- FAB: `width: 56px; height: 56px` (Rule 1 minimum: ≥56×56px per layout.spec.ts). Not a
+ spacing-scale value — this is the FAB's own intrinsic size.
+- All interactive elements: `minHeight: 44px; minWidth: 44px` (WCAG 2.5.5 Touch Target).
+- Admin two-tab strip: tab items use `minHeight: 44px` to meet touch-target minimum.
+- Dialog/sheet (centered, D-09): `maxWidth: 480px` centered via
+ `left: 50%; transform: translateX(-50%)` (desktop); phone retains full-width
+ bottom-sheet `bottom: 0; left: 0; right: 0`.
+
+---
+
+## Typography
+
+All values from `tokens.css`. No new sizes or weights.
+
+| Role | Size | Weight | Line Height | Variable |
+|------|------|--------|-------------|----------|
+| Body | 15px | 400 | 1.5 | `var(--text-body-size)` / `var(--text-body-weight)` / `var(--text-body-line-height)` |
+| Label | 13px | 400 | 1.4 | `var(--text-label-size)` / `var(--text-label-weight)` / `var(--text-label-line-height)` |
+| Heading | 18px | 600 | 1.25 | `var(--text-heading-size)` / `var(--text-heading-weight)` / `var(--text-heading-line-height)` |
+| Display | 24px | 600 | 1.2 | `var(--text-display-size)` / `var(--text-display-weight)` / `var(--text-display-line-height)` |
+
+Usage in this phase:
+- Admin two-tab strip label: Label (13px/400/1.4) — inactive state; active state weight 600
+- Toast notification body: Label (13px/400/1.4)
+- Toast notification icon: 16px lucide icon
+- Logout button label: Body (15px/400/1.5) — matches existing SettingsSheet row pattern
+- Admin section content: inherits existing AdminPage typography (no change)
+
+---
+
+## Color
+
+All values from `tokens.css`. No new hex values in this phase.
+
+| Role | Value | Variable | Usage |
+|------|-------|----------|-------|
+| Dominant (60%) | #ffffff | `var(--color-surface)` | Page background, sheet background, tab strip background |
+| Secondary (30%) | #f7f7f8 | `var(--color-surface-dim)` | Tab strip inactive background, toast background |
+| Accent (10%) | #4a90d9 | `var(--color-member-0)` | Active tab indicator, active tab label, toast success icon, logout destructive separator |
+| Destructive | #dc2626 | `var(--color-destructive)` | Logout button text color (destructive row style) |
+
+Accent (`var(--color-member-0)`) reserved for:
+- Active tab bottom-border indicator in the admin two-tab strip (2px solid)
+- Active tab label text color
+- Toast icon for success feedback
+- Focus ring on all new interactive elements (`var(--color-focus-ring)`, 2px outline, 2px offset)
+
+Additional semantic colors (already in tokens.css — no new values):
+- `var(--color-border)` #e2e4e9 — tab strip bottom border, dialog border, toast border
+- `var(--color-border-subtle)` #eceef2 — separator above logout button in SettingsSheet
+- `var(--color-text-primary)` #111318 — tab labels (active), sheet headings
+- `var(--color-text-secondary)` #6b7280 — tab labels (inactive), toast body text
+- `var(--color-text-muted)` #9ca3af — section labels (uppercase, 13px/600/0.06em letter-spacing)
+- `var(--color-overlay)` rgba(0,0,0,0.32) — sheet/dialog backdrop
+
+### Brand accent checkpoint (answered question Q1)
+
+The accent direction is a **checkpoint decision** — both variants must be producible
+and comparable. The token restructure in Workstream C makes this a single-file swap.
+
+**Variant A — keep cool-blue:**
+- No token changes: `--color-member-0: #4a90d9`, `theme-color` stays `#4A90D9`
+
+**Variant B — warm rose/amber:**
+- `--color-member-0: #f25c7a` (rose, already the `--color-shared-family` value)
+ OR a warm amber `#e8915a` — one of these two candidates to compare at the checkpoint
+- Acceptance lens: warm/rounded/at-home; contrast ratio ≥3:1 on `#ffffff` (WCAG AA for
+ large text/UI components; the current rose #f25c7a passes at 3.0:1)
+- Files that flip for Variant B: `tokens.css` (`--color-member-0`), `index.html`
+ (`theme-color` meta content), `vite.config.ts` manifest (`theme_color`)
+- Note: `--sx-color-primary` already maps to `var(--color-member-0)` — it follows
+ the accent automatically
+
+**Default if checkpoint skipped:** keep Variant A (#4a90d9).
+
+Light-theme scope only. No dark palette values authored this phase.
+
+---
+
+## Workstream A — Phone-Layout Overlap Fix
+
+### Visual invariants (hard rules — must pass on iphone + pixel profiles)
+
+1. **FAB never intersects the BottomTabBar rect.** The FAB's bottom edge must be
+ at or above the BottomTabBar's top edge. On a 390×844 viewport with `safe-area-inset=0`:
+ BottomTabBar top edge = 844 - 56 = 788px. FAB bottom edge must be ≤ 788px.
+2. **Content fully scrollable above the bar.** The phone content area's scroll-bottom
+ must clear the BottomTabBar height so no content is occluded at rest. The colour-legend
+ chips ("Dev User" / member legend) and any bottom-of-page content must be visible
+ without needing to manually offset-scroll.
+3. **Safe-area-inset composes correctly.** On notched devices, `env(safe-area-inset-bottom)`
+ is non-zero; the token `calc(56px + env(safe-area-inset-bottom, 0px))` absorbs both the
+ bar height and the notch.
+4. **No horizontal overflow** — existing Rule 2 must continue to pass after the fix.
+5. **Tap targets preserved** — all existing ≥44px/≥56px assertions in layout.spec.ts
+ must pass after the fix.
+
+### Fix contract
+
+**New token added to `tokens.css` `:root`:**
+```css
+--bottom-chrome-h: calc(56px + env(safe-area-inset-bottom, 0px));
+```
+
+**FAB offset (CalendarShell.tsx):**
+- Before: `bottom: var(--space-6)` (~24px)
+- After: `bottom: calc(var(--bottom-chrome-h) + var(--space-6))`
+- The FAB sits `var(--space-6)` (24px) above the BottomTabBar top edge regardless
+ of safe-area-inset value.
+
+**Content padding (App.tsx `contentStyle`):**
+- Phone branch only (inside `if (phone)` or via `isPhone()` conditional)
+- Add: `paddingBottom: 'var(--bottom-chrome-h)'`
+- Desktop `contentStyle` is unchanged (no BottomTabBar on desktop).
+
+**BottomTabBar height (BottomTabBar.tsx):**
+- The bar's `height` calculation already uses `calc(56px + env(safe-area-inset-bottom, 0px))`
+ inline. This remains correct and unchanged — `--bottom-chrome-h` resolves to the same
+ value so both the token and the component agree. For consistency, the planner MAY choose
+ to reference the token from the bar's height property as well, but the visual invariant
+ is met either way.
+
+### Regression guard (D-02 decision)
+
+**Recommendation: add a permanent overlap CI assertion to `layout.spec.ts`.**
+
+Evidence basis: the defect was long-standing (Phase 04 — months), was invisible to desktop
+testing, and CI has iphone/pixel profiles running. Adding a geometry assertion to the
+existing spec is the lowest-regress mechanism. The assertion has no runtime cost beyond
+one `boundingBox()` call.
+
+**Assertion contract to add to `layout.spec.ts`:**
+
+```
+test('New Event FAB does not overlap BottomTabBar (A — phone only)', async ({ page }, testInfo) => {
+ test.skip(testInfo.project.name === 'desktop', 'Phone-only assertion');
+ await page.goto('/calendar');
+ const fab = page.getByRole('button', { name: 'New Event' });
+ const nav = page.getByRole('navigation', { name: 'Main navigation' });
+ const fabBox = await fab.boundingBox();
+ const navBox = await nav.boundingBox();
+ expect(fabBox).not.toBeNull();
+ expect(navBox).not.toBeNull();
+ // FAB bottom edge must be at or above the BottomTabBar top edge
+ expect(fabBox!.y + fabBox!.height).toBeLessThanOrEqual(navBox!.y);
+});
+```
+
+Run profiles: iphone + pixel (skipped on desktop).
+
+### Small-viewport sweep (D-01)
+
+After the FAB/content-padding fix, run the full `layout.spec.ts` suite on all three
+profiles. Fix any violations flagged (per D-01: checklist-driven, within no-behaviour-change
+boundary). Expected areas to verify:
+
+- Admin tab (when isAdmin=true): ensure it still meets ≥44px tap target after layout fix
+- ColorLegend chips: confirm they are fully visible (not occluded) once content padding is added
+- Any Phase 19 additions (LoginPage, SettingsSheet rows): no overflow on phone profiles
+
+---
+
+## Workstream B — Branding Assets
+
+### Brand brief (acceptance lens)
+
+All generated assets must feel: **warm / rounded / at-home / caricature-family vibes**.
+Not corporate, not geometric. The operator reviews and approves before assets are final.
+This is a **checkpoint** — the checkpoint fires before wiring is committed.
+
+### Logo asset contract
+
+| Asset | Dimensions | Format | Filename | Purpose |
+|-------|-----------|--------|----------|---------|
+| Logo mark | 192×192px (source; scale up for 512) | SVG preferred; PNG fallback | `logo.svg` or `logo.png` | BrandSlot `![]()
` + derivation source for icon set |
+| Favicon (modern) | 32×32px (scalable) | SVG | `favicon.svg` | Browser tab icon (modern browsers) |
+| Favicon (legacy) | 16×16 + 32×32 ICO | ICO | `favicon.ico` | Browser tab icon (legacy, IE/older Safari) |
+| PWA icon 192 | 192×192px | PNG | `icon-192.png` | PWA manifest — standard purpose |
+| PWA icon 512 | 512×512px | PNG | `icon-512.png` | PWA manifest — standard purpose (splash screen) |
+| PWA maskable 512 | 512×512px | PNG | `icon-maskable-512.png` | PWA manifest — maskable purpose (separate file) |
+| Apple touch icon | 180×180px | PNG | `apple-touch-icon.png` | iOS home screen icon |
+
+All files placed in `apps/pwa/public/`.
+
+**Maskable safe-zone rule:** The maskable icon (`icon-maskable-512.png`) must place
+the logo mark entirely within the 80% safe-zone circle (radius 204px on a 512×512 canvas,
+centered). The outer 10% on each edge may be cropped by the OS adaptive-icon mask. The
+current manifest incorrectly reuses `icon-512.png` (no safe zone) for the maskable
+purpose — this is the defect being fixed.
+
+### BrandSlot swap contract (D-05)
+
+**What changes in `BrandSlot.tsx`:**
+- Replace the placeholder `` with
+ ``
+- Apply the existing `--brand-logo-*` token dimensions to the `![]()
`:
+ `width: var(--brand-logo-size, 48px)`, `height: var(--brand-logo-size, 48px)`,
+ `borderRadius: var(--brand-logo-border-radius, 50%)`, aspect-ratio: 1/1
+- The `--brand-logo-bg` token (placeholder circle background) is no longer used
+ as a background when a real `![]()
` is present — it may be set to `transparent`
+ or removed from the element's style (keep the token in `tokens.css` for forward
+ compat if needed)
+- The `` with "FamilySync" text remains unchanged (screen readers still read the
+ name; the logo is purely decorative)
+- The tagline `
` remains unchanged
+- `LoginPage` layout is NOT touched — the seam contract from Phase 19 is honored
+
+**`--brand-logo-border-radius` update:**
+- The placeholder used `50%` (circle). The real logo may be a rounded square or have
+ its own shape baked in. Phase 17 sets this token to the shape that suits the logo:
+ - If the logo SVG is a circle/rounded shape by design: set to `0` (no extra clipping)
+ - If the logo is a square mark needing rounding: set to `12px` (warm/rounded brief)
+ - Final value determined when the logo is generated and reviewed at checkpoint
+
+**No `LoginPage` changes** — this is enforced by the Phase 19 seam contract.
+
+### `index.html` wiring contract
+
+Current state: one ``, one ``,
+no ``.
+
+After Phase 17:
+
+```html
+
+
+
+
+
+
+
+
+
+
+ FamilySync
+
+```
+
+`{ACCENT_HEX}` = the checkpoint-selected accent value (`#4A90D9` default or warm variant).
+
+The SVG favicon takes precedence in modern browsers; the ICO fallback covers legacy.
+Order matters: SVG first, ICO second (browsers pick the first supported type).
+
+### `vite.config.ts` manifest wiring contract
+
+Current state: 3 icon entries, last entry incorrectly reuses `icon-512.png` for maskable.
+
+After Phase 17:
+
+```ts
+icons: [
+ { src: '/icon-192.png', sizes: '192x192', type: 'image/png' },
+ { src: '/icon-512.png', sizes: '512x512', type: 'image/png' },
+ { src: '/icon-maskable-512.png', sizes: '512x512', type: 'image/png', purpose: 'maskable' },
+],
+```
+
+The `theme_color` value in the manifest must match the `index.html` `theme-color` meta
+and the checkpoint-selected accent. Change from `'#4A90D9'` to the chosen value at checkpoint.
+
+---
+
+## Workstream C — Theme-Token Groundwork
+
+### Contract
+
+**Groundwork only.** No dark palette values, no `prefers-color-scheme` media query wired
+to flip themes, no theme toggle UI. Light is and remains the only shipped theme.
+
+**Restructure `tokens.css` `:root` into a `data-theme`-capable pattern:**
+
+```css
+/* tokens.css — after restructure */
+
+:root,
+[data-theme="light"] {
+ /* All existing :root declarations move here verbatim. */
+ /* No value changes. */
+ /* ...all existing tokens... */
+}
+
+/* Dark theme stub — values intentionally absent (Phase 17 groundwork only).
+ Phase 999.20 fills these values and wires prefers-color-scheme. */
+/* [data-theme="dark"] { ... } */
+```
+
+The change is purely structural: `:root` is extended with `[data-theme="light"]` as a
+second selector on the same rule block. This allows a future `data-theme="dark"` attribute
+on `` to override without touching component files.
+
+**Schedule-X `--sx-color-*` overrides must remain working.** They are currently at the
+bottom of the same `:root` rule — after the restructure they remain inside the same
+combined `:root, [data-theme="light"]` rule block. The cascade order (after
+`@schedule-x/theme-default`) is unchanged; the overrides continue to win.
+
+**`--brand-logo-*` tokens** remain in the same `:root, [data-theme="light"]` block.
+Phase 17's logo swap updates their values here (e.g. `--brand-logo-border-radius`).
+
+**New token added in this workstream (in addition to Workstream A's
+`--bottom-chrome-h`):**
+
+No additional tokens beyond `--bottom-chrome-h` (Workstream A) and any updated
+`--brand-logo-*` values (Workstream B). The theme restructure introduces no new
+semantic names — only the selector change.
+
+**Invariant check:** after restructure, `grep -rn 'var(--' apps/pwa/src/components/`
+must show only `var(--token-name)` references, no hard-coded hex or px values in
+component files. This is the existing invariant; the restructure must not break it.
+
+---
+
+## Workstream D — UAT-Surfaced UI Fixes
+
+### D-07 — Logout control
+
+**Surfaces:** SettingsSheet (primary) and optionally AppNav phone header (secondary).
+
+**Primary placement: SettingsSheet.**
+A "Sign out" row is added below all existing SettingsSheet content, separated by a
+`var(--color-border-subtle)` horizontal rule (same divider pattern as the existing
+Account section). This mirrors the established section-separator pattern already used
+in SettingsSheet between Notifications and Account.
+
+Layout within SettingsSheet (bottom of sheet, after all other rows):
+```
+───────────────────────── ← 1px var(--color-border-subtle) divider, margin var(--space-4) top/bottom
+[LogOut icon 16px] Sign out ← full-width button, minHeight 44px, Body 15px/400, var(--color-destructive)
+```
+
+**Logout button style:**
+- `background: none; border: none; cursor: pointer`
+- Full width (`width: 100%`), `display: flex; alignItems: center; gap: var(--space-2)`
+- `LogOut` lucide icon (16px, `var(--color-destructive)`)
+- Label "Sign out" — Body (15px/400), `var(--color-destructive)`
+- `minHeight: 44px` (WCAG tap target)
+- `textAlign: left`, `padding: var(--space-2, 8px) 0`
+- On click: calls `fetchLocalLogout()` (already exists in `apps/pwa/src/api/client.ts:127`),
+ then navigates to `/login` (react-router `useNavigate` or `window.location.replace`)
+- No confirmation dialog — logout is not destructive in the "data loss" sense for a
+ household app; the user is simply signed out and can re-sign in immediately
+
+**Accessibility:**
+- `aria-label="Sign out"` on the button
+- Icon is `aria-hidden="true"`
+- Standard focus ring (`var(--color-focus-ring)`, 2px outline, 2px offset)
+
+**No backend work required** — `fetchLocalLogout()` calls the existing
+`POST /api/auth/local/logout` endpoint.
+
+### D-08 — Admin success feedback
+
+**Surfaces:** AdminPage.tsx — create-member and reset-password flows.
+
+**Toast notification design contract:**
+
+A lightweight transient toast appears after a successful admin action. Reuses the
+existing `SyncStateToast` visual pattern (already in the codebase) if possible; if not,
+implement a minimal inline variant.
+
+Toast style:
+- Position: `fixed; bottom: calc(var(--bottom-chrome-h) + var(--space-4))` on phone;
+ `fixed; bottom: var(--space-6); left: 50%; transform: translateX(-50%)` on desktop
+- Background: `var(--color-surface)`, border: `1px solid var(--color-border)`,
+ `borderRadius: var(--space-2)`, `boxShadow: 0 2px 8px rgba(0,0,0,0.12)`
+- Padding: `var(--space-3) var(--space-4)` (12px 16px)
+- Content: `CheckCircle` (16px, `var(--color-member-0)`) + toast message text (Label 13px/400,
+ `var(--color-text-primary)`)
+- Auto-dismiss: after 3 seconds (no dismiss button needed for a household app)
+- `role="status"`, `aria-live="polite"` — screen readers announce the success
+
+**Toast copy variants:**
+
+| Action | Toast copy |
+|--------|------------|
+| Create member success | "Member added." |
+| Reset password success | "Password reset." |
+
+**Placement note:** the toast bottom offset on phone uses `var(--bottom-chrome-h)`
+(introduced in Workstream A) so it clears the BottomTabBar.
+
+### D-09 — Dialog/sheet centering fix
+
+**Surfaces:** SettingsSheet, ChangePasswordSheet, LinkOidcSheet in SettingsSheet.tsx;
+AdminPage CredentialSheet; AdminPage reset-password sheet (Surface 11B).
+
+**Problem:** sheets currently use `bottom: 0; left: 0; right: 0; maxWidth: 480px;
+margin: 0 auto` — on desktop this places them bottom-center, not truly centered.
+
+**Fix contract:**
+
+Phone (`≤767px`): bottom-sheet behavior is correct and intentional. No change.
+- `position: fixed; bottom: 0; left: 0; right: 0; borderRadius: 12px 12px 0 0`
+
+Desktop (`≥768px`): centered modal.
+- `position: fixed; top: 50%; left: 50%; transform: translate(-50%, -50%)`
+- `maxWidth: 480px; width: calc(100% - var(--space-8)); borderRadius: 12px`
+- `maxHeight: calc(100dvh - var(--space-8)); overflowY: auto`
+- Remove `bottom: 0; left: 0; right: 0; margin: 0 auto; borderRadius: 12px 12px 0 0`
+- Box shadow: `0 8px 32px rgba(0,0,0,0.18)` (deeper shadow for centered modal feel)
+
+**Breakpoint:** use `window.matchMedia('(max-width: 767px)')` — same as `isPhone()`
+in the existing codebase. The behavior is determined at render time; no CSS-only
+media query approach is used (consistent with project pattern of inline React styles).
+
+**Applies to all sheets:** SettingsSheet, ChangePasswordSheet, LinkOidcSheet,
+CredentialSheet, AdminPage reset-password sheet. Each gets a phone/desktop style
+branch for its outer ``.
+
+**Backdrop:** unchanged — `position: fixed; inset: 0; background: var(--color-overlay)`.
+
+**Verification:** confirm via playwright-cli at both 390×844 (phone — bottom sheet) and
+1280×720 (desktop — centered modal) before merging.
+
+### D-10 — Admin two-tab navigation
+
+**Surface:** AdminPage.tsx
+
+**Structure:** horizontal tab strip at the top of the AdminPage content column,
+replacing the current single-page long-scroll layout.
+
+**Two tabs:**
+
+| Tab | Label | Contents |
+|-----|-------|----------|
+| Tab 1 | "Members & Accounts" | MEMBERS section (credential management) + LOCAL ACCOUNTS section (create member + reset-password) |
+| Tab 2 | "Settings" | SHARED CALENDAR section + TIMEZONE section |
+
+**Tab strip visual contract:**
+
+```
+┌────────────────────────────────────────────────────────────┐
+│ [Members & Accounts] [Settings] │
+│ ─────────────────── 2px active border-bottom │
+│ 1px var(--color-border-subtle) full-width rule below strip │
+└────────────────────────────────────────────────────────────┘
+```
+
+Tab strip container:
+- `display: flex; borderBottom: 1px solid var(--color-border-subtle)`
+- `marginBottom: var(--space-6)` (24px gap before first section)
+
+Individual tab button:
+- `background: none; border: none; cursor: pointer`
+- `padding: var(--space-3) var(--space-4)` (12px 16px)
+- `minHeight: 44px` (WCAG tap target)
+- `fontSize: var(--text-label-size, 13px)` (13px)
+- Inactive: `fontWeight: 400; color: var(--color-text-secondary); borderBottom: 2px solid transparent`
+- Active: `fontWeight: 600; color: var(--color-text-primary); borderBottom: 2px solid var(--color-member-0)`
+- `transition: color 0.1s ease, border-color 0.1s ease`
+- `fontFamily: var(--font-family-base)`
+
+**Accessibility (roving tabindex / ARIA tabs pattern):**
+- Tab strip container: `role="tablist"`
+- Each tab button: `role="tab"`, `aria-selected={isActive}`,
+ `aria-controls="{panel-id}"`, `id="{tab-id}"`
+- Inactive tabs: `tabIndex={-1}` (roving tabindex — only active tab is in tab order)
+- Active tab: `tabIndex={0}`
+- Keyboard navigation within the tablist: `ArrowLeft`/`ArrowRight` move focus + activate tab
+- Tab panel: `role="tabpanel"`, `aria-labelledby="{tab-id}"`, `id="{panel-id}"`
+ Each panel receives `tabIndex={0}` so keyboard users can enter the panel content after
+ the tablist
+
+**Tab IDs:**
+- `id="admin-tab-members"` / `aria-controls="admin-panel-members"`
+- `id="admin-tab-settings"` / `aria-controls="admin-panel-settings"`
+
+**Default active tab on mount:** "Members & Accounts" (Tab 1).
+
+**Phone behavior:** the two-tab strip eliminates the long-scroll on phone. Each tab's
+content replaces the other. The tab labels are short enough that both fit without
+overflow at 390px width (verify via playwright-cli). No horizontal scroll on the
+tab strip.
+
+**No new tokens** — the tab strip uses only existing spacing, color, and typography tokens.
+
+---
+
+## Copywriting Contract
+
+### Workstream D new copy
+
+| Element | Copy |
+|---------|------|
+| Logout button label | "Sign out" |
+| Logout button aria-label | "Sign out" |
+| Toast — create member success | "Member added." |
+| Toast — reset password success | "Password reset." |
+| Admin tab 1 label | "Members & Accounts" |
+| Admin tab 2 label | "Settings" |
+
+### Copywriting rules (inherited from Phase 19)
+
+- Never use "Authelia" in any user-facing copy.
+- Admin copy ("Reset password", "Sign out") is direct — admins are comfortable with the vocabulary.
+- End-user copy is warm and low-friction.
+- "Sign out" (not "Log out" or "Logout") — consistent with friendly household tone.
+- Toast copy is declarative past-tense ("Member added.") not celebratory — keeps the
+ admin UI professional.
+
+### Empty states
+
+No new empty states introduced by Phase 17. The existing AdminPage empty states
+(no members / no calendars synced) remain unchanged.
+
+### Error states
+
+No new error states introduced by Phase 17. Workstream D's logout has no error path
+(if the API call fails, the user is navigated to `/login` regardless —
+`fetchLocalLogout()` is fire-and-best-effort for a cookie clear).
+
+---
+
+## Surface Architecture
+
+### Surface A-1 — Phone layout (App.tsx `contentStyle`, phone branch)
+
+After fix:
+```ts
+const contentStyle: React.CSSProperties = {
+ flex: 1,
+ minWidth: 0,
+ minHeight: 0,
+ display: 'flex',
+ flexDirection: 'column',
+ overflow: 'hidden',
+ position: 'relative',
+ // Phone-only: reserve space for the fixed BottomTabBar
+ ...(phone ? { paddingBottom: 'var(--bottom-chrome-h)' } : {}),
+};
+```
+
+The `overflow: 'hidden'` on the outer contentStyle traps scroll. The inner route content
+(CalendarShell, ListsIndex, etc.) must handle its own scroll; the padding-bottom ensures
+their scrollable area clears the tab bar.
+
+### Surface A-2 — New Event FAB (CalendarShell.tsx)
+
+After fix (phone-only FAB style):
+```ts
+// Phone FAB positioning — clears BottomTabBar + adds breathing room
+position: 'fixed',
+bottom: 'calc(var(--bottom-chrome-h) + var(--space-6))',
+right: 'var(--space-6)',
+// size unchanged
+width: '56px',
+height: '56px',
+```
+
+### Surface B-1 — BrandSlot (BrandSlot.tsx)
+
+After swap:
+```tsx
+
+
+ {/* and
tagline unchanged */}
+
+```
+
+`--brand-logo-border-radius` updated in `tokens.css` to suit the logo shape
+(determined at checkpoint; likely `12px` for warm/rounded brief or `50%` if circular).
+
+### Surface C-1 — tokens.css structural change
+
+Before:
+```css
+:root { /* all tokens */ }
+```
+
+After:
+```css
+:root,
+[data-theme="light"] { /* all tokens, values unchanged */ }
+/* [data-theme="dark"] { ... } intentionally absent — Phase 999.20 fills this */
+```
+
+### Surface D-1 — SettingsSheet logout row
+
+After the existing Account section divider (or at the bottom of the sheet):
+```tsx
+{/* Sign out */}
+
+
+```
+
+`handleSignOut` calls `fetchLocalLogout()` then navigates to `/login`.
+
+### Surface D-2 — Admin two-tab strip (AdminPage.tsx)
+
+Rendered above all AdminPage content, inside the content column:
+- `` containing two `
+ {(['members', 'settings'] as const).map((id) => (
+
+ ))}
+
+
+ {/* active panel content */}
+
+```
+
+`handleTabKeyDown` moves focus + activates on ArrowLeft/ArrowRight using `document.querySelector('[role="tab"]')` siblings or a ref array.
+
+### Anti-Patterns to Avoid
+
+- **Do not add `data-theme="light"` attribute to ``** in Phase 17. The groundwork is CSS-only; the attribute is added by Phase 999.20 when the toggle is shipped. The combined `:root, [data-theme="light"]` selector means light tokens apply regardless — no attribute needed for light-only.
+- **Do not use `pwa-asset-generator` (the older v8 package)** — it uses Puppeteer/Chromium and is not the official vite-pwa project tool.
+- **Do not run `@vite-pwa/assets-generator` with `overrideManifestIcons: true`** in this project — the manifest is manually maintained in `vite.config.ts`; auto-overwrite would stomp the explicit entries.
+- **Do not modify `LoginPage.tsx`** when swapping BrandSlot internals — the seam contract from Phase 19 explicitly forbids layout changes to LoginPage.
+- **Do not use `dangerouslySetInnerHTML`** in any new components (T-05-24 invariant, enforced project-wide).
+
+---
+
+## Don't Hand-Roll
+
+| Problem | Don't Build | Use Instead | Why |
+|---------|-------------|-------------|-----|
+| Maskable icon safe-zone padding | Custom canvas/sharp script | `@vite-pwa/assets-generator` minimal-2023 preset | Safe-zone math, ICO encoding, maskable background fill already implemented and tested |
+| ICO encoding | Custom bit-packing | `sharp-ico` (dependency of assets-generator) | ICO is a non-trivial multi-image container format; sharp-ico handles it correctly |
+| Toast state management | Custom event bus | Local `useState` + `setTimeout` in AdminPage | Single-component use; TanStack Query `onSuccess` callback feeds the state directly |
+| ARIA tabs keyboard nav | Custom focus-trap | Roving tabindex pattern (standard ARIA spec) | Two tabs; ArrowLeft/ArrowRight with `tabIndex={-1}` on inactive tabs is 10 lines of code |
+
+---
+
+## Code Surface Audit (Fix Surfaces Verified Against Source)
+
+All files and symbols confirmed to exist as described in CONTEXT.md and UI-SPEC. No drift found.
+
+### Workstream A
+
+| File | Finding | Status |
+|------|---------|--------|
+| `apps/pwa/src/App.tsx` | `contentStyle` (lines 155–163): no `paddingBottom`; phone split done via `isPhone()` function defined at line 64 | CONFIRMED — `paddingBottom` absent, fix is additive |
+| `apps/pwa/src/components/BottomTabBar.tsx` | `height: 'calc(56px + env(safe-area-inset-bottom, 0px))'` at line 72; `position: fixed; bottom: 0; z-index: 200` | CONFIRMED — matches UI-SPEC description exactly |
+| `apps/pwa/src/components/CalendarShell.tsx` | FAB at lines 463–484: `position: 'fixed', bottom: 'var(--space-6)', right: 'var(--space-6)'` — the defect | CONFIRMED — FAB bottom is `var(--space-6)` (24px), not clearing the 56px bar |
+| `apps/pwa/e2e/layout.spec.ts` | Existing assertions cover tap targets, overflow, in-viewport; no overlap assertion yet | CONFIRMED — overlap assertion is missing; file is the correct home for it |
+| `apps/pwa/playwright.config.ts` | Three profiles: iphone (390×844 WebKit), pixel (412×915 Chromium), desktop (1280×720 Chrome) | CONFIRMED |
+
+### Workstream B
+
+| File | Finding | Status |
+|------|---------|--------|
+| `apps/pwa/public/` | Three stubs: `apple-touch-icon.png` (617 B), `icon-192.png` (699 B), `icon-512.png` (4086 B). No `favicon.ico`, no `favicon.svg`, no `icon-maskable-512.png` | CONFIRMED — stubs only; all need replacement |
+| `apps/pwa/index.html` | One ``, one ``, no `` | CONFIRMED — favicon links entirely absent |
+| `apps/pwa/vite.config.ts` | `icons` array (lines 38–42): 3 entries; last entry incorrectly reuses `icon-512.png` for maskable purpose | CONFIRMED — `{ src: '/icon-512.png', sizes: '512x512', type: 'image/png', purpose: 'maskable' }` is the defect |
+| `apps/pwa/src/components/BrandSlot.tsx` | Placeholder `` with `--brand-logo-*` token consumption; `FamilySync
` and tagline `` present | CONFIRMED — swap internals only; seam is correct | +| `sharp` in monorepo | Not installed anywhere in monorepo — not in `apps/pwa/package.json`, `apps/api/package.json`, or root; `node_modules/sharp` absent | CONFIRMED — must install `@vite-pwa/assets-generator` as devDependency | + +### Workstream C + +| File | Finding | Status | +|------|---------|--------| +| `apps/pwa/src/styles/tokens.css` | Single `:root { ... }` block with all tokens including `--brand-logo-*` tokens and Schedule-X `--sx-color-*` overrides at bottom | CONFIRMED — restructure is selector-only; token values unchanged | + +### Workstream D + +| Symbol | File | Line | Status | +|--------|------|------|--------| +| `fetchLocalLogout()` | `apps/pwa/src/api/client.ts` | 124–134 | CONFIRMED — `POST /api/auth/local/logout`, `credentials: 'include'`, `redirect: 'manual'`; handles opaqueredirect | +| `SyncStateToast` visual pattern | `apps/pwa/src/components/SyncStateToast.tsx` | 1–60 | CONFIRMED — toast renders with `role="status"` or `role="alert"`, bottom-center position; reuse the visual style | +| `AdminPage.tsx` | `apps/pwa/src/routes/AdminPage.tsx` | 1–80 | CONFIRMED — `useMutation` imports from TanStack Query present; `sectionLabelStyle` defined; currently single-scroll layout | +| `SettingsSheet.tsx` sheet structure | `apps/pwa/src/components/SettingsSheet.tsx` | 1–60 | CONFIRMED — `role="dialog"` pattern exists; `LogOut` lucide icon NOT yet imported (needs adding) | + +--- + +## Common Pitfalls + +### Pitfall 1: Maskable Icon Without Safe Zone +**What goes wrong:** Reusing the non-maskable 512 PNG as the maskable icon (the current defect in `vite.config.ts`) — the logo gets cropped at the edges on Android adaptive icons. +**Why it happens:** The manifest `purpose: 'maskable'` flag is easy to add without understanding that maskable requires the logo to be inset within the 80% safe zone. +**How to avoid:** Generate a separate `icon-maskable-512.png` using `@vite-pwa/assets-generator` which pads the logo to the safe zone automatically with a solid background fill. +**Warning signs:** `maskable` and `any` entries pointing to the same file in the manifest. + +### Pitfall 2: FAB Position Regression on Desktop +**What goes wrong:** Applying `paddingBottom: 'var(--bottom-chrome-h)'` to `contentStyle` unconditionally — on desktop, this adds 56px+ of empty space below content where there is no BottomTabBar. +**Why it happens:** `contentStyle` in `App.tsx` is shared across phone and desktop layouts. +**How to avoid:** Apply the padding-bottom only in the phone branch — `...(phone ? { paddingBottom: 'var(--bottom-chrome-h)' } : {})`. The existing `phone` boolean (computed from `isPhone()` at line 84 of `App.tsx`) is the correct gate. +**Warning signs:** layout.spec.ts desktop profile shows content area with unexpected bottom padding. + +### Pitfall 3: Schedule-X Token Override Cascade Break +**What goes wrong:** Moving the `--sx-color-*` overrides OUTSIDE the `:root, [data-theme="light"]` block during the tokens.css restructure — they no longer override the `@schedule-x/theme-default` values. +**Why it happens:** The tokens.css comment says "must come after the theme-default import" (import order in main.tsx), but that refers to the stylesheet import order. If the overrides move to a new rule block that comes before `:root` in cascade order (e.g., a bare `[data-theme="light"]` block without `:root`), specificity changes could affect the Schedule-X defaults. +**How to avoid:** Keep ALL tokens — including `--sx-color-*` — inside the combined `:root, [data-theme="light"]` block. Do not split them across multiple rule blocks. +**Warning signs:** Schedule-X calendar grid loses custom colors (event chips revert to the Schedule-X default blue/green). + +### Pitfall 4: `fetchLocalLogout` Error Swallowed on Navigate +**What goes wrong:** If `fetchLocalLogout()` rejects (e.g., server error, network timeout), a naive `await fetchLocalLogout(); navigate('/login')` would navigate away without clearing the cookie. The user would believe they logged out but the session cookie may still be valid. +**Why it happens:** Async error propagation on a fire-and-forget logout. +**How to avoid:** Wrap in `try/catch` and call `navigate('/login')` in both the `try` (success) and `catch` (failure) branches — the UI-SPEC documents this as "fire-and-best-effort for a cookie clear." The server already handles the 401 case by expiring the cookie; the navigate is always safe. +**Warning signs:** `fetchLocalLogout` throws and the SettingsSheet stays open. + +### Pitfall 5: `--brand-logo-border-radius` Not Updated +**What goes wrong:** After swapping the BrandSlot `
` for an `![]()
`, the `--brand-logo-border-radius: 50%` token (currently in tokens.css) clips the `![]()
` into a circle regardless of the logo's own shape.
+**Why it happens:** The token was set for the initials-circle placeholder; it is inherited by the `![]()
` element via the BrandSlot swap contract.
+**How to avoid:** After the logo art is approved at the checkpoint, update `--brand-logo-border-radius` in tokens.css to match the logo shape (likely `12px` for a warm/rounded brief, or `0` if the SVG draws its own shape).
+**Warning signs:** The real logo looks cropped or forced into a circle shape in the login view.
+
+---
+
+## Runtime State Inventory
+
+SKIPPED — this is a greenfield polish phase, not a rename/refactor/migration. No stored data, live service config, OS-registered state, secrets, or build artifacts carry strings being changed.
+
+---
+
+## Environment Availability
+
+| Dependency | Required By | Available | Version | Fallback |
+|------------|------------|-----------|---------|----------|
+| Node.js | Asset generation script | ✓ | 22 LTS | — |
+| pnpm | Monorepo package management | ✓ | (installed) | — |
+| `@vite-pwa/assets-generator` | Workstream B icon generation | ✗ (not installed) | 1.0.2 (latest) | Install as devDependency in `apps/pwa` |
+| `sharp` | Transitive dep of assets-generator | ✗ (not installed) | 0.35.1 (latest) | Installed automatically with assets-generator |
+| ImageMagick `convert` | Alternative ICO generation | ✗ | — | Not needed — using assets-generator instead |
+| Playwright | Workstream A regression assertions | ✓ | 1.60.0 | — |
+| Vitest | Unit tests | ✓ | ^4.1.8 | — |
+
+**Missing dependencies with no fallback:** none
+**Missing dependencies with fallback:** `@vite-pwa/assets-generator` — install as devDependency in `apps/pwa`.
+
+---
+
+## Validation Architecture
+
+### Test Framework
+
+| Property | Value |
+|----------|-------|
+| E2E Framework | Playwright 1.60.0 |
+| Unit Framework | Vitest ^4.1.8 |
+| E2E Config | `apps/pwa/playwright.config.ts` |
+| Unit Config | `apps/pwa/vitest.config.ts` |
+| E2E quick run | `pnpm --filter @familysync/pwa exec playwright test --project=pixel layout.spec.ts` |
+| E2E full suite | `pnpm --filter @familysync/pwa test:e2e` |
+
+### Phase Requirements → Validation Map
+
+| Workstream | Behavior | Test Type | Command / Method | Automated? |
+|------------|----------|-----------|------------------|------------|
+| A — FAB overlap | FAB bottom edge ≤ BottomTabBar top edge on iphone/pixel | Playwright geometry assertion | New assertion in `layout.spec.ts` | CI (iphone + pixel profiles) |
+| A — Content clearance | Color legend chips visible; content scrollable above bar | Playwright + playwright-cli sweep | `layout.spec.ts` full suite + manual scroll | Partially automated |
+| A — No horizontal overflow | `scrollWidth ≤ clientWidth` after fix | Playwright Rule 2 | Existing `layout.spec.ts` Rule 2 tests | CI (all profiles) |
+| A — Tap targets preserved | All existing ≥44px/≥56px assertions pass | Playwright Rule 1 | Existing `layout.spec.ts` Rule 1 tests | CI (all profiles) |
+| B — Asset existence | All 7 files present in `apps/pwa/public/` | Shell `ls` / existence check | `ls apps/pwa/public/{favicon.svg,favicon.ico,icon-192.png,icon-512.png,icon-maskable-512.png,apple-touch-icon.png,logo.svg}` | CI gate / Wave 0 check |
+| B — Manifest references resolve | PWA manifest icons all 200 in browser | Playwright | `page.goto('/')` then check `navigator.serviceWorker` / devtools manifest tab | playwright-cli |
+| B — Maskable dimensions | `icon-maskable-512.png` is exactly 512×512 | Node.js check using `sharp` | `node -e "require('sharp')('/path/icon-maskable-512.png').metadata().then(m => console.log(m.width, m.height))"` | Scripted |
+| B — ICO is not zero-byte | `favicon.ico` exists and is >100 bytes | Shell | `test $(wc -c < apps/pwa/public/favicon.ico) -gt 100` | CI gate |
+| B — Visual logo approval | Logo meets warm/rounded brief | Human review | playwright-cli screenshot + operator approval | Human checkpoint (checkpoint:human-verify) |
+| C — No hard-coded values in components | `grep` finds no hex/px literals in component files | `grep` | `grep -rn '#[0-9a-fA-F]\{3,6\}\|[0-9]\+px' apps/pwa/src/components/ apps/pwa/src/routes/` | CI gate |
+| C — Schedule-X colors unchanged | Calendar grid retains custom colors post-restructure | Playwright + playwright-cli | playwright-cli visual sweep of /calendar | playwright-cli |
+| C — Build succeeds | TypeScript + Vite build exits 0 | Build | `pnpm --filter @familysync/pwa build` | CI |
+| D-07 — Logout control renders | "Sign out" button visible in SettingsSheet | Playwright + playwright-cli | playwright-cli: open settings sheet, confirm button visible | playwright-cli |
+| D-07 — Logout wiring | `fetchLocalLogout` called on click; navigate to /login | Playwright interaction | playwright-cli: click Sign out, confirm redirect to /login | playwright-cli |
+| D-08 — Admin create toast | "Member added." toast appears after create success | Playwright interaction | playwright-cli: create member, confirm toast | playwright-cli (admin session) |
+| D-08 — Admin reset toast | "Password reset." toast appears after reset success | Playwright interaction | playwright-cli: reset password, confirm toast | playwright-cli (admin session) |
+| D-08 — Toast auto-dismiss | Toast disappears after ~3 seconds | Playwright interaction | playwright-cli: wait 3.5s after toast appears | playwright-cli |
+| D-09 — Dialog desktop centering | Sheet renders centered (`top: 50%; left: 50%; transform`) on desktop | Playwright geometry | playwright-cli at 1280×720: open SettingsSheet, confirm geometry | playwright-cli (desktop) |
+| D-09 — Dialog phone bottom-sheet | Sheet renders at bottom on phone | Playwright geometry | playwright-cli at 390×844: open SettingsSheet, confirm bottom-sheet | playwright-cli (phone) |
+| D-10 — Admin tabs render | Two-tab strip visible with correct labels | Playwright | playwright-cli at /admin: confirm "Members & Accounts" and "Settings" tabs | playwright-cli (admin session) |
+| D-10 — Admin tabs keyboard | ArrowLeft/ArrowRight switches tabs | Playwright keyboard | playwright-cli: focus tab, ArrowRight, confirm second tab active | playwright-cli |
+| D-10 — Admin tab ARIA | `role="tablist"`, `role="tab"`, `aria-selected`, `role="tabpanel"` present | Playwright | `page.getByRole('tablist')`, `page.getByRole('tab', {name: ...})` | Playwright test (add to layout.spec.ts or admin.spec.ts) |
+
+### Sampling Rate
+
+- **Per task commit:** `pnpm --filter @familysync/pwa exec playwright test --project=pixel layout.spec.ts` (fast; phone profile covers the primary fix geometry)
+- **Per wave merge:** `pnpm --filter @familysync/pwa test:e2e` (full 3-profile suite)
+- **Phase gate:** Full Playwright suite green + playwright-cli visual sweeps passed + human logo approval received before `/gsd-verify-work`
+
+### Wave 0 Gaps
+
+- [ ] The overlap regression assertion does not exist yet — add to `apps/pwa/e2e/layout.spec.ts` (Workstream A)
+- [ ] Admin tab ARIA assertions — add to a new `apps/pwa/e2e/admin.spec.ts` or append to `layout.spec.ts` (Workstream D-10)
+- [ ] Asset existence check script — can be a Wave 0 npm script or inline CI step
+
+---
+
+## Security Domain
+
+`security_enforcement: true` in `.planning/config.json`. ASVS level 1.
+
+| ASVS Category | Applies | Control |
+|---------------|---------|---------|
+| V2 Authentication | No — no auth changes; logout calls existing endpoint | Existing endpoint (`POST /api/auth/local/logout`) already verified in Phase 19 |
+| V3 Session Management | Indirect — logout clears session cookie | `fetchLocalLogout` posts to existing endpoint; cookie clearance is server-side |
+| V4 Access Control | No — admin page UX gating unchanged; server 403 unchanged | No new routes or authorization changes |
+| V5 Input Validation | Minimal — admin tab state, toast message strings are hardcoded constants | No user input reaches new UI surfaces except the existing admin forms (unchanged) |
+| V6 Cryptography | No | No new crypto |
+
+### Known Threat Patterns
+
+| Pattern | STRIDE | Mitigation |
+|---------|--------|------------|
+| XSS via toast message content | Spoofing/Tampering | Toast copy is hardcoded JSX string constants ("Member added." / "Password reset.") — no user-controlled content; T-05-24 invariant maintained |
+| Session fixation after logout | Elevation of Privilege | `fetchLocalLogout` clears the `local-session` cookie server-side; client navigates to `/login` regardless of success/failure |
+| Admin route access without OIDC | Elevation of Privilege | No change — `isAdmin` check in App.tsx is UX-only; server enforces 403 on all `/api/admin/*` (unchanged) |
+
+---
+
+## Assumptions Log
+
+| # | Claim | Section | Risk if Wrong |
+|---|-------|---------|---------------|
+| A1 | `@vite-pwa/assets-generator` `minimal-2023` preset generates a maskable icon with the logo properly inset in the 80% safe zone (not just solid-color fill) | Standard Stack / Asset Toolchain | If the preset only fills the 512×512 with a background and does not inset the logo, the maskable icon will have the logo cropped on adaptive-icon masks — require custom `padding` option in config |
+| A2 | The 48×48 single-size `favicon.ico` from `@vite-pwa/assets-generator` is adequate for this household app (vs. 16+32 multi-size) | Standard Stack | Negligible visual risk — legacy browsers (IE, old Safari) may show a slightly blurry icon; no functional impact for modern browsers which prefer `favicon.svg` |
+| A3 | `sharp` SUS verdict is a false positive due to version recency window; the package is safe to use | Package Legitimacy Audit | Near-zero risk — 13-year-old package, 65.6M weekly downloads, lovell/sharp well-known author; risk if the seam has additional signals not surfaced in the output |
+| A4 | Hand-authoring SVG for the logo (warm/rounded family vibes) in-phase by Claude produces a logo that meets the brand brief to the operator's satisfaction at the checkpoint | Workstream B | If operator rejects the generated logo, the phase stalls at the checkpoint; the plan must include a checkpoint:human-verify before assets are wired in |
+
+---
+
+## Open Questions
+
+1. **`@vite-pwa/assets-generator` maskable padding behavior**
+ - What we know: the `minimal-2023` preset produces a `maskable` 512×512 PNG with a white background; the documentation describes it as "safe zone padded"
+ - What's unclear: whether the preset option allows overriding the background color to a warm brand color (e.g., `#fef3ec`) matching the logo palette, vs. always producing white
+ - Recommendation: use white background for the maskable icon in Wave 1; if the operator wants a brand-color background, add a `maskableIconOptions` config in `pwa-assets.config.ts` at the checkpoint
+
+2. **Brand accent checkpoint outcome**
+ - What we know: two candidates (Variant A: `#4a90d9` cool blue; Variant B: warm rose `#f25c7a` or amber `#e8915a`) per UI-SPEC §Color
+ - What's unclear: which the operator will select after seeing the logo
+ - Recommendation: produce the logo, show both accent variants in context (the token restructure in C makes it a one-line swap), checkpoint before committing accent to `index.html`/`vite.config.ts`/`tokens.css`
+
+---
+
+## Sources
+
+### Primary (HIGH confidence — official project documentation)
+- `apps/pwa/src/App.tsx` — `contentStyle`, `isPhone()`, phone/desktop branch; confirmed missing `paddingBottom` [VERIFIED: codebase grep]
+- `apps/pwa/src/components/CalendarShell.tsx:469–470` — FAB `bottom: 'var(--space-6)'` defect [VERIFIED: codebase grep]
+- `apps/pwa/src/components/BottomTabBar.tsx:72` — bar `height: 'calc(56px + env(safe-area-inset-bottom, 0px))'` [VERIFIED: codebase grep]
+- `apps/pwa/src/api/client.ts:124–134` — `fetchLocalLogout()` exists, POST, credentials include [VERIFIED: codebase grep]
+- `apps/pwa/src/styles/tokens.css` — single `:root {}` block confirmed; `--sx-color-*` overrides at bottom [VERIFIED: codebase grep]
+- `apps/pwa/vite.config.ts:38–42` — maskable icon defect (reusing `icon-512.png`) confirmed [VERIFIED: codebase grep]
+- `apps/pwa/index.html` — no `` entries confirmed [VERIFIED: codebase grep]
+- `apps/pwa/public/` — only 3 stub files, none maskable, no favicon.ico/svg [VERIFIED: codebase grep]
+- `.planning/config.json` — `nyquist_validation: true`, `security_enforcement: true` [VERIFIED: codebase grep]
+
+### Secondary (MEDIUM confidence — official package docs)
+- `@vite-pwa/assets-generator` v1.0.2 — vite-pwa-org.netlify.app/assets-generator/ [CITED: vite-pwa-org.netlify.app/assets-generator/]
+- `sharp` v0.35.1 — sharp.pixelplumbing.com; github.com/lovell/sharp [CITED: npm registry metadata]
+- `vite-plugin-pwa` v1.3.0 — peer-depends on `@vite-pwa/assets-generator ^1.0.0` [CITED: npm registry peerDependencies]
+
+### Tertiary (LOW confidence — training knowledge)
+- ARIA tabs pattern (roving tabindex, `role="tablist"/"tab"/"tabpanel"`) — standard W3C ARIA spec [ASSUMED — widely documented, no drift risk]
+
+---
+
+## Metadata
+
+**Confidence breakdown:**
+- Fix surfaces: HIGH — directly confirmed against codebase source
+- Asset toolchain: MEDIUM — based on official vite-pwa documentation and npm registry; `minimal-2023` preset maskable behavior [ASSUMED] pending a test run
+- Architecture patterns: HIGH — Workstreams A/C/D are CSS/React patterns with no external dependencies
+- Pitfalls: HIGH — drawn from confirmed code structure and known project conventions
+
+**Research date:** 2026-06-18
+**Valid until:** 2026-08-18 (stable APIs; vite-plugin-pwa and @vite-pwa/assets-generator are stable releases)
diff --git a/.planning/phases/17-ui-optimization-polish/17-REVIEW-FIX.iter2.md b/.planning/phases/17-ui-optimization-polish/17-REVIEW-FIX.iter2.md
new file mode 100644
index 0000000..0eb8662
--- /dev/null
+++ b/.planning/phases/17-ui-optimization-polish/17-REVIEW-FIX.iter2.md
@@ -0,0 +1,125 @@
+---
+phase: 17-ui-optimization-polish
+fixed_at: 2026-06-18T00:00:00Z
+review_path: .planning/phases/17-ui-optimization-polish/17-REVIEW.md
+iteration: 1
+findings_in_scope: 15
+fixed: 15
+skipped: 0
+status: all_fixed
+---
+
+# Phase 17: Code Review Fix Report
+
+**Fixed at:** 2026-06-18T00:00:00Z
+**Source review:** .planning/phases/17-ui-optimization-polish/17-REVIEW.md
+**Iteration:** 1
+
+**Summary:**
+- Findings in scope: 15 (fix_scope: all — includes Info)
+- Fixed: 15
+- Skipped: 0
+
+All fixes were verified with `tsc --noEmit` (clean) and `eslint --max-warnings 0`
+(clean) on every touched file; the PWA also builds (`vite build` succeeds). A new
+shared hook `apps/pwa/src/hooks/useIsPhone.ts` was created to back WR-05/IN-03.
+
+## Fixed Issues
+
+### WR-01: Modal dialogs declare `aria-modal="true"` but do not trap focus
+
+**Files modified:** `apps/pwa/src/components/CredentialSheet.tsx`, `apps/pwa/src/components/SettingsSheet.tsx`, `apps/pwa/src/routes/AdminPage.tsx`
+**Commit:** fb30800
+**Applied fix:** Reused the existing `useFocusTrap(dialogRef)` hook (already used by EventForm/SeriesEditPrompt). Added a `dialogRef` + `onKeyDown={handleDialogKeyDown}` to every modal sheet that asserts `aria-modal="true"`: CredentialSheet, SettingsSheet, ChangePasswordSheet, LinkOidcSheet, and ResetPasswordSheet. Tab/Shift-Tab now cycle within the dialog instead of escaping to occluded background controls.
+
+### WR-02: Admin tab strip keyboard nav is incomplete (no Home/End, no explicit wrap)
+
+**Files modified:** `apps/pwa/src/routes/AdminPage.tsx`
+**Commit:** f601c0c
+**Applied fix:** Rewrote `handleTabKeyDown` to the full WAI-ARIA tabs pattern: ArrowLeft/Right now wrap around the ends using modular arithmetic over the `['members','settings']` order, and Home/End jump to the first/last tab.
+
+### WR-03: Success toast does not re-announce repeated identical messages
+
+**Files modified:** `apps/pwa/src/routes/AdminPage.tsx`
+**Commit:** f601c0c
+**Applied fix:** Changed toast state from `string | null` to `{ id: number; msg: string } | null` with a `showToast(msg)` helper that mints a fresh `id` (Date.now()) per call. The rendered toast `
` is now keyed on `toast.id` so an identical repeated message remounts and `aria-live` re-announces it; the auto-dismiss effect depends on the fresh object reference so the 3s timer restarts.
+
+### WR-04: Toast `whiteSpace: nowrap` is a latent horizontal-overflow regression
+
+**Files modified:** `apps/pwa/src/routes/AdminPage.tsx`
+**Commit:** f601c0c
+**Applied fix:** Removed `whiteSpace: 'nowrap'` from the toast style so a longer/localized message wraps within `maxWidth: 90vw` instead of overflowing `documentElement.scrollWidth` (which would trip the layout suite's no-horizontal-overflow rule).
+
+### WR-05: `matchMedia(...)` read at render time does not react to resize/orientation
+
+**Files modified:** `apps/pwa/src/hooks/useIsPhone.ts` (new), `apps/pwa/src/App.tsx`, `apps/pwa/src/components/CalendarShell.tsx`, `apps/pwa/src/components/SettingsSheet.tsx`, `apps/pwa/src/components/CredentialSheet.tsx`, `apps/pwa/src/routes/AdminPage.tsx`
+**Commit:** a4a7438
+**Applied fix:** Added a resize-aware `useMediaQuery`/`useIsPhone` hook backed by `matchMedia.addEventListener('change', …)`. Replaced all six synchronous `matchMedia('(max-width: 767px)')` render-time reads with `useIsPhone()`. Hook calls were placed before any early `return null` to respect the Rules of Hooks. Components now re-render when the 767px breakpoint is crossed (iPad rotation, desktop resize).
+
+### WR-06: Timezone combobox `aria-activedescendant`/highlight can desync after filtering
+
+**Files modified:** `apps/pwa/src/routes/AdminPage.tsx`
+**Commit:** 1c0f357
+**Applied fix:** Derived a clamped `tzActiveIndexClamped = Math.min(tzActiveIndex, max(0, filteredZones.length - 1))` in render and used it for `aria-activedescendant`, the Enter-to-commit lookup, and the visual highlight (`i === tzActiveIndexClamped`). ArrowUp/ArrowDown clamp the current index before moving so they never start from a stale position past the end of a freshly-shrunk list.
+**Note:** Combobox interaction logic — recommend a quick manual/keyboard pass (type to filter, arrow, Enter) to confirm behavior.
+
+### WR-07: Timezone combobox drops Tab-to-commit and relies on a fragile blur timeout
+
+**Files modified:** `apps/pwa/src/routes/AdminPage.tsx`
+**Commit:** 1c0f357
+**Applied fix:** Added a `Tab` branch to the combobox `onKeyDown` that commits the highlighted option WITHOUT `preventDefault` (focus still advances to Save). Added an unmount cleanup effect that clears `tzBlurTimer`. Reduced the blur-close `setTimeout` from 120ms to 0ms now that options `preventDefault()` on `onMouseDown` (so a click never blurs the input first).
+**Note:** Interaction logic — recommend a manual check that tabbing out of the open listbox commits the highlighted zone and that clicking an option still selects it.
+
+### WR-08: `pwa:icons` script is non-portable and silently coupled to generated filenames
+
+**Files modified:** `apps/pwa/scripts/copy-pwa-icons.mjs` (new), `apps/pwa/package.json`, `apps/pwa/vite.config.ts`
+**Commit:** dd0b761
+**Applied fix:** Replaced the five-`cp` Unix-only chain with a cross-platform Node script (`fs.copyFileSync`) that maps each generated filename to its stable manifest name and fails loudly with a named error if a generated file is missing (generator rename guard). Added a discoverability comment beside the manifest `icons` array in `vite.config.ts` pointing at the script's COPIES table.
+
+### IN-01: `OidcRedirect` navigates as a render-phase side effect
+
+**Files modified:** `apps/pwa/src/App.tsx`
+**Commit:** a4a7438
+**Applied fix:** Moved `window.location.replace('/api/login')` into a `useEffect(() => {...}, [])` so the navigation is no longer a render-phase side effect.
+
+### IN-02: Inconsistent `exhaustive-deps` disables across sibling dialogs
+
+**Files modified:** `apps/pwa/src/components/CredentialSheet.tsx`, `apps/pwa/src/components/SettingsSheet.tsx`
+**Commit:** 3f4b7ea
+**Applied fix:** Wrapped `handleClose` in `useCallback` in CredentialSheet and ChangePasswordSheet, added it to the Escape effect's dependency array, and removed the `// eslint-disable-line react-hooks/exhaustive-deps` comments — matching the LinkOidc/Reset sheet pattern.
+
+### IN-03: `isPhone`/`phone` 767px check duplicated across ~6 sites
+
+**Files modified:** (same as WR-05)
+**Commit:** a4a7438
+**Applied fix:** Resolved together with WR-05 — the single `useIsPhone()` hook now backs all call sites, and the `(max-width: 767px)` query lives in one place (`PHONE_MAX_QUERY` in the hook). The old standalone `isPhone()` helpers in App.tsx and CalendarShell.tsx were deleted.
+
+### IN-04: Dead placeholder brand tokens retained
+
+**Files modified:** `apps/pwa/src/styles/tokens.css`
+**Commit:** 2317833
+**Applied fix:** Removed the unused `--brand-logo-bg`, `--brand-logo-text`, and `--brand-app-name` declarations (verified via grep that nothing references them); left a short comment explaining the removal and that BrandSlot only reads `--brand-logo-size`/`--brand-logo-border-radius`.
+
+### IN-05: Admin members-panel JSX has inconsistent indentation / stacked bottom margins
+
+**Files modified:** `apps/pwa/src/routes/AdminPage.tsx`
+**Commit:** 4bc1e2a
+**Applied fix:** Ran Prettier (project `.prettierrc`) over AdminPage.tsx, normalizing the members-panel indentation and the rest of the file's drift; `prettier --check` now passes on the file. The stacked `marginBottom: var(--space-8)` on the last panel section was left intentionally — the review flagged it only as a minor cosmetic note, and changing section spacing risks a visual regression outside the finding's scope.
+
+### IN-06: Toast and dialog `zIndex` overlap (300/301)
+
+**Files modified:** `apps/pwa/src/routes/AdminPage.tsx`
+**Commit:** f601c0c
+**Applied fix:** Raised the toast `zIndex` from 300 to 400 so it always paints above sheet backdrops (300) and sheets (301), removing the DOM-order-dependent paint ambiguity.
+
+### IN-07: `Intl.DateTimeFormat()` recomputed every render in the calendar-config path
+
+**Files modified:** `apps/pwa/src/components/CalendarShell.tsx`, `apps/pwa/src/routes/AdminPage.tsx`
+**Commit:** 11b6b36
+**Applied fix:** Wrapped both `Intl.DateTimeFormat().resolvedOptions().timeZone` reads in `useMemo(…, [])` — `displayTimeZone` in CalendarShell (feeds the stable `useCalendarApp` config) and `detectedTz` in AdminPage.
+
+---
+
+_Fixed: 2026-06-18T00:00:00Z_
+_Fixer: Claude (gsd-code-fixer)_
+_Iteration: 1_
diff --git a/.planning/phases/17-ui-optimization-polish/17-REVIEW-FIX.iter3.md b/.planning/phases/17-ui-optimization-polish/17-REVIEW-FIX.iter3.md
new file mode 100644
index 0000000..0eb8662
--- /dev/null
+++ b/.planning/phases/17-ui-optimization-polish/17-REVIEW-FIX.iter3.md
@@ -0,0 +1,125 @@
+---
+phase: 17-ui-optimization-polish
+fixed_at: 2026-06-18T00:00:00Z
+review_path: .planning/phases/17-ui-optimization-polish/17-REVIEW.md
+iteration: 1
+findings_in_scope: 15
+fixed: 15
+skipped: 0
+status: all_fixed
+---
+
+# Phase 17: Code Review Fix Report
+
+**Fixed at:** 2026-06-18T00:00:00Z
+**Source review:** .planning/phases/17-ui-optimization-polish/17-REVIEW.md
+**Iteration:** 1
+
+**Summary:**
+- Findings in scope: 15 (fix_scope: all — includes Info)
+- Fixed: 15
+- Skipped: 0
+
+All fixes were verified with `tsc --noEmit` (clean) and `eslint --max-warnings 0`
+(clean) on every touched file; the PWA also builds (`vite build` succeeds). A new
+shared hook `apps/pwa/src/hooks/useIsPhone.ts` was created to back WR-05/IN-03.
+
+## Fixed Issues
+
+### WR-01: Modal dialogs declare `aria-modal="true"` but do not trap focus
+
+**Files modified:** `apps/pwa/src/components/CredentialSheet.tsx`, `apps/pwa/src/components/SettingsSheet.tsx`, `apps/pwa/src/routes/AdminPage.tsx`
+**Commit:** fb30800
+**Applied fix:** Reused the existing `useFocusTrap(dialogRef)` hook (already used by EventForm/SeriesEditPrompt). Added a `dialogRef` + `onKeyDown={handleDialogKeyDown}` to every modal sheet that asserts `aria-modal="true"`: CredentialSheet, SettingsSheet, ChangePasswordSheet, LinkOidcSheet, and ResetPasswordSheet. Tab/Shift-Tab now cycle within the dialog instead of escaping to occluded background controls.
+
+### WR-02: Admin tab strip keyboard nav is incomplete (no Home/End, no explicit wrap)
+
+**Files modified:** `apps/pwa/src/routes/AdminPage.tsx`
+**Commit:** f601c0c
+**Applied fix:** Rewrote `handleTabKeyDown` to the full WAI-ARIA tabs pattern: ArrowLeft/Right now wrap around the ends using modular arithmetic over the `['members','settings']` order, and Home/End jump to the first/last tab.
+
+### WR-03: Success toast does not re-announce repeated identical messages
+
+**Files modified:** `apps/pwa/src/routes/AdminPage.tsx`
+**Commit:** f601c0c
+**Applied fix:** Changed toast state from `string | null` to `{ id: number; msg: string } | null` with a `showToast(msg)` helper that mints a fresh `id` (Date.now()) per call. The rendered toast `` block (`register_authored_at_plan_time: true`). The work is
+client-side CSS/layout, static brand-asset wiring, and presentation-only React
+state — no new endpoints, no new authorization logic, no new runtime data flow.
+The single non-`accept` threat (logout wiring) reuses an endpoint already
+verified live in Phase 19.
+
+---
+
+## Trust Boundaries
+
+| Boundary | Description | Data Crossing |
+|----------|-------------|---------------|
+| Build tooling → repo (17-02) | `@vite-pwa/assets-generator` (+ sharp, sharp-ico) runs at design time and writes static images into `public/`. New devDependency = supply-chain surface. | Static image bytes; no secrets/PII |
+| Client UI → existing logout endpoint (17-05) | Sign out control calls the already-implemented, Phase-19-verified `POST /api/auth/local/logout` via `fetchLocalLogout()`. No new endpoint, no new auth logic. | Session cookie (cleared server-side) |
+| (none new) — 17-01, 17-03, 17-04, 17-06 | CSS-only restructure/offsets, static asset references, and presentation-only local `useState` (tab/toast). Server-side admin `403` enforcement unchanged. | None |
+
+---
+
+## Threat Register
+
+| Threat ID | Category | Component | Disposition | Mitigation | Status |
+|-----------|----------|-----------|-------------|------------|--------|
+| T-17-01-01 | Tampering | tokens.css selector restructure | accept | CSS custom properties carry no executable content and no user input; selector change cannot introduce injection. | closed |
+| T-17-02-SC | Tampering | npm devDependency install (@vite-pwa/assets-generator, sharp, sharp-ico) | accept | RESEARCH Package Legitimacy Audit rates all three Approved (official vite-pwa, 13-yr sharp, sharp-ico); no `[SLOP]`/unverified packages. devDependencies only; generated output is static images. | closed |
+| T-17-02-02 | Information disclosure | generated brand assets | accept | Assets are public-by-design brand images; no secrets or PII. | closed |
+| T-17-03-01 | Tampering | FAB/content CSS offsets | accept | Pure layout geometry via existing CSS custom property; no executable content, no input. | closed |
+| T-17-04-01 | Tampering | BrandSlot img / index.html links | accept | Logo img is decorative with empty `alt`; no `dangerouslySetInnerHTML` (T-05-24 invariant maintained); favicon/manifest entries point at committed static files. **Verified live:** BrandSlot renders ``, no `dangerouslySetInnerHTML` in source. | closed |
+| T-17-05-01 | Elevation of Privilege | logout control (D-07) | mitigate | `fetchLocalLogout()` clears the local-session cookie via the existing Phase-19-verified endpoint; client navigates to `/login` regardless of success/failure so a stale-cookie-with-logged-out-UI state cannot persist. **Verified:** `SettingsSheet.tsx:143-151` — `try { await fetchLocalLogout(); } catch {} onClose(); void navigate('/login');`. | closed |
+| T-17-05-02 | Tampering | sheet centering CSS (D-09) | accept | Position-only CSS branch; no input, no executable content. | closed |
+| T-17-06-01 | Tampering | toast message content (D-08) | accept | Toast copy is hardcoded JSX string constants ("Member added." / "Password reset."); no user-controlled content; no `dangerouslySetInnerHTML`. **Verified live:** toast rendered "Member added." from a `role=status` node on member creation. | closed |
+| T-17-06-02 | Elevation of Privilege | admin two-tab nav (D-10) | accept | Tab strip is presentation-only local `useState`; `isAdmin` nav visibility is UX-only — the real boundary is server-side `403` on `/api/admin/*` (unchanged). | closed |
+
+*Status: open · closed*
+*Disposition: mitigate (implementation required) · accept (documented risk) · transfer (third-party)*
+
+---
+
+## Accepted Risks Log
+
+| Risk ID | Threat Ref | Rationale | Accepted By | Date |
+|---------|------------|-----------|-------------|------|
+| AR-17-01 | T-17-01-01 | Static stylesheet selector restructure; zero runtime data flow. | Lucas Berger | 2026-06-18 |
+| AR-17-02 | T-17-02-SC | All new devDependencies Approved by RESEARCH package-legitimacy audit; design-time only. | Lucas Berger | 2026-06-18 |
+| AR-17-03 | T-17-02-02 | Brand assets are public-by-design; no secrets/PII. | Lucas Berger | 2026-06-18 |
+| AR-17-04 | T-17-03-01 | Pure CSS layout geometry; no input surface. | Lucas Berger | 2026-06-18 |
+| AR-17-05 | T-17-04-01 | Decorative img with empty alt; no `dangerouslySetInnerHTML`; committed static assets. | Lucas Berger | 2026-06-18 |
+| AR-17-06 | T-17-05-02 | Position-only CSS branch; no input/executable content. | Lucas Berger | 2026-06-18 |
+| AR-17-07 | T-17-06-01 | Hardcoded toast string constants; no user-controlled content. | Lucas Berger | 2026-06-18 |
+| AR-17-08 | T-17-06-02 | Presentation-only tab state; authorization enforced server-side (unchanged). | Lucas Berger | 2026-06-18 |
+
+*Accepted risks do not resurface in future audit runs.*
+
+---
+
+## Security Audit Trail
+
+| Audit Date | Threats Total | Closed | Open | Run By |
+|------------|---------------|--------|------|--------|
+| 2026-06-18 | 9 | 9 | 0 | /gsd-secure-phase (orchestrator, plan-time register verification) |
+
+Verification method: all 6 plans carried plan-time `` blocks
+(`register_authored_at_plan_time: true`). 8 `accept`-disposition threats are
+documented accepted risks; the 1 `mitigate` threat (T-17-05-01) had its
+mitigation verified present in `SettingsSheet.tsx`. Several dispositions were
+additionally corroborated at runtime during the Phase 17 UAT (playwright-cli):
+BrandSlot decorative img, hardcoded success toast, admin tab presentation-only
+state. `threats_open: 0` — short-circuit per workflow Step 3.
+
+---
+
+## Sign-Off
+
+- [x] All threats have a disposition (mitigate / accept / transfer)
+- [x] Accepted risks documented in Accepted Risks Log
+- [x] `threats_open: 0` confirmed
+- [x] `status: verified` set in frontmatter
+
+**Approval:** verified 2026-06-18
diff --git a/.planning/phases/17-ui-optimization-polish/17-UAT.md b/.planning/phases/17-ui-optimization-polish/17-UAT.md
new file mode 100644
index 0000000..3a7d887
--- /dev/null
+++ b/.planning/phases/17-ui-optimization-polish/17-UAT.md
@@ -0,0 +1,82 @@
+---
+status: complete
+phase: 17-ui-optimization-polish
+source:
+ - 17-01-SUMMARY.md
+ - 17-02-SUMMARY.md
+ - 17-03-SUMMARY.md
+ - 17-04-SUMMARY.md
+ - 17-05-SUMMARY.md
+ - 17-06-SUMMARY.md
+verification_method: playwright-cli (Chromium, host Vite @5173, Docker API/DB)
+started: 2026-06-18T18:26:00Z
+updated: 2026-06-18T18:31:00Z
+---
+
+## Current Test
+
+[testing complete]
+
+## Tests
+
+### 1. Cold Start Smoke Test
+expected: App boots and `/calendar` loads with live data — calendar grid, color legend, and primary controls render without console errors.
+result: pass
+evidence: PWA opened at http://localhost:5173/ → redirected to /calendar (dev-bypass). June 2026 grid rendered, color legend ("Dev User" #4A90D9, "Family" #F25C7A), New Event button + Today/nav present. 0 console errors. Docker API/MariaDB/Redis up.
+
+### 2. Login Page Branding — FamilySync logo (Plan 17-04)
+expected: Login page shows the approved family-house logo (BrandSlot), not the old "FS" text placeholder.
+result: pass
+evidence: /login renders `` at 48px. Old `aria-hidden` "FS" placeholder div is absent. `/logo.svg` serves 200 image/svg+xml.
+
+### 3. Favicon & Theme Color (Plan 17-04)
+expected: Browser tab favicon set (SVG + ICO + apple-touch) wired; warm-amber theme color applied.
+result: pass
+evidence: `` for /favicon.svg (image/svg+xml) + /favicon.ico + apple-touch-icon present. All of favicon.svg/favicon.ico/apple-touch-icon.png/icon-maskable-512.png fetch 200 with correct content-types. `` = #e8915a.
+
+### 4. Phone Layout Overlap Fix (Plan 17-03 / D-01)
+expected: At ≤767px, the New Event FAB sits above the fixed BottomTabBar (not occluded) and the color-legend chips remain fully visible.
+result: pass
+evidence: @390×844 — FAB bottom=764, BottomTabBar top=788 → FAB above bar with 24px gap (= --space-6). Color legend bottom=780 < nav top=788, visible:true, not occluded. Both chips ("Dev User", "Family") present. 0 console errors.
+
+### 5. Sign Out Control (Plan 17-05 / D-07)
+expected: Settings sheet exposes a reachable "Sign out" control.
+result: pass
+evidence: Settings dialog (opened from "Dev User — open settings") contains Account section, "Change password", and a "Sign out" button — all reachable.
+
+### 6. Settings Sheet Centering (Plan 17-05 / D-09)
+expected: On desktop, the settings sheet renders as a centered modal (not a bottom sheet).
+result: pass
+evidence: Settings dialog — position:fixed, width 480px, horizontal & vertical center offset = 0 on 1280×720, aria-modal="true".
+
+### 7. Modal Focus Trap (code-review CR-01 / WR-01 fix)
+expected: With a sheet open, Tab/Shift+Tab cycle focus within the dialog and never escape to background controls.
+result: pass
+evidence: Settings dialog (5 focusables). Tab from last ("Sign out") → wraps to "Close settings" (still inside). Shift+Tab from first → wraps to "Sign out" (still inside). Focus stayed contained both directions. Confirms the jsdom-tolerant visibility filter works correctly in a real (laid-out) browser — resolves the code-review human-verification flag.
+
+### 8. Admin Two-Tab Navigation (Plan 17-06 / D-10 + WR-02)
+expected: Admin page shows "Members & Accounts" / "Settings" tabs with full WAI-ARIA keyboard support (arrows wrap, Home/End).
+result: pass
+evidence: `role=tablist` with two `role=tab`s, "Members & Accounts" selected by default, tabpanels with regions. Keyboard: ArrowRight→Settings, ArrowRight wraps→Members, ArrowLeft→Settings, Home→Members, End→Settings. All transitions update aria-selected.
+
+### 9. Admin Success Toast (Plan 17-06 / D-08)
+expected: Creating a member shows a transient success toast announced to assistive tech.
+result: pass
+evidence: Filled + submitted the Add-member form (throwaway "ZZ Verify Toast"); a `role=status` aria-live="polite" toast read "Member added." Throwaway member removed from the dev DB afterward (verified 0 remaining).
+
+### 10. iOS Standalone PWA — install + home-screen icon + push
+expected: Installed-to-home-screen behavior and apple-touch/maskable icon appearance on a real iOS device.
+result: skipped
+reason: Genuinely device-only — cannot be driven by playwright-cli/Chromium (manifest is production-only and not injected in Vite dev). Icon assets and manifest config are verified at the asset/code level (Tests 2–3, code review). Real-device behavior remains a human checkpoint, already tracked in 17-VERIFICATION.md.
+
+## Summary
+
+total: 10
+passed: 9
+issues: 0
+skipped: 1
+pending: 0
+
+## Gaps
+
+[none — all automated checks passed; 1 device-only item deferred to existing human checkpoints]
diff --git a/.planning/phases/17-ui-optimization-polish/17-UI-SPEC.md b/.planning/phases/17-ui-optimization-polish/17-UI-SPEC.md
new file mode 100644
index 0000000..a636d2a
--- /dev/null
+++ b/.planning/phases/17-ui-optimization-polish/17-UI-SPEC.md
@@ -0,0 +1,851 @@
+---
+phase: 17
+slug: ui-optimization-polish
+status: draft
+shadcn_initialized: false
+preset: none
+created: 2026-06-18
+---
+
+# Phase 17 — UI Design Contract: UI Optimization & Polish
+
+> Visual and interaction contract for four bounded workstreams:
+> A — phone-layout overlap fix + small-viewport sweep,
+> B — branding assets (logo, favicon, PWA icon set),
+> C — theme-token groundwork (light-only, semantic layer),
+> D — UAT-surfaced UI fixes (logout control, admin success feedback,
+> dialog/sheet centering, admin two-tab nav).
+>
+> Generated by gsd-ui-researcher. Consume before planning or executing.
+
+---
+
+## Context & Approach
+
+This is a **polish + branding + theme-token-groundwork** phase on an **existing shipped**
+React 19 + Vite PWA. NOT greenfield, NOT a redesign. All design decisions extend the
+established token system in `apps/pwa/src/styles/tokens.css`.
+
+The no-hard-coded-values invariant is a hard constraint: **all hex/px values live in
+`tokens.css` as CSS custom properties; component files reference variables only.**
+
+The existing Phase 19 UI-SPEC (approved 2026-06-16) establishes the design-system
+baseline this phase builds on. No new tokens are introduced except the layout-chrome
+token added in Workstream A.
+
+---
+
+## Design System
+
+| Property | Value |
+|----------|-------|
+| Tool | none (existing CSS custom properties) |
+| Preset | not applicable |
+| Component library | none (hand-rolled inline `React.CSSProperties`, project convention) |
+| Icon library | lucide-react (already installed) |
+| Font | system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif (`var(--font-family-base)`) |
+
+Source: `apps/pwa/src/styles/tokens.css` — pre-populated from codebase scan.
+Pattern baseline: existing components (SettingsSheet, AdminPage, CredentialSheet, CalendarShell).
+
+---
+
+## Spacing Scale
+
+No new spacing tokens are introduced. Phase 17 uses the existing 4px-based scale unchanged.
+
+| Token | Value | Usage in this phase |
+|-------|-------|---------------------|
+| --space-1 | 4px | Icon gaps, tight label margins |
+| --space-2 | 8px | Tab strip inner gap, section label bottom margin |
+| --space-3 | 12px | Input row padding, tab content gap |
+| --space-4 | 16px | Toast horizontal padding, button padding, between-field gap |
+| --space-6 | 24px | Sheet/card padding, FAB clearance (base of calc expression) |
+| --space-8 | 32px | Section gap in admin two-tab content |
+| --space-12 | 48px | Page-level top/bottom padding |
+
+**New layout-chrome token (Workstream A):**
+
+```css
+/* Added to tokens.css :root alongside existing spacing scale */
+--bottom-chrome-h: calc(56px + env(safe-area-inset-bottom, 0px));
+```
+
+This single token is the source of truth for BottomTabBar height. It is consumed
+by the FAB offset (`bottom: calc(var(--bottom-chrome-h) + var(--space-6))`) and the
+phone content padding (`padding-bottom: var(--bottom-chrome-h)`). All three sites
+agree via one value.
+
+Exceptions:
+- FAB: `width: 56px; height: 56px` (Rule 1 minimum: ≥56×56px per layout.spec.ts). Not a
+ spacing-scale value — this is the FAB's own intrinsic size.
+- All interactive elements: `minHeight: 44px; minWidth: 44px` (WCAG 2.5.5 Touch Target).
+- Admin two-tab strip: tab items use `minHeight: 44px` to meet touch-target minimum.
+- Dialog/sheet (centered, D-09): `maxWidth: 480px` centered via
+ `left: 50%; transform: translateX(-50%)` (desktop); phone retains full-width
+ bottom-sheet `bottom: 0; left: 0; right: 0`.
+
+---
+
+## Typography
+
+All values from `tokens.css`. No new sizes or weights.
+
+| Role | Size | Weight | Line Height | Variable |
+|------|------|--------|-------------|----------|
+| Body | 15px | 400 | 1.5 | `var(--text-body-size)` / `var(--text-body-weight)` / `var(--text-body-line-height)` |
+| Label | 13px | 400 | 1.4 | `var(--text-label-size)` / `var(--text-label-weight)` / `var(--text-label-line-height)` |
+| Heading | 18px | 600 | 1.25 | `var(--text-heading-size)` / `var(--text-heading-weight)` / `var(--text-heading-line-height)` |
+| Display | 24px | 600 | 1.2 | `var(--text-display-size)` / `var(--text-display-weight)` / `var(--text-display-line-height)` |
+
+Usage in this phase:
+- Admin two-tab strip label: Label (13px/400/1.4) — inactive state; active state weight 600
+- Toast notification body: Label (13px/400/1.4)
+- Toast notification icon: 16px lucide icon
+- Logout button label: Body (15px/400/1.5) — matches existing SettingsSheet row pattern
+- Admin section content: inherits existing AdminPage typography (no change)
+
+---
+
+## Color
+
+All values from `tokens.css`. No new hex values in this phase.
+
+| Role | Value | Variable | Usage |
+|------|-------|----------|-------|
+| Dominant (60%) | #ffffff | `var(--color-surface)` | Page background, sheet background, tab strip background |
+| Secondary (30%) | #f7f7f8 | `var(--color-surface-dim)` | Tab strip inactive background, toast background |
+| Accent (10%) | #4a90d9 | `var(--color-member-0)` | Active tab indicator, active tab label, toast success icon, logout destructive separator |
+| Destructive | #dc2626 | `var(--color-destructive)` | Logout button text color (destructive row style) |
+
+Accent (`var(--color-member-0)`) reserved for:
+- Active tab bottom-border indicator in the admin two-tab strip (2px solid)
+- Active tab label text color
+- Toast icon for success feedback
+- Focus ring on all new interactive elements (`var(--color-focus-ring)`, 2px outline, 2px offset)
+
+Additional semantic colors (already in tokens.css — no new values):
+- `var(--color-border)` #e2e4e9 — tab strip bottom border, dialog border, toast border
+- `var(--color-border-subtle)` #eceef2 — separator above logout button in SettingsSheet
+- `var(--color-text-primary)` #111318 — tab labels (active), sheet headings
+- `var(--color-text-secondary)` #6b7280 — tab labels (inactive), toast body text
+- `var(--color-text-muted)` #9ca3af — section labels (uppercase, 13px/600/0.06em letter-spacing)
+- `var(--color-overlay)` rgba(0,0,0,0.32) — sheet/dialog backdrop
+
+### Brand accent checkpoint (answered question Q1)
+
+The accent direction is a **checkpoint decision** — both variants must be producible
+and comparable. The token restructure in Workstream C makes this a single-file swap.
+
+**Variant A — keep cool-blue:**
+- No token changes: `--color-member-0: #4a90d9`, `theme-color` stays `#4A90D9`
+
+**Variant B — warm rose/amber:**
+- `--color-member-0: #f25c7a` (rose, already the `--color-shared-family` value)
+ OR a warm amber `#e8915a` — one of these two candidates to compare at the checkpoint
+- Acceptance lens: warm/rounded/at-home; contrast ratio ≥3:1 on `#ffffff` (WCAG AA for
+ large text/UI components; the current rose #f25c7a passes at 3.0:1)
+- Files that flip for Variant B: `tokens.css` (`--color-member-0`), `index.html`
+ (`theme-color` meta content), `vite.config.ts` manifest (`theme_color`)
+- Note: `--sx-color-primary` already maps to `var(--color-member-0)` — it follows
+ the accent automatically
+
+**Default if checkpoint skipped:** keep Variant A (#4a90d9).
+
+Light-theme scope only. No dark palette values authored this phase.
+
+---
+
+## Workstream A — Phone-Layout Overlap Fix
+
+### Visual invariants (hard rules — must pass on iphone + pixel profiles)
+
+1. **FAB never intersects the BottomTabBar rect.** The FAB's bottom edge must be
+ at or above the BottomTabBar's top edge. On a 390×844 viewport with `safe-area-inset=0`:
+ BottomTabBar top edge = 844 - 56 = 788px. FAB bottom edge must be ≤ 788px.
+2. **Content fully scrollable above the bar.** The phone content area's scroll-bottom
+ must clear the BottomTabBar height so no content is occluded at rest. The colour-legend
+ chips ("Dev User" / member legend) and any bottom-of-page content must be visible
+ without needing to manually offset-scroll.
+3. **Safe-area-inset composes correctly.** On notched devices, `env(safe-area-inset-bottom)`
+ is non-zero; the token `calc(56px + env(safe-area-inset-bottom, 0px))` absorbs both the
+ bar height and the notch.
+4. **No horizontal overflow** — existing Rule 2 must continue to pass after the fix.
+5. **Tap targets preserved** — all existing ≥44px/≥56px assertions in layout.spec.ts
+ must pass after the fix.
+
+### Fix contract
+
+**New token added to `tokens.css` `:root`:**
+```css
+--bottom-chrome-h: calc(56px + env(safe-area-inset-bottom, 0px));
+```
+
+**FAB offset (CalendarShell.tsx):**
+- Before: `bottom: var(--space-6)` (~24px)
+- After: `bottom: calc(var(--bottom-chrome-h) + var(--space-6))`
+- The FAB sits `var(--space-6)` (24px) above the BottomTabBar top edge regardless
+ of safe-area-inset value.
+
+**Content padding (App.tsx `contentStyle`):**
+- Phone branch only (inside `if (phone)` or via `isPhone()` conditional)
+- Add: `paddingBottom: 'var(--bottom-chrome-h)'`
+- Desktop `contentStyle` is unchanged (no BottomTabBar on desktop).
+
+**BottomTabBar height (BottomTabBar.tsx):**
+- The bar's `height` calculation already uses `calc(56px + env(safe-area-inset-bottom, 0px))`
+ inline. This remains correct and unchanged — `--bottom-chrome-h` resolves to the same
+ value so both the token and the component agree. For consistency, the planner MAY choose
+ to reference the token from the bar's height property as well, but the visual invariant
+ is met either way.
+
+### Regression guard (D-02 decision)
+
+**Recommendation: add a permanent overlap CI assertion to `layout.spec.ts`.**
+
+Evidence basis: the defect was long-standing (Phase 04 — months), was invisible to desktop
+testing, and CI has iphone/pixel profiles running. Adding a geometry assertion to the
+existing spec is the lowest-regress mechanism. The assertion has no runtime cost beyond
+one `boundingBox()` call.
+
+**Assertion contract to add to `layout.spec.ts`:**
+
+```
+test('New Event FAB does not overlap BottomTabBar (A — phone only)', async ({ page }, testInfo) => {
+ test.skip(testInfo.project.name === 'desktop', 'Phone-only assertion');
+ await page.goto('/calendar');
+ const fab = page.getByRole('button', { name: 'New Event' });
+ const nav = page.getByRole('navigation', { name: 'Main navigation' });
+ const fabBox = await fab.boundingBox();
+ const navBox = await nav.boundingBox();
+ expect(fabBox).not.toBeNull();
+ expect(navBox).not.toBeNull();
+ // FAB bottom edge must be at or above the BottomTabBar top edge
+ expect(fabBox!.y + fabBox!.height).toBeLessThanOrEqual(navBox!.y);
+});
+```
+
+Run profiles: iphone + pixel (skipped on desktop).
+
+### Small-viewport sweep (D-01)
+
+After the FAB/content-padding fix, run the full `layout.spec.ts` suite on all three
+profiles. Fix any violations flagged (per D-01: checklist-driven, within no-behaviour-change
+boundary). Expected areas to verify:
+
+- Admin tab (when isAdmin=true): ensure it still meets ≥44px tap target after layout fix
+- ColorLegend chips: confirm they are fully visible (not occluded) once content padding is added
+- Any Phase 19 additions (LoginPage, SettingsSheet rows): no overflow on phone profiles
+
+---
+
+## Workstream B — Branding Assets
+
+### Brand brief (acceptance lens)
+
+All generated assets must feel: **warm / rounded / at-home / caricature-family vibes**.
+Not corporate, not geometric. The operator reviews and approves before assets are final.
+This is a **checkpoint** — the checkpoint fires before wiring is committed.
+
+### Logo asset contract
+
+| Asset | Dimensions | Format | Filename | Purpose |
+|-------|-----------|--------|----------|---------|
+| Logo mark | 192×192px (source; scale up for 512) | SVG preferred; PNG fallback | `logo.svg` or `logo.png` | BrandSlot `![]()
` + derivation source for icon set |
+| Favicon (modern) | 32×32px (scalable) | SVG | `favicon.svg` | Browser tab icon (modern browsers) |
+| Favicon (legacy) | 16×16 + 32×32 ICO | ICO | `favicon.ico` | Browser tab icon (legacy, IE/older Safari) |
+| PWA icon 192 | 192×192px | PNG | `icon-192.png` | PWA manifest — standard purpose |
+| PWA icon 512 | 512×512px | PNG | `icon-512.png` | PWA manifest — standard purpose (splash screen) |
+| PWA maskable 512 | 512×512px | PNG | `icon-maskable-512.png` | PWA manifest — maskable purpose (separate file) |
+| Apple touch icon | 180×180px | PNG | `apple-touch-icon.png` | iOS home screen icon |
+
+All files placed in `apps/pwa/public/`.
+
+**Maskable safe-zone rule:** The maskable icon (`icon-maskable-512.png`) must place
+the logo mark entirely within the 80% safe-zone circle (radius 204px on a 512×512 canvas,
+centered). The outer 10% on each edge may be cropped by the OS adaptive-icon mask. The
+current manifest incorrectly reuses `icon-512.png` (no safe zone) for the maskable
+purpose — this is the defect being fixed.
+
+### BrandSlot swap contract (D-05)
+
+**What changes in `BrandSlot.tsx`:**
+- Replace the placeholder `` with
+ ``
+- Apply the existing `--brand-logo-*` token dimensions to the `![]()
`:
+ `width: var(--brand-logo-size, 48px)`, `height: var(--brand-logo-size, 48px)`,
+ `borderRadius: var(--brand-logo-border-radius, 50%)`, aspect-ratio: 1/1
+- The `--brand-logo-bg` token (placeholder circle background) is no longer used
+ as a background when a real `![]()
` is present — it may be set to `transparent`
+ or removed from the element's style (keep the token in `tokens.css` for forward
+ compat if needed)
+- The `FamilySync
+
+```
+
+`{ACCENT_HEX}` = the checkpoint-selected accent value (`#4A90D9` default or warm variant).
+
+The SVG favicon takes precedence in modern browsers; the ICO fallback covers legacy.
+Order matters: SVG first, ICO second (browsers pick the first supported type).
+
+### `vite.config.ts` manifest wiring contract
+
+Current state: 3 icon entries, last entry incorrectly reuses `icon-512.png` for maskable.
+
+After Phase 17:
+
+```ts
+icons: [
+ { src: '/icon-192.png', sizes: '192x192', type: 'image/png' },
+ { src: '/icon-512.png', sizes: '512x512', type: 'image/png' },
+ { src: '/icon-maskable-512.png', sizes: '512x512', type: 'image/png', purpose: 'maskable' },
+],
+```
+
+The `theme_color` value in the manifest must match the `index.html` `theme-color` meta
+and the checkpoint-selected accent. Change from `'#4A90D9'` to the chosen value at checkpoint.
+
+---
+
+## Workstream C — Theme-Token Groundwork
+
+### Contract
+
+**Groundwork only.** No dark palette values, no `prefers-color-scheme` media query wired
+to flip themes, no theme toggle UI. Light is and remains the only shipped theme.
+
+**Restructure `tokens.css` `:root` into a `data-theme`-capable pattern:**
+
+```css
+/* tokens.css — after restructure */
+
+:root,
+[data-theme="light"] {
+ /* All existing :root declarations move here verbatim. */
+ /* No value changes. */
+ /* ...all existing tokens... */
+}
+
+/* Dark theme stub — values intentionally absent (Phase 17 groundwork only).
+ Phase 999.20 fills these values and wires prefers-color-scheme. */
+/* [data-theme="dark"] { ... } */
+```
+
+The change is purely structural: `:root` is extended with `[data-theme="light"]` as a
+second selector on the same rule block. This allows a future `data-theme="dark"` attribute
+on `` to override without touching component files.
+
+**Schedule-X `--sx-color-*` overrides must remain working.** They are currently at the
+bottom of the same `:root` rule — after the restructure they remain inside the same
+combined `:root, [data-theme="light"]` rule block. The cascade order (after
+`@schedule-x/theme-default`) is unchanged; the overrides continue to win.
+
+**`--brand-logo-*` tokens** remain in the same `:root, [data-theme="light"]` block.
+Phase 17's logo swap updates their values here (e.g. `--brand-logo-border-radius`).
+
+**New token added in this workstream (in addition to Workstream A's
+`--bottom-chrome-h`):**
+
+No additional tokens beyond `--bottom-chrome-h` (Workstream A) and any updated
+`--brand-logo-*` values (Workstream B). The theme restructure introduces no new
+semantic names — only the selector change.
+
+**Invariant check:** after restructure, `grep -rn 'var(--' apps/pwa/src/components/`
+must show only `var(--token-name)` references, no hard-coded hex or px values in
+component files. This is the existing invariant; the restructure must not break it.
+
+---
+
+## Workstream D — UAT-Surfaced UI Fixes
+
+### D-07 — Logout control
+
+**Surfaces:** SettingsSheet (primary) and optionally AppNav phone header (secondary).
+
+**Primary placement: SettingsSheet.**
+A "Sign out" row is added below all existing SettingsSheet content, separated by a
+`var(--color-border-subtle)` horizontal rule (same divider pattern as the existing
+Account section). This mirrors the established section-separator pattern already used
+in SettingsSheet between Notifications and Account.
+
+Layout within SettingsSheet (bottom of sheet, after all other rows):
+```
+───────────────────────── ← 1px var(--color-border-subtle) divider, margin var(--space-4) top/bottom
+[LogOut icon 16px] Sign out ← full-width button, minHeight 44px, Body 15px/400, var(--color-destructive)
+```
+
+**Logout button style:**
+- `background: none; border: none; cursor: pointer`
+- Full width (`width: 100%`), `display: flex; alignItems: center; gap: var(--space-2)`
+- `LogOut` lucide icon (16px, `var(--color-destructive)`)
+- Label "Sign out" — Body (15px/400), `var(--color-destructive)`
+- `minHeight: 44px` (WCAG tap target)
+- `textAlign: left`, `padding: var(--space-2, 8px) 0`
+- On click: calls `fetchLocalLogout()` (already exists in `apps/pwa/src/api/client.ts:127`),
+ then navigates to `/login` (react-router `useNavigate` or `window.location.replace`)
+- No confirmation dialog — logout is not destructive in the "data loss" sense for a
+ household app; the user is simply signed out and can re-sign in immediately
+
+**Accessibility:**
+- `aria-label="Sign out"` on the button
+- Icon is `aria-hidden="true"`
+- Standard focus ring (`var(--color-focus-ring)`, 2px outline, 2px offset)
+
+**No backend work required** — `fetchLocalLogout()` calls the existing
+`POST /api/auth/local/logout` endpoint.
+
+### D-08 — Admin success feedback
+
+**Surfaces:** AdminPage.tsx — create-member and reset-password flows.
+
+**Toast notification design contract:**
+
+A lightweight transient toast appears after a successful admin action. Reuses the
+existing `SyncStateToast` visual pattern (already in the codebase) if possible; if not,
+implement a minimal inline variant.
+
+Toast style:
+- Position: `fixed; bottom: calc(var(--bottom-chrome-h) + var(--space-4))` on phone;
+ `fixed; bottom: var(--space-6); left: 50%; transform: translateX(-50%)` on desktop
+- Background: `var(--color-surface)`, border: `1px solid var(--color-border)`,
+ `borderRadius: var(--space-2)`, `boxShadow: 0 2px 8px rgba(0,0,0,0.12)`
+- Padding: `var(--space-3) var(--space-4)` (12px 16px)
+- Content: `CheckCircle` (16px, `var(--color-member-0)`) + toast message text (Label 13px/400,
+ `var(--color-text-primary)`)
+- Auto-dismiss: after 3 seconds (no dismiss button needed for a household app)
+- `role="status"`, `aria-live="polite"` — screen readers announce the success
+
+**Toast copy variants:**
+
+| Action | Toast copy |
+|--------|------------|
+| Create member success | "Member added." |
+| Reset password success | "Password reset." |
+
+**Placement note:** the toast bottom offset on phone uses `var(--bottom-chrome-h)`
+(introduced in Workstream A) so it clears the BottomTabBar.
+
+### D-09 — Dialog/sheet centering fix
+
+**Surfaces:** SettingsSheet, ChangePasswordSheet, LinkOidcSheet in SettingsSheet.tsx;
+AdminPage CredentialSheet; AdminPage reset-password sheet (Surface 11B).
+
+**Problem:** sheets currently use `bottom: 0; left: 0; right: 0; maxWidth: 480px;
+margin: 0 auto` — on desktop this places them bottom-center, not truly centered.
+
+**Fix contract:**
+
+Phone (`≤767px`): bottom-sheet behavior is correct and intentional. No change.
+- `position: fixed; bottom: 0; left: 0; right: 0; borderRadius: 12px 12px 0 0`
+
+Desktop (`≥768px`): centered modal.
+- `position: fixed; top: 50%; left: 50%; transform: translate(-50%, -50%)`
+- `maxWidth: 480px; width: calc(100% - var(--space-8)); borderRadius: 12px`
+- `maxHeight: calc(100dvh - var(--space-8)); overflowY: auto`
+- Remove `bottom: 0; left: 0; right: 0; margin: 0 auto; borderRadius: 12px 12px 0 0`
+- Box shadow: `0 8px 32px rgba(0,0,0,0.18)` (deeper shadow for centered modal feel)
+
+**Breakpoint:** use `window.matchMedia('(max-width: 767px)')` — same as `isPhone()`
+in the existing codebase. The behavior is determined at render time; no CSS-only
+media query approach is used (consistent with project pattern of inline React styles).
+
+**Applies to all sheets:** SettingsSheet, ChangePasswordSheet, LinkOidcSheet,
+CredentialSheet, AdminPage reset-password sheet. Each gets a phone/desktop style
+branch for its outer `
` is now keyed on `toast.id` so an identical repeated message remounts and `aria-live` re-announces it; the auto-dismiss effect depends on the fresh object reference so the 3s timer restarts.
+
+### WR-04: Toast `whiteSpace: nowrap` is a latent horizontal-overflow regression
+
+**Files modified:** `apps/pwa/src/routes/AdminPage.tsx`
+**Commit:** f601c0c
+**Applied fix:** Removed `whiteSpace: 'nowrap'` from the toast style so a longer/localized message wraps within `maxWidth: 90vw` instead of overflowing `documentElement.scrollWidth` (which would trip the layout suite's no-horizontal-overflow rule).
+
+### WR-05: `matchMedia(...)` read at render time does not react to resize/orientation
+
+**Files modified:** `apps/pwa/src/hooks/useIsPhone.ts` (new), `apps/pwa/src/App.tsx`, `apps/pwa/src/components/CalendarShell.tsx`, `apps/pwa/src/components/SettingsSheet.tsx`, `apps/pwa/src/components/CredentialSheet.tsx`, `apps/pwa/src/routes/AdminPage.tsx`
+**Commit:** a4a7438
+**Applied fix:** Added a resize-aware `useMediaQuery`/`useIsPhone` hook backed by `matchMedia.addEventListener('change', …)`. Replaced all six synchronous `matchMedia('(max-width: 767px)')` render-time reads with `useIsPhone()`. Hook calls were placed before any early `return null` to respect the Rules of Hooks. Components now re-render when the 767px breakpoint is crossed (iPad rotation, desktop resize).
+
+### WR-06: Timezone combobox `aria-activedescendant`/highlight can desync after filtering
+
+**Files modified:** `apps/pwa/src/routes/AdminPage.tsx`
+**Commit:** 1c0f357
+**Applied fix:** Derived a clamped `tzActiveIndexClamped = Math.min(tzActiveIndex, max(0, filteredZones.length - 1))` in render and used it for `aria-activedescendant`, the Enter-to-commit lookup, and the visual highlight (`i === tzActiveIndexClamped`). ArrowUp/ArrowDown clamp the current index before moving so they never start from a stale position past the end of a freshly-shrunk list.
+**Note:** Combobox interaction logic — recommend a quick manual/keyboard pass (type to filter, arrow, Enter) to confirm behavior.
+
+### WR-07: Timezone combobox drops Tab-to-commit and relies on a fragile blur timeout
+
+**Files modified:** `apps/pwa/src/routes/AdminPage.tsx`
+**Commit:** 1c0f357
+**Applied fix:** Added a `Tab` branch to the combobox `onKeyDown` that commits the highlighted option WITHOUT `preventDefault` (focus still advances to Save). Added an unmount cleanup effect that clears `tzBlurTimer`. Reduced the blur-close `setTimeout` from 120ms to 0ms now that options `preventDefault()` on `onMouseDown` (so a click never blurs the input first).
+**Note:** Interaction logic — recommend a manual check that tabbing out of the open listbox commits the highlighted zone and that clicking an option still selects it.
+
+### WR-08: `pwa:icons` script is non-portable and silently coupled to generated filenames
+
+**Files modified:** `apps/pwa/scripts/copy-pwa-icons.mjs` (new), `apps/pwa/package.json`, `apps/pwa/vite.config.ts`
+**Commit:** dd0b761
+**Applied fix:** Replaced the five-`cp` Unix-only chain with a cross-platform Node script (`fs.copyFileSync`) that maps each generated filename to its stable manifest name and fails loudly with a named error if a generated file is missing (generator rename guard). Added a discoverability comment beside the manifest `icons` array in `vite.config.ts` pointing at the script's COPIES table.
+
+### IN-01: `OidcRedirect` navigates as a render-phase side effect
+
+**Files modified:** `apps/pwa/src/App.tsx`
+**Commit:** a4a7438
+**Applied fix:** Moved `window.location.replace('/api/login')` into a `useEffect(() => {...}, [])` so the navigation is no longer a render-phase side effect.
+
+### IN-02: Inconsistent `exhaustive-deps` disables across sibling dialogs
+
+**Files modified:** `apps/pwa/src/components/CredentialSheet.tsx`, `apps/pwa/src/components/SettingsSheet.tsx`
+**Commit:** 3f4b7ea
+**Applied fix:** Wrapped `handleClose` in `useCallback` in CredentialSheet and ChangePasswordSheet, added it to the Escape effect's dependency array, and removed the `// eslint-disable-line react-hooks/exhaustive-deps` comments — matching the LinkOidc/Reset sheet pattern.
+
+### IN-03: `isPhone`/`phone` 767px check duplicated across ~6 sites
+
+**Files modified:** (same as WR-05)
+**Commit:** a4a7438
+**Applied fix:** Resolved together with WR-05 — the single `useIsPhone()` hook now backs all call sites, and the `(max-width: 767px)` query lives in one place (`PHONE_MAX_QUERY` in the hook). The old standalone `isPhone()` helpers in App.tsx and CalendarShell.tsx were deleted.
+
+### IN-04: Dead placeholder brand tokens retained
+
+**Files modified:** `apps/pwa/src/styles/tokens.css`
+**Commit:** 2317833
+**Applied fix:** Removed the unused `--brand-logo-bg`, `--brand-logo-text`, and `--brand-app-name` declarations (verified via grep that nothing references them); left a short comment explaining the removal and that BrandSlot only reads `--brand-logo-size`/`--brand-logo-border-radius`.
+
+### IN-05: Admin members-panel JSX has inconsistent indentation / stacked bottom margins
+
+**Files modified:** `apps/pwa/src/routes/AdminPage.tsx`
+**Commit:** 4bc1e2a
+**Applied fix:** Ran Prettier (project `.prettierrc`) over AdminPage.tsx, normalizing the members-panel indentation and the rest of the file's drift; `prettier --check` now passes on the file. The stacked `marginBottom: var(--space-8)` on the last panel section was left intentionally — the review flagged it only as a minor cosmetic note, and changing section spacing risks a visual regression outside the finding's scope.
+
+### IN-06: Toast and dialog `zIndex` overlap (300/301)
+
+**Files modified:** `apps/pwa/src/routes/AdminPage.tsx`
+**Commit:** f601c0c
+**Applied fix:** Raised the toast `zIndex` from 300 to 400 so it always paints above sheet backdrops (300) and sheets (301), removing the DOM-order-dependent paint ambiguity.
+
+### IN-07: `Intl.DateTimeFormat()` recomputed every render in the calendar-config path
+
+**Files modified:** `apps/pwa/src/components/CalendarShell.tsx`, `apps/pwa/src/routes/AdminPage.tsx`
+**Commit:** 11b6b36
+**Applied fix:** Wrapped both `Intl.DateTimeFormat().resolvedOptions().timeZone` reads in `useMemo(…, [])` — `displayTimeZone` in CalendarShell (feeds the stable `useCalendarApp` config) and `detectedTz` in AdminPage.
+
+---
+
+_Fixed: 2026-06-18T00:00:00Z_
+_Fixer: Claude (gsd-code-fixer)_
+_Iteration: 1_
diff --git a/.planning/phases/17-ui-optimization-polish/17-REVIEW-FIX.md b/.planning/phases/17-ui-optimization-polish/17-REVIEW-FIX.md
new file mode 100644
index 0000000..cf13a44
--- /dev/null
+++ b/.planning/phases/17-ui-optimization-polish/17-REVIEW-FIX.md
@@ -0,0 +1,56 @@
+---
+phase: 17-ui-optimization-polish
+fixed_at: 2026-06-18T14:04:00Z
+review_path: .planning/phases/17-ui-optimization-polish/17-REVIEW.md
+iteration: 3
+findings_in_scope: 2
+fixed: 2
+skipped: 0
+status: all_fixed
+---
+
+# Phase 17: Code Review Fix Report (Iteration 3)
+
+**Fixed at:** 2026-06-18T14:04:00Z
+**Source review:** .planning/phases/17-ui-optimization-polish/17-REVIEW.md
+**Iteration:** 3
+
+**Summary:**
+- Findings in scope: 2 (fix_scope: all — includes Info)
+- Fixed: 2
+- Skipped: 0
+
+**Gate status after fixes (all pass):**
+- `pnpm --filter @familysync/pwa test` → pass (22 files, 266 passed / 0 failed)
+- `pnpm --filter @familysync/pwa typecheck` → pass (tsc + e2e tsconfig)
+- `pnpm --filter @familysync/pwa lint` → pass (eslint `--max-warnings 0`)
+
+## Fixed Issues
+
+### CR-01: `useFocusTrap` visibility filter excluded all focusables under jsdom (CI gate failed)
+
+**Files modified:** `apps/pwa/src/hooks/useFocusTrap.ts`
+**Commit:** 287ecae
+**Applied fix:** The prior iter-3 auto-fix (WR-01) rejected every focusable under jsdom because there `getBoundingClientRect()` returns all-zero geometry and `offsetParent` is `null` for every node, which short-circuited the trap (`focusable.length === 0`) and broke the two pre-existing WR-07 focus-trap regression tests — making `pnpm test` (a CI gate) fail at 2 failed / 264 passed.
+
+Made the visibility heuristic tolerant of a non-layout environment: it now derives `hasLayout = r.width > 0 || r.height > 0 || el.offsetParent !== null`, and when there is no evidence of a layout engine (jsdom) it treats the node as visible instead of filtering it. Only when a real layout exists does it apply the `offsetParent === null` / zero-geometry exclusion, so genuinely hidden/collapsed nodes are still excluded in a real browser. The `hidden`-attribute exclusion is unambiguous regardless of layout, so it was hoisted out and kept unconditional. Result: all 266 PWA tests pass, including both WR-07 cases.
+
+### IN-01: Focus-trap containment guard was unreachable as wired (harmless dead branch)
+
+**Files modified:** `apps/pwa/src/hooks/useFocusTrap.ts`
+**Commit:** 287ecae
+**Applied fix:** The handler is wired only to each dialog's own `onKeyDown`, so it can only run while focus is already inside the dialog subtree; the `!dialogRef.current.contains(document.activeElement)` containment branch could therefore never evaluate true and delivered no actual containment guarantee. Per the review's recommendation, removed the inert branch and replaced its misleading comment with an accurate note: this is a deliberate boundary-only trap (a `document`-level `keydown`/`focusin` listener would be required for true containment, and is unnecessary for the current always-focus-the-heading-on-open flows). No behavior change in any real scenario — it only removes a comment that implied a guarantee the wiring cannot provide.
+
+## Skipped Issues
+
+None.
+
+## Prior Iterations
+
+Iterations 1 and 2 fixed the earlier batches of findings (15 in iter-1, then the iter-3 review's WR-01/IN-02/IN-03 set). The IN-02 (favicon.ico coupling) and IN-03 (OidcRedirect visible status) fixes were confirmed clean by the final re-review. This iteration-3 report supersedes those and records the final state: the WR-01 regression (CR-01) and its inert containment guard (IN-01) are now resolved, with all CI gates green.
+
+---
+
+_Fixed: 2026-06-18T14:04:00Z_
+_Fixer: Claude (gsd-code-fixer)_
+_Iteration: 3_
diff --git a/.planning/phases/17-ui-optimization-polish/17-REVIEW.iter2.md b/.planning/phases/17-ui-optimization-polish/17-REVIEW.iter2.md
new file mode 100644
index 0000000..60ec5fd
--- /dev/null
+++ b/.planning/phases/17-ui-optimization-polish/17-REVIEW.iter2.md
@@ -0,0 +1,167 @@
+---
+phase: 17-ui-optimization-polish
+reviewed: 2026-06-18T00:00:00Z
+depth: deep
+files_reviewed: 13
+files_reviewed_list:
+ - apps/pwa/e2e/admin.spec.ts
+ - apps/pwa/e2e/layout.spec.ts
+ - apps/pwa/index.html
+ - apps/pwa/package.json
+ - apps/pwa/pwa-assets.config.ts
+ - apps/pwa/src/App.tsx
+ - apps/pwa/src/components/BrandSlot.tsx
+ - apps/pwa/src/components/CalendarShell.tsx
+ - apps/pwa/src/components/CredentialSheet.tsx
+ - apps/pwa/src/components/SettingsSheet.tsx
+ - apps/pwa/src/routes/AdminPage.tsx
+ - apps/pwa/src/styles/tokens.css
+ - apps/pwa/vite.config.ts
+findings:
+ critical: 0
+ warning: 8
+ info: 7
+ total: 15
+status: issues_found
+---
+
+# Phase 17: Code Review Report
+
+**Reviewed:** 2026-06-18T00:00:00Z
+**Depth:** deep
+**Files Reviewed:** 13
+**Status:** issues_found
+
+## Summary
+
+Phase 17 is UI optimization/polish: brand logo swap, PWA manifest/icon hand-maintenance, an admin two-tab ARIA strip, a success toast, and a searchable timezone combobox, plus structural layout/admin Playwright suites. No structural-findings pre-pass was provided.
+
+The code is generally careful — XSS surfaces are plain-text JSX, password fields use `new-password` autocomplete and are never pre-filled, the OIDC `authorizationUrl` null is guarded before navigation, and touch targets are consistently ≥44px. I found **no BLOCKERs** (no injection, no secret leakage, no data-loss path, no crash on the happy path).
+
+There are real correctness/robustness defects worth fixing before ship: the **admin tab keyboard handler half-implements the WAI-ARIA tabs pattern** (no Home/End, no wrap); the **timezone combobox `aria-activedescendant`/highlight can desync after filtering** and **drops Tab-to-commit**; the **success toast does not re-announce** repeated identical messages and its `whiteSpace: nowrap` is a latent Rule-2 horizontal-overflow hazard against the project's own layout suite; **none of the modal dialogs trap focus** despite `aria-modal="true"`; and several `window.matchMedia` reads at render time **do not react to resize/orientation**, a stale-UI class this project explicitly cares about (iPad rotation).
+
+## Warnings
+
+### WR-01: Modal dialogs declare `aria-modal="true"` but do not trap focus
+
+**File:** `apps/pwa/src/components/CredentialSheet.tsx:173-176`, `apps/pwa/src/components/SettingsSheet.tsx:199-202` (plus ChangePasswordSheet ~667-701 and LinkOidcSheet ~979-1013), `apps/pwa/src/routes/AdminPage.tsx:1420-1423` (ResetPasswordSheet)
+**Issue:** Every sheet sets `role="dialog"` + `aria-modal="true"` and focuses the heading/close button on open, but none implements a focus trap. Tab/Shift-Tab can move focus out of the dialog to content behind the backdrop (still in the DOM). `aria-modal="true"` asserts to assistive tech that focus is contained — it is not. The app's stated UX hard-constraint is "slick and low-friction for a non-technical Apple member"; VoiceOver/keyboard users will escape the dialog silently and interact with occluded background controls.
+**Fix:** Add a focus trap — capture Tab/Shift-Tab in the dialog keydown handler and cycle between first/last focusable descendants, ideally as a shared `useFocusTrap(ref)` hook reused by all sheets:
+```tsx
+onKeyDown={(e) => {
+ if (e.key !== 'Tab') return;
+ const f = dialogRef.current?.querySelectorAll(
+ 'a[href],button:not([disabled]),input:not([disabled]),[tabindex]:not([tabindex="-1"])');
+ if (!f?.length) return;
+ const first = f[0], last = f[f.length - 1];
+ if (e.shiftKey && document.activeElement === first) { e.preventDefault(); last.focus(); }
+ else if (!e.shiftKey && document.activeElement === last) { e.preventDefault(); first.focus(); }
+}}
+```
+
+### WR-02: Admin tab strip keyboard nav is incomplete (no Home/End, no explicit wrap)
+
+**File:** `apps/pwa/src/routes/AdminPage.tsx:205-225`
+**Issue:** `handleTabKeyDown` handles only `ArrowRight`/`ArrowLeft`, and the next/prev computation is a two-state toggle that does not wrap (ArrowRight on the Settings tab is a no-op rather than wrapping to Members). The WAI-ARIA tabs pattern requires `Home`/`End` to jump to first/last tab. `admin.spec.ts` (lines 134-152) only exercises the Arrow keys, so this gap is untested and ships a half-pattern.
+**Fix:** Handle `Home`/`End` and decide wrap behavior explicitly:
+```tsx
+const order = ['members', 'settings'] as const;
+const idx = order.indexOf(current);
+let next: typeof order[number] | null = null;
+if (e.key === 'ArrowRight') next = order[(idx + 1) % order.length];
+else if (e.key === 'ArrowLeft') next = order[(idx - 1 + order.length) % order.length];
+else if (e.key === 'Home') next = order[0];
+else if (e.key === 'End') next = order[order.length - 1];
+if (next) { e.preventDefault(); setActiveTab(next); /* focus #admin-tab-${next} */ }
+```
+
+### WR-03: Success toast does not re-announce repeated identical messages
+
+**File:** `apps/pwa/src/routes/AdminPage.tsx:62-69`, `1028-1065`
+**Issue:** The toast is a single `role="status" aria-live="polite"` region rendering the `toast` string. If the same message fires twice (two password resets, two "Member added.") and the second `setToast('…')` lands before the first cleared, React's state-equality short-circuit means the DOM text does not change, so `aria-live` does not re-announce — the second success is silent to screen-reader users, and the 3s auto-dismiss timer (keyed on `toast` identity) does not reset for an identical string.
+**Fix:** Make each toast a distinct value and remount it so AT re-announces and the timer resets:
+```tsx
+const [toast, setToast] = useState<{ id: number; msg: string } | null>(null);
+const show = (msg: string) => setToast({ id: Date.now(), msg });
+// effect dep: [toast?.id]; render: ` and its children are indented inconsistently (section at one level, children shallower), and both the Members and Local Accounts sections carry `marginBottom: var(--space-8)`, adding trailing space at the panel boundary. Cosmetic, but will trip future edits.
+**Fix:** Reformat the panel JSX — Prettier should normalize it. Confirm `pnpm --filter @familysync/pwa lint`/format was run (a recurring pre-push gate on this project).
+
+### IN-06: Toast and dialog `zIndex` overlap (300/301)
+
+**File:** `apps/pwa/src/routes/AdminPage.tsx:1033` (toast 300) vs `CredentialSheet.tsx:169,189` (backdrop 300 / sheet 301), ResetPasswordSheet (300/301)
+**Issue:** The toast shares `zIndex: 300` with the sheet backdrops. If a toast lingers while a sheet opens within the 3s window, paint order becomes DOM-order-dependent and the toast can render under the backdrop dim. Low likelihood, but the z-index scale is not cleanly layered.
+**Fix:** Put the toast above dialogs (e.g. `zIndex: 400`) and document a named z-index scale (backdrop/sheet/toast) in `tokens.css`.
+
+### IN-07: `Intl.DateTimeFormat()` recomputed every render in the calendar-config path
+
+**File:** `apps/pwa/src/components/CalendarShell.tsx:159`, `apps/pwa/src/routes/AdminPage.tsx:146`
+**Issue:** `Intl.DateTimeFormat().resolvedOptions().timeZone` is called inline in render. Cheap, but in `CalendarShell` it feeds `useCalendarApp` config, whose stability the file's own comments warn about. (Flagged as a note, not a perf-scope item, because it touches the calendar-app config the code explicitly tries to keep stable.)
+**Fix:** `const displayTimeZone = useMemo(() => Intl.DateTimeFormat().resolvedOptions().timeZone, [])`.
+
+---
+
+_Reviewed: 2026-06-18T00:00:00Z_
+_Reviewer: Claude (gsd-code-reviewer)_
+_Depth: deep_
diff --git a/.planning/phases/17-ui-optimization-polish/17-REVIEW.iter3.md b/.planning/phases/17-ui-optimization-polish/17-REVIEW.iter3.md
new file mode 100644
index 0000000..70cf986
--- /dev/null
+++ b/.planning/phases/17-ui-optimization-polish/17-REVIEW.iter3.md
@@ -0,0 +1,95 @@
+---
+phase: 17-ui-optimization-polish
+reviewed: 2026-06-18T00:00:00Z
+depth: deep
+files_reviewed: 16
+files_reviewed_list:
+ - apps/pwa/e2e/admin.spec.ts
+ - apps/pwa/e2e/layout.spec.ts
+ - apps/pwa/index.html
+ - apps/pwa/package.json
+ - apps/pwa/pwa-assets.config.ts
+ - apps/pwa/scripts/copy-pwa-icons.mjs
+ - apps/pwa/src/App.tsx
+ - apps/pwa/src/components/BrandSlot.tsx
+ - apps/pwa/src/components/CalendarShell.tsx
+ - apps/pwa/src/components/CredentialSheet.tsx
+ - apps/pwa/src/components/SettingsSheet.tsx
+ - apps/pwa/src/hooks/useFocusTrap.ts
+ - apps/pwa/src/hooks/useIsPhone.ts
+ - apps/pwa/src/routes/AdminPage.tsx
+ - apps/pwa/src/styles/tokens.css
+ - apps/pwa/vite.config.ts
+findings:
+ critical: 0
+ warning: 1
+ info: 3
+ total: 4
+status: issues_found
+---
+
+# Phase 17: Code Review Report (Re-Review After Auto-Fix)
+
+**Reviewed:** 2026-06-18T00:00:00Z
+**Depth:** deep
+**Files Reviewed:** 16
+**Status:** issues_found
+
+## Summary
+
+This is a re-review of Phase 17 (UI optimization/polish) after auto-fixes were applied to the prior 15 findings (8 warnings, 7 info). I re-read every listed file at deep depth, traced the just-changed code (focus-trap wiring across the 5 sheets, the new `useIsPhone`/`useFocusTrap` hooks, admin tab keyboard handling, the toast re-announce/wrapping changes, the timezone combobox active-index/Tab-commit logic, and the cross-platform icon-copy script), and confirmed the fixes against the surrounding call sites for regressions.
+
+**All 8 prior warnings and all 7 prior info items are correctly resolved.** Both local gates pass clean: `pnpm --filter @familysync/pwa typecheck` (tsc + e2e tsconfig) and `pnpm --filter @familysync/pwa lint` (eslint `--max-warnings 0`) both succeed with no output. I found **no BLOCKERs** and **no regressions** introduced by the fixes.
+
+What the fixes got right and why they don't regress:
+- **Focus trap** (`useFocusTrap`) is wired into all five dialogs. The child sheets (`ChangePasswordSheet`/`LinkOidcSheet`) are rendered as DOM **siblings** of the `SettingsSheet` dialog div (after the `
` at SettingsSheet.tsx:563), not descendants, so the parent trap's `querySelectorAll` cannot capture child-sheet focusables and there is no double-trap conflict — each sheet owns its own trap.
+- **Combobox desync** is genuinely fixed: `tzActiveIndexClamped` now drives the visual highlight (AdminPage.tsx:955), `aria-activedescendant` (:838), and the Enter/Tab commit (:879/:887) from one clamped source. `aria-selected` correctly stays bound to `effectiveTimezoneInput` (:961) — that is the right ARIA distinction (selected value vs. active option), not a residual bug.
+- **Tab-to-commit** commits the clamped option without `preventDefault`, the blur timer is now `setTimeout(…, 0)` and is cleared on focus, on select, and on unmount (AdminPage.tsx:115-119) — no setState-after-unmount path remains.
+- **Toast** is keyed on a unique `{id, msg}` so identical repeats remount and `aria-live` re-announces; `whiteSpace: nowrap` is removed so it wraps within `maxWidth: 90vw` (no Rule 2 overflow hazard); z-index raised to 400, above all sheet backdrops (max 303), resolving the prior overlap.
+- **`useIsPhone`/`useMediaQuery`** subscribe via `addEventListener('change', …)` and are now used at every former inline `matchMedia` site (App, CalendarShell, all sheets, AdminPage), so iPad rotation across 767px reflows correctly. SSR guard returns `false` cleanly.
+
+The one remaining WARNING is a pre-existing focus-trap robustness gap (not introduced this phase, but now load-bearing because `aria-modal` promises containment). The three INFO items are minor and non-blocking.
+
+## Warnings
+
+### WR-01: `useFocusTrap` only wraps at the boundaries — focus can still escape via hidden/zero-size focusables
+
+**File:** `apps/pwa/src/hooks/useFocusTrap.ts:25-48`
+**Issue:** The trap queries `button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])` and filters only `!disabled` and `tabindex !== '-1'`. It does not exclude elements that are `display:none`, `visibility:hidden`, `hidden`, or zero-size. In the current sheets every focusable is visible, so the trap works today. But the pattern has two latent escape paths: (1) if a dialog ever conditionally renders a focusable inside a `hidden`/collapsed block, that element joins the `first`/`last` computation and the wrap math targets an unfocusable node — `last.focus()` becomes a no-op and Tab leaks to background content (which `aria-modal="true"` asserts is impossible); (2) the trap only intervenes at the exact first/last boundary, so it relies on the browser's natural Tab order between them being correct and contained. This is the kind of half-implemented trap the prior WR-01 set out to eliminate; the fix is correct for the present DOM but fragile for future edits.
+**Fix:** Filter to genuinely focusable, rendered elements before computing first/last, e.g.:
+```ts
+.filter((el) => {
+ if (el.hasAttribute('disabled') || el.getAttribute('tabindex') === '-1') return false;
+ if (el.hasAttribute('hidden') || (el as HTMLElement).offsetParent === null) return false;
+ const r = el.getBoundingClientRect();
+ return r.width > 0 && r.height > 0;
+});
+```
+Alternatively, document that all dialog focusables must be unconditionally rendered and visible while the dialog is open.
+
+## Info
+
+### IN-01: Focus trap does not pull focus back when `activeElement` is already outside the dialog
+
+**File:** `apps/pwa/src/hooks/useFocusTrap.ts:36-47`
+**Issue:** The handler wraps only when `document.activeElement === first` (Shift+Tab) or `=== last` (Tab). Each sheet focuses its heading/close button on open, so the trap engages from inside. But `aria-modal="true"` does not actually prevent the background DOM (still mounted behind the backdrop) from receiving focus — e.g. a programmatic focus, or a browser quirk, could land focus outside the dialog, and then neither boundary condition matches, so Tab moves through background content until it happens to re-enter. This is the residual weakness of a boundary-only trap versus a containment trap (which checks `dialogRef.current.contains(document.activeElement)` and redirects when false). Low likelihood given the open-focus behavior; noted for completeness.
+**Fix:** Add a containment guard: if `!dialogRef.current.contains(document.activeElement)` on Tab, `preventDefault()` and focus `first`.
+
+### IN-02: `favicon.ico` is referenced by `index.html` but not produced by `pwa:icons`
+
+**File:** `apps/pwa/index.html:7`, `apps/pwa/scripts/copy-pwa-icons.mjs:21-27`
+**Issue:** `index.html` links `/favicon.ico`, and the file is committed in `public/` (967 bytes). The new `copy-pwa-icons.mjs` `COPIES` table generates `favicon.svg` (from `logo.svg`) and the PNGs, but the `minimal2023Preset` does not emit a `.ico`, so `favicon.ico` is hand-maintained outside the script. This is the same invisible-coupling class the prior WR-08 flagged, just narrowed: regenerating icons leaves `favicon.ico` stale relative to a new brand mark, with nothing to catch it. The script's own header says "Keep COPIES in sync with the manifest," but the `.ico` link in `index.html` has no such pointer.
+**Fix:** Either drop the `favicon.ico` link (the SVG favicon + `sizes="any"` covers modern browsers) or add a comment in `copy-pwa-icons.mjs`/`index.html` noting `favicon.ico` is hand-maintained and must be regenerated manually when the brand mark changes.
+
+### IN-03: `OidcRedirect` placeholder renders an empty `aria-hidden` div for a full render cycle
+
+**File:** `apps/pwa/src/App.tsx:74-82`
+**Issue:** The prior IN-01 fix correctly moved the navigation into `useEffect`. The component now renders `` and the redirect fires post-commit. For the OIDC-only-mode unauthenticated path this means a brief blank frame before `window.location.replace('/api/login')` unloads the page. Functionally fine and a strict improvement over the render-phase side effect, but the blank `aria-hidden` div gives screen-reader/keyboard users no "redirecting…" affordance during the gap.
+**Fix:** Render a minimal visible "Redirecting to sign in…" status (e.g. `role="status"`) instead of an empty `aria-hidden` div, so the transition is perceivable if the redirect is slow.
+
+---
+
+_Reviewed: 2026-06-18T00:00:00Z_
+_Reviewer: Claude (gsd-code-reviewer)_
+_Depth: deep_
+_Re-review: prior 15 findings all confirmed resolved; gates (typecheck + lint) pass clean_
diff --git a/.planning/phases/17-ui-optimization-polish/17-REVIEW.md b/.planning/phases/17-ui-optimization-polish/17-REVIEW.md
new file mode 100644
index 0000000..0a895d6
--- /dev/null
+++ b/.planning/phases/17-ui-optimization-polish/17-REVIEW.md
@@ -0,0 +1,128 @@
+---
+phase: 17-ui-optimization-polish
+reviewed: 2026-06-18T00:00:00Z
+depth: deep
+files_reviewed: 16
+files_reviewed_list:
+ - apps/pwa/e2e/admin.spec.ts
+ - apps/pwa/e2e/layout.spec.ts
+ - apps/pwa/index.html
+ - apps/pwa/package.json
+ - apps/pwa/pwa-assets.config.ts
+ - apps/pwa/scripts/copy-pwa-icons.mjs
+ - apps/pwa/src/App.tsx
+ - apps/pwa/src/components/BrandSlot.tsx
+ - apps/pwa/src/components/CalendarShell.tsx
+ - apps/pwa/src/components/CredentialSheet.tsx
+ - apps/pwa/src/components/SettingsSheet.tsx
+ - apps/pwa/src/hooks/useFocusTrap.ts
+ - apps/pwa/src/hooks/useIsPhone.ts
+ - apps/pwa/src/routes/AdminPage.tsx
+ - apps/pwa/src/styles/tokens.css
+ - apps/pwa/vite.config.ts
+findings:
+ critical: 1
+ warning: 0
+ info: 1
+ total: 2
+status: issues_found
+---
+
+# Phase 17: Code Review Report (Final Re-Review After Iter-3 Auto-Fixes)
+
+**Reviewed:** 2026-06-18T00:00:00Z
+**Depth:** deep
+**Files Reviewed:** 16
+**Status:** issues_found
+
+## Summary
+
+This is the final re-review of Phase 17 after the second round of auto-fixes, which targeted the three iter-3 findings:
+
+- **WR-01** — `useFocusTrap` hidden/zero-size focusable exclusion + containment guard.
+- **IN-03** — `App.tsx` `OidcRedirect` now renders a visible "Redirecting to sign in…" status.
+- **IN-02** — favicon.ico hand-maintained coupling documented in `copy-pwa-icons.mjs` and `index.html`.
+
+I re-read every listed file at deep depth and traced the changed code against its call sites and the existing test suite.
+
+**Two of the three fixes are correct and regression-free:**
+- **IN-03 (OidcRedirect):** Correct. The navigation stays in `useEffect` (no render-phase side effect), and the placeholder is now a perceivable `role="status"` "Redirecting to sign in…" (App.tsx:83-97). No regression.
+- **IN-02 (favicon.ico coupling):** Correct and complete. Both `copy-pwa-icons.mjs` (lines 13-17) and `index.html` (line 7) now carry the hand-maintained-`.ico` pointer. Verified on disk: `favicon.svg` is byte-identical to `logo.svg` (produced by the `COPIES` table), and `favicon.ico` (967 B) is committed separately. The invisible coupling is now documented at both ends.
+
+**The WR-01 fix introduces a CR-tier regression.** The new visibility filter in `useFocusTrap.ts` (lines 36-38) relies on `offsetParent` and `getBoundingClientRect()` width/height. Both are `null`/`0` under jsdom — the environment the existing focus-trap unit tests run in — so the filter now excludes **every** focusable, `focusable.length === 0` short-circuits, and the trap silently stops wrapping focus. This breaks the two pre-existing `EventForm.test.tsx` WR-07 tests and makes `pnpm test` (a CI gate per CLAUDE.md) fail.
+
+Gate status after the fixes:
+- `pnpm --filter @familysync/pwa typecheck` → **pass** (tsc + e2e tsconfig).
+- `pnpm --filter @familysync/pwa lint` → **pass** (eslint `--max-warnings 0`).
+- `pnpm --filter @familysync/pwa test` (vitest) → **FAIL**: 2 failed / 264 passed / 266 total. Both failures are the WR-07 focus-trap tests, caused directly by the WR-01 change under review.
+
+The IN-01 containment guard added alongside WR-01 is functionally inert (the handler is only wired to the dialog's `onKeyDown`, which cannot fire when focus is outside the dialog), but it is harmless — recorded as INFO.
+
+## Critical Issues
+
+### CR-01: `useFocusTrap` visibility filter excludes all focusables under jsdom — breaks the focus-trap test suite (CI gate fails)
+
+**File:** `apps/pwa/src/hooks/useFocusTrap.ts:36-38`
+**Issue:** The WR-01 fix added a "rendered/visible" filter to the focusable query:
+```ts
+if (el.hasAttribute('hidden') || el.offsetParent === null) return false;
+const r = el.getBoundingClientRect();
+return r.width > 0 && r.height > 0;
+```
+In a real browser this is correct. But the existing focus-trap regression tests (`apps/pwa/src/components/EventForm.test.tsx`, the two `WR-07` cases at lines 718-764) run under **jsdom**, where:
+- `getBoundingClientRect()` returns all-zero geometry for every element (`width === 0`, `height === 0`), and
+- `offsetParent` is `null` for every element.
+
+Either condition alone causes the filter to reject **every** focusable. `focusable.length` becomes `0`, the handler hits the `if (focusable.length === 0) return;` early-out (line 41), and Tab/Shift+Tab no longer wrap. Both WR-07 tests now fail:
+
+```
+FAIL src/components/EventForm.test.tsx > WR-07: Tab from last focusable element wraps focus to first inside dialog
+FAIL src/components/EventForm.test.tsx > WR-07: Shift+Tab from first focusable element wraps focus to last inside dialog
+Test Files 1 failed | 21 passed (22)
+ Tests 2 failed | 264 passed (266)
+```
+
+`pnpm test` (→ `vitest run`) is one of the CI gates the project requires to pass before push (CLAUDE.md "Frustrations" directive + the CI-checks-conformance memory). This regression ships as part of the file under review, so it is in scope even though `EventForm.test.tsx` is not in the listed-files set — those tests exist specifically to guard the changed behavior.
+
+**Fix:** Make the visibility filter tolerant of a non-layout (jsdom) environment, so it excludes genuinely hidden nodes in a browser without nuking all nodes in tests. Treat zero-geometry as "visible" when no layout engine is present, and gate on `offsetParent` only when geometry is meaningful:
+```ts
+.filter((el) => {
+ if (el.hasAttribute('disabled') || el.getAttribute('tabindex') === '-1') return false;
+ if (el.hasAttribute('hidden')) return false;
+ // jsdom has no layout: getBoundingClientRect() is all-zero and offsetParent is
+ // null for every node. Only apply the visibility heuristic when a real layout
+ // exists, so unit tests still see focusables.
+ const r = el.getBoundingClientRect();
+ const hasLayout = r.width > 0 || r.height > 0 || el.offsetParent !== null;
+ if (!hasLayout) return true; // no layout engine → don't filter on visibility
+ if (el.offsetParent === null) return false;
+ return r.width > 0 && r.height > 0;
+});
+```
+Alternatively, stub `getBoundingClientRect`/`offsetParent` in the test setup so jsdom reports non-zero geometry — but the production-side guard above is the safer minimal change, since other future tests will hit the same wall. Either way, re-run `pnpm --filter @familysync/pwa test` and confirm both WR-07 cases pass before considering this resolved.
+
+## Info
+
+### IN-01: Focus-trap containment guard is unreachable as wired (harmless dead branch)
+
+**File:** `apps/pwa/src/hooks/useFocusTrap.ts:50-54`
+**Issue:** The IN-01 fix added a containment guard:
+```ts
+if (!dialogRef.current.contains(document.activeElement)) {
+ e.preventDefault();
+ first.focus();
+ return;
+}
+```
+The comment claims this catches the case where "focus has somehow landed outside the dialog ... Tab would walk background content." But the handler is only attached to each dialog container's `onKeyDown` (verified across all 5 sheets + EventForm + SeriesEditPrompt — no `document`-level listener exists). React's synthetic `onKeyDown` on the dialog div only fires when the keydown event's target is **inside** the dialog subtree (the event must bubble up through that div). When `document.activeElement` is genuinely outside the dialog, the keydown fires on that outside element and bubbles through `document`, **not** through the dialog div — so `handleDialogKeyDown` never runs, and `dialogRef.current.contains(document.activeElement)` is effectively always `true` whenever this code executes. The guard is therefore a no-op in practice: it does not deliver the containment guarantee its comment promises.
+
+This is not a correctness bug (it never produces wrong behavior), so it is INFO, not a blocker. But it is worth noting that the IN-01 concern (focus escaping a boundary-only trap) is **not actually addressed** by this change.
+
+**Fix:** If true containment is desired, move the trap to a `document`-level `keydown` (or `focusin`) listener mounted while the dialog is open, so it can intercept Tab/focus originating outside the dialog. If the boundary-only trap is considered sufficient (it is, for the present always-focus-the-heading-on-open flows), drop the unreachable containment branch and its comment to avoid implying a guarantee the code does not provide.
+
+---
+
+_Reviewed: 2026-06-18T00:00:00Z_
+_Reviewer: Claude (gsd-code-reviewer)_
+_Depth: deep_
+_Re-review: IN-02 + IN-03 fixes confirmed clean; WR-01 fix regresses the focus-trap test suite (CR-01) and its IN-01 containment guard is inert. typecheck + lint pass; `pnpm test` FAILS (2 WR-07 tests)._
diff --git a/.planning/phases/17-ui-optimization-polish/17-SECURITY.md b/.planning/phases/17-ui-optimization-polish/17-SECURITY.md
new file mode 100644
index 0000000..eefcfe0
--- /dev/null
+++ b/.planning/phases/17-ui-optimization-polish/17-SECURITY.md
@@ -0,0 +1,92 @@
+---
+phase: 17
+slug: ui-optimization-polish
+status: verified
+threats_open: 0
+asvs_level: 1
+created: 2026-06-18
+---
+
+# Phase 17 — Security
+
+> Per-phase security contract: threat register, accepted risks, and audit trail.
+
+Phase 17 is a UI optimization & polish phase. Every plan carried a plan-time
+`{toast.msg}
+```
+
+### WR-04: Toast `whiteSpace: nowrap` is a latent horizontal-overflow regression against Rule 2
+
+**File:** `apps/pwa/src/routes/AdminPage.tsx:1054-1055`
+**Issue:** The toast sets `whiteSpace: 'nowrap'` with `maxWidth: '90vw'`. `nowrap` + `maxWidth` does not shrink text; it overflows. A longer/localized toast on a 390px viewport will exceed 90vw and, because the toast is `position: fixed`, contribute to `documentElement.scrollWidth` — violating `layout.spec.ts` Rule 2 (lines 176-200), which asserts no horizontal overflow on `/calendar` and `/lists`. Current strings are short, so the bug is latent, not active, but it is a direct hazard to the project's own quality bar.
+**Fix:** Remove `whiteSpace: 'nowrap'` (let it wrap), or bound the width and use `overflow:hidden; text-overflow:ellipsis`. Wrapping is safer for a toast that may localize.
+
+### WR-05: `matchMedia(...)` read at render time does not react to resize/orientation
+
+**File:** `apps/pwa/src/App.tsx:64-66` (`isPhone()`), `apps/pwa/src/components/CalendarShell.tsx:74-76`, `apps/pwa/src/components/SettingsSheet.tsx:135`, `apps/pwa/src/components/CredentialSheet.tsx:156`, `apps/pwa/src/routes/AdminPage.tsx:59`, `1378-1379`
+**Issue:** These components compute `phone` once per render via synchronous `matchMedia('(max-width: 767px)').matches`, with no `change` listener. Rotating an iPad across 767px (or resizing a desktop window across the breakpoint) does not trigger a re-render, so the layout (FAB vs toolbar button in `CalendarShell`, bottom-sheet vs centered modal in the sheets, content `paddingBottom` in `App`) stays stale until an unrelated state change forces a re-render. The developer profile explicitly flags resize/orientation correctness; iPad rotation is a realistic trigger for this cross-ecosystem app.
+**Fix:** Use a `useMediaQuery` hook backed by `matchMedia.addEventListener('change', …)` so components re-render on breakpoint crossing; share a single `phone` value through context/hook so all call sites stay consistent.
+
+### WR-06: Timezone combobox `aria-activedescendant`/highlight can desync after filtering
+
+**File:** `apps/pwa/src/routes/AdminPage.tsx:819-821`, `833-837`, `839-845`, `912-919`
+**Issue:** `onChange` resets `tzActiveIndex` to 0 while `ArrowDown` clamps against `filteredZones.length - 1` from the *current render closure*. With batched updates, interleavings exist where `tzActiveIndex` (and thus `aria-activedescendant={tz-opt-${tzActiveIndex}}`, line 820) references an option index that no longer exists after the filtered list shrinks (e.g., active 12, then a keystroke filters to 3 rows before re-clamp). Separately, the visual highlight uses `i === tzActiveIndex` (line 913) while `aria-selected` uses `tz === effectiveTimezoneInput` (line 919) — two different bases, so the highlighted row and the AT-announced row can disagree.
+**Fix:** Derive a clamped active index in render and use it everywhere (visual + `aria-activedescendant`): `const activeIndex = Math.min(tzActiveIndex, Math.max(0, filteredZones.length - 1))`, or reset `tzActiveIndex` to 0 in a `useEffect` keyed on `tzSearch`.
+
+### WR-07: Timezone combobox drops Tab-to-commit and relies on a fragile blur timeout
+
+**File:** `apps/pwa/src/routes/AdminPage.tsx:838-865`, `927`
+**Issue:** (1) `onKeyDown` handles ArrowUp/Down/Enter/Escape but not `Tab`. Tabbing out with the listbox open and an option highlighted moves focus to Save without committing — the input/`effectiveTimezoneInput` still holds the raw search text, so the admin can attempt to save a partial string (server 400s, but the UX is a confusing failure). (2) The `onBlur` 120ms `setTimeout` to let an option's `onClick` fire is a race; since options already `onMouseDown` `preventDefault()` (line 927), blur won't fire on option click, so the 120ms hack may be unnecessary. The `tzBlurTimer` is cleared on focus/select but not on unmount.
+**Fix:** Commit the active option on `Tab` (without `preventDefault`, so focus still advances); clear `tzBlurTimer` in an unmount cleanup effect; reassess/remove the 120ms blur delay now that `onMouseDown` preventDefault is in place.
+
+### WR-08: `pwa:icons` script is non-portable and silently coupled to generated filenames
+
+**File:** `apps/pwa/package.json:16`
+**Issue:** `pwa:icons` chains the assets generator with five `cp` commands. (1) `cp` is Unix-only — breaks on Windows contributors and minimal CI containers. (2) It hard-codes the generator's output names (`pwa-192x192.png`, `maskable-icon-512x512.png`, `apple-touch-icon-180x180.png`); a generator version bump that renames outputs breaks it with an opaque `cp: cannot stat`. (3) The manifest icon entries in `vite.config.ts:38-42` (`/icon-192.png`, etc.) only stay in sync because of these manual renames — an invisible coupling with no test. Regenerating icons without running the full script leaves the manifest referencing stale files.
+**Fix:** Configure the generator to emit the final filenames directly, or replace the `cp` chain with a small cross-platform Node script (`fs.copyFileSync`). At minimum, add a comment in `vite.config.ts` by the icon entries pointing at the `pwa:icons` rename step so the coupling is discoverable.
+
+## Info
+
+### IN-01: `OidcRedirect` navigates as a render-phase side effect
+
+**File:** `apps/pwa/src/App.tsx:77-80`
+**Issue:** `OidcRedirect` calls `window.location.replace('/api/login')` directly in the function body (render phase). React may render a component more than once (StrictMode double-invoke in dev, concurrent re-renders); side effects in render are an anti-pattern. It works because `replace` is idempotent and the page unloads, but it is fragile.
+**Fix:** Move the navigation into `useEffect(() => { window.location.replace('/api/login'); }, [])` and render the placeholder.
+
+### IN-02: Inconsistent `exhaustive-deps` disables across sibling dialogs
+
+**File:** `apps/pwa/src/components/CredentialSheet.tsx:95`, `apps/pwa/src/components/SettingsSheet.tsx:605`
+**Issue:** The Escape `useEffect` disables `react-hooks/exhaustive-deps` (because `handleClose` is referenced but not listed), while the `LinkOidcSheet`/`ResetPasswordSheet` versions list `[isOpen, onClose]` with no disable. The blanket disable also hides any future missing dep added to that effect.
+**Fix:** Wrap `handleClose` in `useCallback` and add it to the dep array, removing the disable; make the pattern consistent across all sheets.
+
+### IN-03: `isPhone`/`phone` 767px check duplicated across ~6 sites
+
+**File:** `apps/pwa/src/App.tsx:64-66`, `CalendarShell.tsx:74-76`, `SettingsSheet.tsx:135`, `CredentialSheet.tsx:156`, `AdminPage.tsx:59`, `1378-1379`
+**Issue:** The same breakpoint check is reimplemented in two spellings (`isPhone()` helper vs inline `matchMedia`), and the JS hard-codes `767` while `tokens.css` declares `--bp-tablet: 768px`. Drift risk if the breakpoint changes.
+**Fix:** Extract one `useIsPhone()` hook (ideally the resize-aware one from WR-05) and import it everywhere; reference the breakpoint in a single place.
+
+### IN-04: Dead placeholder brand tokens retained
+
+**File:** `apps/pwa/src/styles/tokens.css:103-104,107`
+**Issue:** `--brand-logo-bg`, `--brand-logo-text`, and `--brand-app-name` are leftovers from the Phase 19 "FS initials circle." BrandSlot now renders `logo.svg` and reads only `--brand-logo-size`/`--brand-logo-border-radius`; `--brand-app-name` is commented "drives doc only — not used as CSS content." These are dead declarations.
+**Fix:** Remove them, or add a comment that they're retained intentionally for a planned fallback.
+
+### IN-05: Admin members-panel JSX has inconsistent indentation / stacked bottom margins
+
+**File:** `apps/pwa/src/routes/AdminPage.tsx:364-418`
+**Issue:** Inside `admin-panel-members`, `` with "FamilySync" text remains unchanged (screen readers still read the + name; the logo is purely decorative) +- The tagline `
` remains unchanged +- `LoginPage` layout is NOT touched — the seam contract from Phase 19 is honored + +**`--brand-logo-border-radius` update:** +- The placeholder used `50%` (circle). The real logo may be a rounded square or have + its own shape baked in. Phase 17 sets this token to the shape that suits the logo: + - If the logo SVG is a circle/rounded shape by design: set to `0` (no extra clipping) + - If the logo is a square mark needing rounding: set to `12px` (warm/rounded brief) + - Final value determined when the logo is generated and reviewed at checkpoint + +**No `LoginPage` changes** — this is enforced by the Phase 19 seam contract. + +### `index.html` wiring contract + +Current state: one ``, one ``, +no ``. + +After Phase 17: + +```html +
+ + + + + + + + + +`.
+
+**Backdrop:** unchanged — `position: fixed; inset: 0; background: var(--color-overlay)`.
+
+**Verification:** confirm via playwright-cli at both 390×844 (phone — bottom sheet) and
+1280×720 (desktop — centered modal) before merging.
+
+### D-10 — Admin two-tab navigation
+
+**Surface:** AdminPage.tsx
+
+**Structure:** horizontal tab strip at the top of the AdminPage content column,
+replacing the current single-page long-scroll layout.
+
+**Two tabs:**
+
+| Tab | Label | Contents |
+|-----|-------|----------|
+| Tab 1 | "Members & Accounts" | MEMBERS section (credential management) + LOCAL ACCOUNTS section (create member + reset-password) |
+| Tab 2 | "Settings" | SHARED CALENDAR section + TIMEZONE section |
+
+**Tab strip visual contract:**
+
+```
+┌────────────────────────────────────────────────────────────┐
+│ [Members & Accounts] [Settings] │
+│ ─────────────────── 2px active border-bottom │
+│ 1px var(--color-border-subtle) full-width rule below strip │
+└────────────────────────────────────────────────────────────┘
+```
+
+Tab strip container:
+- `display: flex; borderBottom: 1px solid var(--color-border-subtle)`
+- `marginBottom: var(--space-6)` (24px gap before first section)
+
+Individual tab button:
+- `background: none; border: none; cursor: pointer`
+- `padding: var(--space-3) var(--space-4)` (12px 16px)
+- `minHeight: 44px` (WCAG tap target)
+- `fontSize: var(--text-label-size, 13px)` (13px)
+- Inactive: `fontWeight: 400; color: var(--color-text-secondary); borderBottom: 2px solid transparent`
+- Active: `fontWeight: 600; color: var(--color-text-primary); borderBottom: 2px solid var(--color-member-0)`
+- `transition: color 0.1s ease, border-color 0.1s ease`
+- `fontFamily: var(--font-family-base)`
+
+**Accessibility (roving tabindex / ARIA tabs pattern):**
+- Tab strip container: `role="tablist"`
+- Each tab button: `role="tab"`, `aria-selected={isActive}`,
+ `aria-controls="{panel-id}"`, `id="{tab-id}"`
+- Inactive tabs: `tabIndex={-1}` (roving tabindex — only active tab is in tab order)
+- Active tab: `tabIndex={0}`
+- Keyboard navigation within the tablist: `ArrowLeft`/`ArrowRight` move focus + activate tab
+- Tab panel: `role="tabpanel"`, `aria-labelledby="{tab-id}"`, `id="{panel-id}"`
+ Each panel receives `tabIndex={0}` so keyboard users can enter the panel content after
+ the tablist
+
+**Tab IDs:**
+- `id="admin-tab-members"` / `aria-controls="admin-panel-members"`
+- `id="admin-tab-settings"` / `aria-controls="admin-panel-settings"`
+
+**Default active tab on mount:** "Members & Accounts" (Tab 1).
+
+**Phone behavior:** the two-tab strip eliminates the long-scroll on phone. Each tab's
+content replaces the other. The tab labels are short enough that both fit without
+overflow at 390px width (verify via playwright-cli). No horizontal scroll on the
+tab strip.
+
+**No new tokens** — the tab strip uses only existing spacing, color, and typography tokens.
+
+---
+
+## Copywriting Contract
+
+### Workstream D new copy
+
+| Element | Copy |
+|---------|------|
+| Logout button label | "Sign out" |
+| Logout button aria-label | "Sign out" |
+| Toast — create member success | "Member added." |
+| Toast — reset password success | "Password reset." |
+| Admin tab 1 label | "Members & Accounts" |
+| Admin tab 2 label | "Settings" |
+
+### Copywriting rules (inherited from Phase 19)
+
+- Never use "Authelia" in any user-facing copy.
+- Admin copy ("Reset password", "Sign out") is direct — admins are comfortable with the vocabulary.
+- End-user copy is warm and low-friction.
+- "Sign out" (not "Log out" or "Logout") — consistent with friendly household tone.
+- Toast copy is declarative past-tense ("Member added.") not celebratory — keeps the
+ admin UI professional.
+
+### Empty states
+
+No new empty states introduced by Phase 17. The existing AdminPage empty states
+(no members / no calendars synced) remain unchanged.
+
+### Error states
+
+No new error states introduced by Phase 17. Workstream D's logout has no error path
+(if the API call fails, the user is navigated to `/login` regardless —
+`fetchLocalLogout()` is fire-and-best-effort for a cookie clear).
+
+---
+
+## Surface Architecture
+
+### Surface A-1 — Phone layout (App.tsx `contentStyle`, phone branch)
+
+After fix:
+```ts
+const contentStyle: React.CSSProperties = {
+ flex: 1,
+ minWidth: 0,
+ minHeight: 0,
+ display: 'flex',
+ flexDirection: 'column',
+ overflow: 'hidden',
+ position: 'relative',
+ // Phone-only: reserve space for the fixed BottomTabBar
+ ...(phone ? { paddingBottom: 'var(--bottom-chrome-h)' } : {}),
+};
+```
+
+The `overflow: 'hidden'` on the outer contentStyle traps scroll. The inner route content
+(CalendarShell, ListsIndex, etc.) must handle its own scroll; the padding-bottom ensures
+their scrollable area clears the tab bar.
+
+### Surface A-2 — New Event FAB (CalendarShell.tsx)
+
+After fix (phone-only FAB style):
+```ts
+// Phone FAB positioning — clears BottomTabBar + adds breathing room
+position: 'fixed',
+bottom: 'calc(var(--bottom-chrome-h) + var(--space-6))',
+right: 'var(--space-6)',
+// size unchanged
+width: '56px',
+height: '56px',
+```
+
+### Surface B-1 — BrandSlot (BrandSlot.tsx)
+
+After swap:
+```tsx
+
+
+ {/*
+```
+
+`--brand-logo-border-radius` updated in `tokens.css` to suit the logo shape
+(determined at checkpoint; likely `12px` for warm/rounded brief or `50%` if circular).
+
+### Surface C-1 — tokens.css structural change
+
+Before:
+```css
+:root { /* all tokens */ }
+```
+
+After:
+```css
+:root,
+[data-theme="light"] { /* all tokens, values unchanged */ }
+/* [data-theme="dark"] { ... } intentionally absent — Phase 999.20 fills this */
+```
+
+### Surface D-1 — SettingsSheet logout row
+
+After the existing Account section divider (or at the bottom of the sheet):
+```tsx
+{/* Sign out */}
+
+
+```
+
+`handleSignOut` calls `fetchLocalLogout()` then navigates to `/login`.
+
+### Surface D-2 — Admin two-tab strip (AdminPage.tsx)
+
+Rendered above all AdminPage content, inside the content column:
+- `and
tagline unchanged */} +
` containing two `