+```
+
+**`--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 `
+```
+
+**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-VERIFICATION.md b/.planning/phases/17-ui-optimization-polish/17-VERIFICATION.md
new file mode 100644
index 0000000..66560f2
--- /dev/null
+++ b/.planning/phases/17-ui-optimization-polish/17-VERIFICATION.md
@@ -0,0 +1,119 @@
+---
+phase: 17-ui-optimization-polish
+verified: 2026-06-18T00:00:00Z
+status: human_needed
+score: 10/10 decisions delivered in code (1 WARNING-class resize limitation, 4 device-only checks)
+behavior_unverified: 0
+overrides_applied: 0
+human_verification:
+ - test: "On a phone (≤767px, e.g. iPhone 14 / Pixel 7) load /calendar and /lists. Confirm the New Event FAB sits fully above the BottomTabBar and the color-legend chips are not clipped behind the bar."
+ expected: "FAB floats above the tab bar (not on the Admin tab); legend chips fully visible; CI overlap guard (layout.spec.ts) corroborates geometry on iphone/pixel profiles."
+ why_human: "Pixel-accurate fixed-chrome overlap + safe-area-inset rendering on a real notched device cannot be fully judged from CSS source; CI guard runs headless WebKit/Chromium only."
+ - test: "Resize a desktop browser window narrower than 768px (or rotate a tablet/foldable across the 767px breakpoint) with the Settings sheet, a credential sheet, or the admin reset sheet OPEN."
+ expected: "Sheet should switch between centered-modal (desktop) and bottom-sheet (phone) geometry. NOTE: 17-REVIEW WR-01 documents that the `phone` snapshot is computed once per render with no matchMedia listener, so the sheet keeps stale geometry until an unrelated re-render. Confirm severity for this household's actual devices."
+ why_human: "Resize-crossing-breakpoint re-render behavior is a runtime interaction; the static branches are correct at mount but do not re-evaluate. Operator decides if this WARNING blocks (real phones are always phones; impact is tablets/foldables/desktop-resize)."
+ - test: "Install the PWA to a device home screen and inspect the app icon (especially Android adaptive/maskable rendering and iOS apple-touch-icon)."
+ expected: "Maskable icon (icon-maskable-512.png) shows the family-house logo inside the safe zone with no clipping; favicon shows in browser tab; apple-touch-icon shows on iOS home screen."
+ why_human: "Maskable safe-zone correctness and home-screen icon rendering are device/installer-specific (iOS-Safari standalone is device-only per CLAUDE.md); cannot be driven headless."
+ - test: "Sign in (local auth, non-dev-bypass) and open Settings; tap 'Sign out'."
+ expected: "Session is cleared and the app routes to /login; signing back in works. (Endpoint + client wiring verified in code; live round-trip confirms cookie clearing end-to-end.)"
+ why_human: "Full logout round-trip (cookie cleared server-side + redirect) is a runtime/auth flow; code path is verified but live confirmation is prudent."
+---
+
+# Phase 17: UI Optimization & Polish Verification Report
+
+**Phase Goal:** A visual-identity & polish pass for the PWA spanning three workstreams — (A) phone-layout polish (no fixed-chrome overlap), (B) branding assets (real logo + complete icon set), (C) theme-token groundwork — plus (D) UAT-surfaced UI fixes (logout, admin toasts, sheet centering, admin nav rework).
+**Verified:** 2026-06-18
+**Status:** human_needed
+**Re-verification:** No — initial verification
+
+## Goal Achievement
+
+Decisions D-01..D-10 stand in for REQ-IDs (no Success Criteria array in ROADMAP; goal is prose + decisions). All 10 decisions have corresponding, substantive, wired code in the codebase. The status is `human_needed` (not `passed`) because device-only checks (phone overlap on real hardware, PWA icon install, logout round-trip) and one WARNING-class resize limitation (17-REVIEW WR-01) require operator confirmation.
+
+### Observable Truths (by Decision)
+
+| # | Decision / Truth | Status | Evidence |
+| ---- | ---------------- | ------ | -------- |
+| D-01 | Phone FAB no longer overlaps BottomTabBar; legend not occluded | ✓ VERIFIED | FAB `bottom: calc(var(--bottom-chrome-h) + var(--space-6))` (CalendarShell.tsx:470); phone `paddingBottom: var(--bottom-chrome-h)` (App.tsx:164); `--bottom-chrome-h: calc(56px + env(safe-area-inset-bottom,0px))` (tokens.css:69). Matches ROADMAP fix sketch exactly. |
+| D-02 | Permanent overlap regression guard in CI | ✓ VERIFIED | layout.spec.ts:209-231 "New Event FAB does not overlap BottomTabBar" — asserts `fabBox.bottom ≤ navBox.top`, phone-only (iphone/pixel), skipped on desktop. Shared-token approach chosen (the planner's default lean). |
+| D-03 | Real FamilySync logo (warm/rounded/at-home) committed as SVG; operator-approved | ✓ VERIFIED | logo.svg (warm peach gradient bg, rounded family-house mark, 512 viewBox). Accent #e8915a + `--brand-logo-border-radius: 0` documented as operator-approved (tokens.css:41,106). |
+| D-04 | Complete 7-asset icon set; proper separate maskable | ✓ VERIFIED | All 7 files present in public/ (logo.svg, favicon.svg, favicon.ico, icon-192/512, icon-maskable-512, apple-touch-icon) at real sizes (not stubs). Maskable is its own 8627B file, distinct from icon-512 (12056B). Manifest references it with `purpose: 'maskable'` (vite.config.ts:41). |
+| D-05 | Logo wired into BrandSlot, decorative, no LoginPage layout change | ✓ VERIFIED | BrandSlot.tsx swaps placeholder div for ``; `