docs(phase-11): complete phase execution and verification

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

.planning/ROADMAP.md

@@ -117,4 +117,4 @@ Plans:
 | 8. Theme Foundation | v1.2 | 2/2 | Complete | 2026-04-01 |
 | 9. MD3 Components | v1.2 | 5/5 | Complete | 2026-04-01 |
 | 10. Content & Clarity | v1.2 | 3/3 | Complete | 2026-04-01 |
-| 11. Polish & Responsiveness | 2/2 | Complete   | 2026-04-01 | - |
+| 11. Polish & Responsiveness | 2/2 | Complete    | 2026-04-01 | - |

.planning/STATE.md

@@ -4,7 +4,7 @@ milestone: v1.2
 milestone_name: UI Polish & Clarity
 status: completed
 stopped_at: Completed 11-02-PLAN.md
-last_updated: "2026-04-01T11:32:08.129Z"
+last_updated: "2026-04-01T11:35:59.058Z"
 last_activity: 2026-04-01 — Phase 11 plan 02 complete (POLISH-03, POLISH-04 satisfied)
 progress:
   total_phases: 4

.planning/phases/11-polish-responsiveness/11-VERIFICATION.md

@@ -0,0 +1,137 @@
+---
+phase: 11-polish-responsiveness
+verified: 2026-04-01T13:35:00Z
+status: passed
+score: 10/10 must-haves verified
+re_verification: false
+human_verification:
+  - test: "Resize browser to <640px viewport and navigate through all wizard steps"
+    expected: "Backend cards stack in a single column, navigation buttons fill full width and stack vertically, StepIndicator shows only circles/connectors (no labels)"
+    why_human: "CSS responsive breakpoints cannot be tested by grep; requires actual viewport resize"
+  - test: "Navigate wizard with keyboard only (Tab + Enter/Space)"
+    expected: "Every button, card, and theme toggle button shows a visible 3px indigo focus ring when focused via keyboard; no ring appears when clicking with mouse"
+    why_human: "focus-visible CSS behavior requires actual browser rendering to verify visually"
+  - test: "Click through wizard steps (step 1 to step 2, etc.)"
+    expected: "Each new step content fades in and slides up by ~8px over 200ms"
+    why_human: "CSS animation playback requires browser rendering"
+  - test: "Enable prefers-reduced-motion (OS accessibility setting or DevTools) and navigate steps"
+    expected: "Step transitions show no animation — content appears instantly"
+    why_human: "prefers-reduced-motion media query behavior requires OS/browser setting and visual inspection"
+  - test: "On BackendSelectionStep, click Next without filling in the remote name"
+    expected: "Page scrolls smoothly to center the remote name input in the viewport"
+    why_human: "scrollIntoView behavior in real browser differs from jsdom mock; visual scroll feedback requires browser"
+  - test: "On RemoteConfigStep (e.g. S3 backend), click Next without filling required fields"
+    expected: "Page scrolls smoothly to center the first errored field in the viewport"
+    why_human: "Same as above — real scroll behavior needs browser verification"
+---
+
+# Phase 11: Polish & Responsiveness Verification Report
+
+**Phase Goal:** The wizard feels production-ready on any device with smooth interactions and accessible keyboard navigation
+**Verified:** 2026-04-01T13:35:00Z
+**Status:** passed
+**Re-verification:** No — initial verification
+
+## Goal Achievement
+
+### Observable Truths
+
+| #  | Truth                                                                                             | Status     | Evidence                                                                                 |
+|----|---------------------------------------------------------------------------------------------------|------------|------------------------------------------------------------------------------------------|
+| 1  | On mobile viewport (<640px), backend cards stack vertically in a single column                    | VERIFIED   | `BackendSelectionStep.tsx:80` — `grid grid-cols-1 sm:grid-cols-2`                       |
+| 2  | On mobile viewport (<640px), navigation buttons stretch to full width and stack vertically        | VERIFIED   | All 4 step components have `flex flex-col sm:flex-row` wrapper + `w-full sm:w-auto` on buttons |
+| 3  | On mobile viewport (<640px), StepIndicator hides label text but keeps circles and connectors     | VERIFIED   | `StepIndicator.tsx:45,52,59` — all 3 label spans have `hidden sm:block`                 |
+| 4  | On desktop viewport (>=640px), backend cards display in a 2-column grid                           | VERIFIED   | `BackendSelectionStep.tsx:80` — `sm:grid-cols-2` activates at 640px+                    |
+| 5  | Every button and interactive card shows a 3px MD3 focus ring when keyboard-navigated             | VERIFIED   | `md3-buttons.ts:14,20,26` — all constants have `focus-visible:ring-3 focus-visible:ring-primary`; `BackendCard.tsx:17`; `ThemeToggle.tsx:61,62`; `StepIndicator.tsx:42` |
+| 6  | Focus ring does not appear on mouse click (uses focus-visible, not focus)                        | VERIFIED   | All interactive elements consistently use `focus-visible:` prefix, not bare `focus:`    |
+| 7  | Changing wizard steps plays a subtle fade/slide-up animation on the new step content             | VERIFIED   | `App.tsx:65` — `key={state.currentStep} className="mt-8 animate-step-in"` forces remount; `index.css:72-81` — `@keyframes step-in` with `opacity 0→1, translateY(8px)→0` |
+| 8  | Users with prefers-reduced-motion enabled see no animation on step change                        | VERIFIED   | `index.css:83-87` — `@media (prefers-reduced-motion: reduce) { .animate-step-in { animation: none !important; } }` |
+| 9  | When form validation fails, the view auto-scrolls to the first errored field                     | VERIFIED   | `BackendSelectionStep.tsx:53-56` — `onInvalidSubmit` calls `getElementById('remote-name')?.scrollIntoView`; `RemoteConfigStep.tsx:46-51` — `onInvalidSubmit` resolves first error key and scrolls |
+| 10 | scrollIntoView uses smooth behavior and centers the errored field                                | VERIFIED   | Both components use `{ behavior: 'smooth', block: 'center' }`                           |
+
+**Score:** 10/10 truths verified
+
+### Required Artifacts
+
+| Artifact                                                    | Expected                                          | Status   | Details                                                                                      |
+|-------------------------------------------------------------|---------------------------------------------------|----------|----------------------------------------------------------------------------------------------|
+| `src/styles/md3-buttons.ts`                                 | MD3 button constants with focus-visible:ring-3    | VERIFIED | Lines 14, 20, 26 — all three constants contain `focus-visible:ring-3 focus-visible:ring-primary` |
+| `src/components/ui/BackendCard.tsx`                         | Responsive full-width card with focus-visible ring | VERIFIED | Line 17 — base class includes `w-full` and `focus-visible:ring-3 focus-visible:ring-primary` |
+| `src/components/wizard/StepIndicator.tsx`                   | Collapsed labels on mobile, upgraded focus ring   | VERIFIED | Lines 45, 52, 59 — `hidden sm:block` on all 3 label spans; line 42 — `group-focus-visible:ring-3` |
+| `src/components/wizard/BackendSelectionStep.tsx`            | Responsive card grid and button row               | VERIFIED | Line 80 — `grid grid-cols-1 sm:grid-cols-2`; line 91 — `flex flex-col sm:flex-row`         |
+| `src/index.css`                                             | step-in keyframe animation and reduced-motion guard | VERIFIED | Line 69 — `--animate-step-in` in `@theme`; lines 72-81 — `@keyframes step-in`; lines 83-87 — reduced-motion guard |
+| `src/App.tsx`                                               | Step content wrapper with key and animation class | VERIFIED | Line 65 — `key={state.currentStep} className="mt-8 animate-step-in"`                       |
+| `src/components/wizard/BackendSelectionStep.tsx` (scroll)   | Auto-scroll to first error on validation failure  | VERIFIED | Lines 53-56 — `onInvalidSubmit` wired to `handleSubmit` on both form onSubmit and handleCardClick |
+| `src/components/wizard/RemoteConfigStep.tsx`                | Auto-scroll to first error on validation failure  | VERIFIED | Lines 46-51 — `onInvalidSubmit` wired to form `handleSubmit`                               |
+
+### Key Link Verification
+
+| From                          | To                              | Via                                              | Status   | Details                                                                   |
+|-------------------------------|---------------------------------|--------------------------------------------------|----------|---------------------------------------------------------------------------|
+| `src/styles/md3-buttons.ts`   | All step components             | `MD3_BTN_FILLED` / `MD3_BTN_OUTLINED` constants  | WIRED    | Imported and used in BackendSelectionStep, RemoteConfigStep, DeploymentStep, ReviewStep |
+| `src/components/ui/BackendCard.tsx` | `BackendSelectionStep.tsx`  | Component usage                                  | WIRED    | Imported line 8 and rendered in grid at line 82                           |
+| `src/index.css`               | `src/App.tsx`                   | `animate-step-in` Tailwind utility               | WIRED    | `--animate-step-in` registered in `@theme`; `animate-step-in` applied in App.tsx line 65 |
+| `BackendSelectionStep.tsx`    | DOM element `#remote-name`      | `document.getElementById('remote-name')?.scrollIntoView` | WIRED | `onInvalidSubmit` wired as second arg to `handleSubmit` at lines 60, 70  |
+| `RemoteConfigStep.tsx`        | DOM element by first error key  | `document.getElementById(firstKey)?.scrollIntoView` | WIRED  | `onInvalidSubmit` wired as second arg to `handleSubmit` at line 70        |
+
+### Requirements Coverage
+
+| Requirement | Source Plan | Description                                                                                     | Status    | Evidence                                                                                   |
+|-------------|-------------|-------------------------------------------------------------------------------------------------|-----------|--------------------------------------------------------------------------------------------|
+| POLISH-01   | 11-01       | Wizard layout adapts to mobile screens — backend cards stack, form fields go full-width, step indicator collapses, buttons stretch | SATISFIED | `grid grid-cols-1 sm:grid-cols-2` on card container; `flex flex-col sm:flex-row` + `w-full sm:w-auto` on all button rows; `hidden sm:block` on all StepIndicator labels |
+| POLISH-02   | 11-01       | All interactive elements have visible MD3 focus indicators (3px outline) using focus-visible for keyboard navigation | SATISFIED | All three MD3_BTN constants use `focus-visible:ring-3`; BackendCard, ThemeToggle, StepIndicator completed-step circle, and both FieldRenderer tooltip buttons all have `focus-visible` rings |
+| POLISH-03   | 11-02       | Step transitions use subtle fade/slide animation that respects prefers-reduced-motion            | SATISFIED | `@keyframes step-in` with 200ms ease-out in index.css; `key={state.currentStep} animate-step-in` in App.tsx; `@media (prefers-reduced-motion: reduce)` guard |
+| POLISH-04   | 11-02       | On validation failure, the view auto-scrolls to the first errored field                         | SATISFIED | Both BackendSelectionStep and RemoteConfigStep implement `onInvalidSubmit` with `scrollIntoView({ behavior: 'smooth', block: 'center' })`; unit tests verify behavior (204 tests pass) |
+
+No orphaned requirements — all four POLISH-xx IDs declared in REQUIREMENTS.md are claimed by plans 11-01 and 11-02.
+
+### Anti-Patterns Found
+
+| File | Line | Pattern | Severity | Impact |
+|------|------|---------|----------|--------|
+| `src/components/ui/FieldRenderer.tsx` | 71 | `focus:ring-error/50` and `focus:ring-primary/50` on select element — ring color uses bare `focus:` while ring width uses `focus-visible:ring-2` | Info | Inconsistency only — no functional impact. Ring width (ring-2) is gated on focus-visible, so the color class is dormant on mouse click. Visual behavior is correct. |
+
+No blocker or warning anti-patterns found. The single info-level item in FieldRenderer is a harmless inconsistency: the ring size was correctly changed to `focus-visible:ring-2` per the plan, but the color selectors (`focus:ring-error/50`, `focus:ring-primary/50`) retain the bare `focus:` prefix. Because the ring width class controls visibility, the color classes are inert during mouse focus. The plan only required changing the size class, so this is within spec.
+
+### Human Verification Required
+
+#### 1. Mobile layout at <640px viewport
+
+**Test:** Open the wizard in a browser, resize the viewport to 375px wide, and navigate through all four steps.
+**Expected:** Backend cards appear one per row (full width); Back/Next buttons fill the full width and stack vertically (Back on top, Next below); StepIndicator shows only the numbered circles with connector lines — no "Backend", "Remote Config", "Deployment", "Review" labels.
+**Why human:** Tailwind responsive breakpoints (`sm:` prefix = 640px) require actual viewport rendering; grep confirms the classes exist but cannot confirm Tailwind compiles and applies them correctly.
+
+#### 2. Keyboard focus rings (focus-visible behavior)
+
+**Test:** Tab through all wizard interactive elements (theme toggle, step indicator completed circles, backend cards, form buttons). Then click each element with the mouse and inspect.
+**Expected:** Tabbing to any element shows a 3px indigo ring; clicking with the mouse shows no ring.
+**Why human:** `focus-visible` CSS pseudo-class behavior requires a real browser to distinguish pointer vs keyboard input.
+
+#### 3. Step transition animation
+
+**Test:** Start the wizard and click Next through the steps.
+**Expected:** Each new step content performs a visible fade-in combined with a slight upward slide (8px) over approximately 200ms.
+**Why human:** CSS animation playback requires browser rendering; cannot be verified by static analysis.
+
+#### 4. Reduced-motion guard
+
+**Test:** In OS accessibility settings (or Chrome DevTools > Rendering > Emulate CSS media feature: prefers-reduced-motion: reduce), navigate between wizard steps.
+**Expected:** Step content appears instantly with no animation; no fade or slide visible.
+**Why human:** OS-level media feature emulation requires browser/DevTools interaction.
+
+#### 5. Scroll-to-error in real browser
+
+**Test:** In the wizard, leave the remote name field empty and click Next (or any backend card). Then on RemoteConfigStep, leave required fields empty and click Next.
+**Expected:** The page smoothly scrolls to center the first errored field in the viewport.
+**Why human:** jsdom `scrollIntoView` is mocked in unit tests; real scrolling behavior (visual smoothness, centering accuracy) requires a live browser with a scrollable viewport.
+
+### Gaps Summary
+
+No gaps. All 10 observable truths are verified by static code analysis. All 4 POLISH requirements are satisfied with substantive, wired implementations. The full test suite passes (204 tests, 0 failures). The only item of note is a harmless inconsistency in FieldRenderer's select element where ring color classes still use `focus:` while the ring width class correctly uses `focus-visible:` — this has no visual impact on the POLISH-02 goal.
+
+Six items are flagged for human verification because they involve visual rendering, responsive breakpoints, and OS-level accessibility settings that cannot be evaluated by static analysis alone.
+
+---
+
+_Verified: 2026-04-01T13:35:00Z_
+_Verifier: Claude (gsd-verifier)_