docs(phase-11): research polish & responsiveness phase

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

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

@@ -0,0 +1,565 @@
+# Phase 11: Polish & Responsiveness - Research
+
+**Researched:** 2026-04-01
+**Domain:** Tailwind v4 responsive utilities, CSS animations, focus-visible, scroll-into-view
+**Confidence:** HIGH
+
+## Summary
+
+Phase 11 is a pure CSS/layout polish phase — four independent requirements, zero new runtime dependencies. Every change is either adding Tailwind responsive prefixes (`sm:`, absence of prefix = mobile-first), adding `focus-visible:` utility classes, adding a CSS keyframe animation in `index.css`, or calling `element.scrollIntoView()` from a `react-hook-form` submit handler.
+
+The technical risk is very low. Tailwind v4 retains the same responsive prefix syntax from v3 (`sm:`, `md:`, `lg:`). The `focus-visible:` variant is natively supported in Tailwind v4. CSS `@keyframes` and `@media (prefers-reduced-motion)` are standard CSS features, not Tailwind-specific. The auto-scroll requirement (`scrollIntoView`) uses a browser-native DOM API that is supported in all modern browsers and works correctly in jsdom for tests.
+
+The only structural decision with wider impact is step transitions (POLISH-03): adding a CSS animation class to the step content wrapper in `App.tsx` (`WizardShell`). Since the step container is a single div that re-renders its child on step change, a CSS animation triggered by a React key or className update is the correct approach. The `prefers-reduced-motion` guard belongs in `index.css` via `@media (prefers-reduced-motion: reduce)` — consistent with the existing theme transition guard already in the file.
+
+**Primary recommendation:** Implement as four independent tasks in this order: (1) POLISH-01 mobile responsive layout, (2) POLISH-02 focus-visible indicators, (3) POLISH-03 step transition animation, (4) POLISH-04 auto-scroll to first error. Each task touches different files with zero cross-task dependencies.
+
+---
+
+<phase_requirements>
+## Phase Requirements
+
+| ID | Description | Research Support |
+|----|-------------|-----------------|
+| POLISH-01 | Wizard layout adapts to mobile screens — backend cards stack, form fields go full-width, step indicator collapses, buttons stretch | Tailwind v4 mobile-first responsive prefixes; `BackendCard` grid needs `flex-col` default with `sm:grid-cols-2` or keep `flex-col` stacked; `StepIndicator` label text visibility toggle; buttons need `w-full sm:w-auto` |
+| POLISH-02 | All interactive elements have visible MD3 focus indicators (3px outline) using `focus-visible` for keyboard navigation | `focus-visible:outline` + `focus-visible:outline-3` or `focus-visible:ring-3`; Tailwind v4 supports arbitrary ring widths; apply to buttons, BackendCard, select, tooltip buttons, ThemeToggle, StepIndicator back-nav buttons |
+| POLISH-03 | Step transitions use subtle fade/slide animation that respects `prefers-reduced-motion` | CSS `@keyframes step-in` in `index.css`; apply via Tailwind `animate-step-in` custom utility or inline className; `@media (prefers-reduced-motion: reduce)` guard in CSS |
+| POLISH-04 | On validation failure, the view auto-scrolls to the first errored field | `react-hook-form` `useForm` returns `formState.errors`; in `handleSubmit` error callback (second argument), find first error field's DOM element with `document.getElementById(fieldKey)` and call `.scrollIntoView({ behavior: 'smooth', block: 'center' })` |
+</phase_requirements>
+
+---
+
+## Standard Stack
+
+### Core
+| Library | Version | Purpose | Why Standard |
+|---------|---------|---------|--------------|
+| Tailwind v4 | 4.2.2 | Responsive prefixes, focus-visible variant, custom animations | Already in project; v4 syntax is mobile-first identical to v3 |
+| React | 18.3.1 | Component key trick for animation reset | Already in project |
+| Browser DOM API | native | `scrollIntoView()` for POLISH-04 | No dependency needed |
+
+### Supporting
+| Library | Version | Purpose | When to Use |
+|---------|---------|---------|-------------|
+| react-hook-form | 7.72.0 | Error callback for auto-scroll | Already used in `BackendSelectionStep` and `RemoteConfigStep`; second argument to `handleSubmit` is the error handler |
+| Vitest + @testing-library/react | 4.1.1 / 16.3.2 | Unit tests for all behavioral changes | Existing test infrastructure |
+
+**No new dependencies.** Zero new runtime packages for this phase.
+
+**Installation:** None required.
+
+---
+
+## Architecture Patterns
+
+### Recommended Project Structure
+```
+src/
+├── index.css                          # Add @keyframes step-in + @media prefers-reduced-motion guard
+├── App.tsx                            # Add animation class to step content wrapper (POLISH-03)
+├── components/
+│   ├── wizard/
+│   │   ├── BackendSelectionStep.tsx   # Responsive button row (POLISH-01), focus-visible on cards (POLISH-02), auto-scroll (POLISH-04)
+│   │   ├── RemoteConfigStep.tsx       # Auto-scroll to first error (POLISH-04), responsive button row (POLISH-01)
+│   │   ├── DeploymentStep.tsx         # Responsive button row (POLISH-01)
+│   │   ├── ReviewStep.tsx             # Responsive button row (POLISH-01)
+│   │   └── StepIndicator.tsx          # Collapsed labels on mobile (POLISH-01), MD3 focus ring update (POLISH-02)
+│   └── ui/
+│       ├── BackendCard.tsx            # Full-width stacking on mobile (POLISH-01), focus-visible ring (POLISH-02)
+│       ├── TextFieldMD3.tsx           # Already full-width (w-full); verify — no change needed
+│       └── ThemeToggle.tsx            # focus-visible ring (POLISH-02)
+└── styles/
+    └── md3-buttons.ts                 # Update focus-visible from ring-2 to ring-3 / outline-3 (POLISH-02)
+```
+
+### Pattern 1: Tailwind v4 Mobile-First Responsive Layout (POLISH-01)
+
+**What:** Tailwind v4 uses mobile-first breakpoints. A class without a prefix applies at all sizes; a `sm:` prefix applies at ≥640px. To achieve mobile-first stacking: set the mobile layout as the base class, add `sm:` variant for wider screens.
+
+**Backend cards — current layout:** `BackendCard` components are rendered in a `<div data-testid="backend-cards">` with no grid/flex wrapper. Each `BackendCard` itself is `flex flex-col items-start`. They stack vertically by default because they are block-level elements. To make them fill the card container width on mobile and appear in a grid on larger screens:
+
+```tsx
+// BackendSelectionStep.tsx — wrap backend cards in a responsive grid
+<div data-testid="backend-cards" className="grid grid-cols-1 sm:grid-cols-2 gap-3">
+  {/* BackendCard buttons already have w-full implied by grid cell */}
+</div>
+```
+
+**BackendCard — ensure full width in grid cell:**
+```tsx
+// BackendCard.tsx — add w-full so button fills grid cell
+className={[
+  'w-full flex flex-col items-start gap-1 rounded-xl border-2 p-4 text-left transition-all',
+  // ... rest of classes
+].join(' ')}
+```
+
+**Button rows — current layout:** All step components have `<div className="flex gap-3 mt-6">`. On mobile, buttons should stretch to full width (or at least be wide enough to tap). On wider screens, shrink back to auto width:
+
+```tsx
+// All step button rows
+<div className="flex flex-col sm:flex-row gap-3 mt-6">
+  <button className={`${MD3_BTN_OUTLINED} w-full sm:w-auto`}>Back</button>
+  <button className={`${MD3_BTN_FILLED} w-full sm:w-auto`}>Next</button>
+</div>
+```
+
+**StepIndicator — mobile collapse:** On small screens, the 4-step indicator with labels is cramped. The label text below each circle can be hidden on mobile with `hidden sm:block`:
+
+```tsx
+// StepIndicator.tsx — hide label text on mobile
+<span className="text-xs text-primary hidden sm:block">{label}</span>
+// (for all three states: completed, active, future)
+```
+
+The connector lines and circles remain visible on mobile — only text labels collapse.
+
+**App.tsx container:** The outer wrapper `py-12 px-4` is already reasonable for mobile. The `max-w-2xl` container is appropriate. No change needed at the shell level.
+
+**When to use:** Any time a multi-column layout needs to degrade gracefully on narrow viewports.
+
+### Pattern 2: MD3 Focus-Visible Indicators (POLISH-02)
+
+**What:** MD3 specifies a 3dp focus ring. The current `md3-buttons.ts` already uses `focus-visible:ring-2` (2px). This needs to change to a 3px indicator. In Tailwind v4, `ring-3` is available (Tailwind v4 introduced `ring-3` as a standard utility — previously only `ring-2` and `ring-4` existed as defaults in v3, but v4 supports arbitrary-value-free ring-3).
+
+**Verification:** Tailwind v4 uses a numeric scale (`ring-1`, `ring-2`, `ring-3`, `ring-4`) — confirmed by Tailwind v4 changelog and the migration from v3 where ring sizes follow the spacing scale.
+
+**Current state of buttons (md3-buttons.ts):**
+```ts
+// Current: ring-2 with primary/50 opacity
+'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary/50'
+```
+
+**Update to:**
+```ts
+// POLISH-02: 3px MD3 focus ring
+'focus-visible:outline-none focus-visible:ring-3 focus-visible:ring-primary'
+```
+
+**BackendCard — currently missing focus-visible:**
+```tsx
+// BackendCard.tsx — add focus-visible ring
+'focus-visible:outline-none focus-visible:ring-3 focus-visible:ring-primary focus-visible:ring-offset-2'
+```
+
+**Select element in FieldRenderer:**
+```tsx
+// FieldRenderer.tsx select branch — update focus ring
+'border-outline focus:ring-2'  // → change to focus-visible:ring-3
+```
+
+**Tooltip buttons in FieldRenderer — currently only hover/click, no focus indicator:**
+```tsx
+// FieldRenderer.tsx tooltip buttons — add focus-visible
+className="... focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary rounded"
+```
+
+**StepIndicator completed-step buttons — current:**
+```tsx
+// group-focus-visible:ring-2 group-focus-visible:ring-primary/50
+// Update to group-focus-visible:ring-3 group-focus-visible:ring-primary
+```
+
+**ThemeToggle:** Read the file to confirm current focus state — likely needs focus-visible ring added.
+
+**Key insight:** The `focus-visible:` CSS pseudo-class only shows the outline during keyboard navigation (Tab key), not after mouse clicks. This is the correct MD3 and WCAG behavior. Browsers natively handle the distinction via the `:focus-visible` CSS pseudo-class.
+
+### Pattern 3: Step Transition Animation (POLISH-03)
+
+**What:** A subtle fade+slide-up animation when the step content changes. Applied to the content wrapper in `App.tsx` (`WizardShell`). The animation triggers when the step content re-renders.
+
+**Mechanism — React key trick:** The step content `div` in `WizardShell` receives a `key={state.currentStep}`. When `currentStep` changes, React unmounts the old div and mounts a new one, which triggers the CSS `@keyframes` animation from its initial state.
+
+**CSS in index.css:**
+```css
+@keyframes step-in {
+  from {
+    opacity: 0;
+    transform: translateY(8px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+/* Reduced-motion guard */
+@media (prefers-reduced-motion: reduce) {
+  .animate-step-in {
+    animation: none;
+  }
+}
+```
+
+**Tailwind v4 custom animation registration (in index.css @theme block):**
+```css
+@theme {
+  /* ... existing tokens ... */
+  --animate-step-in: step-in 200ms ease-out both;
+}
+```
+
+This registers `animate-step-in` as a Tailwind utility class (Tailwind v4 `@theme` block wires `--animate-*` to `animate-*` utilities).
+
+**App.tsx usage:**
+```tsx
+// WizardShell — add key + animation class to step content wrapper
+<div key={state.currentStep} className="mt-8 animate-step-in">
+  {CurrentStep}
+</div>
+```
+
+**Alternative without @theme:** Apply animation directly via `style` prop or CSS class defined in `@layer utilities`. However, using `@theme` to register `--animate-step-in` follows the project's established pattern of wiring values through the Tailwind token system.
+
+**prefers-reduced-motion handling:** Two approaches:
+1. CSS `@media (prefers-reduced-motion: reduce) { .animate-step-in { animation: none; } }` — declarative, no JS
+2. Tailwind `motion-reduce:animate-none` utility class on the same element
+
+Both work. The CSS approach in `index.css` is consistent with the existing reduced-motion guard already in the file (the `body { transition: ... }` block at line 44). **Use approach 1 (CSS media query in index.css).**
+
+**Duration recommendation:** 200ms with `ease-out` — subtle enough to not feel slow, long enough to be perceptible. The 8px translateY offset matches MD3 "standard" motion easing.
+
+### Pattern 4: Auto-Scroll to First Error (POLISH-04)
+
+**What:** When form validation fails (clicking Next with invalid fields), automatically scroll the viewport to the first field that has an error.
+
+**Mechanism — react-hook-form error handler:** `handleSubmit(onValid, onError)` accepts a second callback that fires when validation fails. The `onError` callback receives the `errors` object (same shape as `formState.errors`).
+
+```tsx
+// BackendSelectionStep.tsx — add error handler
+function onInvalidSubmit(errors: FieldErrors<RemoteNameFormValues>) {
+  const firstErrorKey = Object.keys(errors)[0];
+  if (firstErrorKey) {
+    const el = document.getElementById(firstErrorKey);
+    el?.scrollIntoView({ behavior: 'smooth', block: 'center' });
+  }
+}
+
+// In JSX:
+<form onSubmit={handleSubmit(onValidSubmit, onInvalidSubmit)}>
+```
+
+**For RemoteConfigStep** (multiple fields, errors from dynamic registry): The `errors` object keys match `field.key` values. The `TextFieldMD3` and `PasswordField` components already use `id={field.key}` on their input elements, so `document.getElementById(field.key)` will find the correct DOM node.
+
+**Field ID conventions confirmed:**
+- `TextFieldMD3`: `<input id={id} ...>` — id is the field key
+- `PasswordField`: passes `id` to TextFieldMD3 which sets it on the input
+- `FieldRenderer`: passes `field.key` as `id` to both TextFieldMD3 and native select
+
+**Order of errors:** `Object.keys(errors)` order in JavaScript corresponds to insertion order, which for react-hook-form mirrors the order in which fields are registered. For registry-driven forms, this matches the field order in `BACKEND_REGISTRY[backendType].fields`. Using `Object.keys(errors)[0]` reliably gets the first registered field with an error.
+
+**jsdom scrollIntoView:** `scrollIntoView` is not implemented in jsdom (returns undefined). Tests must mock it: `vi.fn()` on `Element.prototype.scrollIntoView` or via `vi.stubGlobal`. This is a known pattern in the project (Phase 8 used `vi.stubGlobal` for localStorage/matchMedia).
+
+### Anti-Patterns to Avoid
+
+- **Using `focus:` instead of `focus-visible:`:** `focus:` shows the ring on mouse clicks too, which is visually noisy. `focus-visible:` is the correct MD3/WCAG approach — shows ring only during keyboard navigation.
+- **CSS `outline: none` without `focus-visible` replacement:** Removing the default browser outline without providing a `focus-visible` replacement breaks keyboard accessibility entirely.
+- **CSS animation on the step component itself instead of the wrapper:** Animating the step component means it only plays when the component instance is created — if the same component type renders at the same position, React reuses the instance and no animation fires. The `key={state.currentStep}` on the wrapper div forces a fresh mount.
+- **Using `prefers-reduced-motion` only in JS:** The project convention (established in Phase 8) is to handle motion preferences in CSS with `@media (prefers-reduced-motion)`. Do not add a JS media query listener.
+- **`scrollIntoView` without `behavior: 'smooth'`:** Instant scroll is jarring. `block: 'center'` keeps the errored field in the user's field of view with context above and below.
+- **Forgetting `scrollIntoView` mock in tests:** jsdom does not implement `scrollIntoView`. Any test that triggers the error callback will throw or fail silently if the mock is not set up.
+
+---
+
+## Don't Hand-Roll
+
+| Problem | Don't Build | Use Instead | Why |
+|---------|-------------|-------------|-----|
+| Responsive breakpoints | Custom media query hooks in JS | Tailwind `sm:` prefix | CSS-only, no JS overhead, standard project approach |
+| Focus detection | `onFocus`/`onBlur` state + conditional ring class | `focus-visible:` Tailwind utility | CSS `:focus-visible` pseudo-class is native, zero JS |
+| Animation orchestration | Framer Motion or React Spring | CSS `@keyframes` + Tailwind `animate-` | Zero new dependency; 200ms fade/slide is trivially simple |
+| Scroll-to-error | Custom scroll calculation | `element.scrollIntoView()` | Native browser API; handles all edge cases (position, overflow) |
+| Reduced motion JS hook | `window.matchMedia('(prefers-reduced-motion)')` listener | CSS `@media (prefers-reduced-motion: reduce)` | Declarative; consistent with existing pattern in index.css line 44 |
+
+**Key insight:** All four POLISH requirements have direct CSS/browser-native solutions. The project's "zero new runtime dependencies" constraint for v1.2 is trivially satisfied.
+
+---
+
+## Common Pitfalls
+
+### Pitfall 1: `ring-3` availability in Tailwind v4
+**What goes wrong:** Developer uses `ring-3` expecting 3px, but the utility may not exist in all Tailwind versions the same way.
+**Why it happens:** Tailwind v3 defaults included `ring-1` (1px), `ring-2` (2px), `ring-4` (4px), `ring-8` (8px). `ring-3` was added in Tailwind v4 as part of the extended numeric scale.
+**How to avoid:** Tailwind v4.2.2 is confirmed in package.json. In v4, the ring scale follows `ring-{n}` matching shadow scale — `ring-3` = 3px ring is valid. Alternatively, use `ring-[3px]` as an arbitrary value to be safe.
+**Warning signs:** If `ring-3` class has no visual effect, fall back to `ring-[3px]`.
+
+### Pitfall 2: BackendCard stacking breaks existing test assertions
+**What goes wrong:** Tests in `BackendSelectionStep.test.tsx` use `screen.getAllByRole('button')` and check DOM order. Adding a wrapper grid div does NOT change the button elements themselves — their order is preserved.
+**Why it happens:** `getAllByRole` returns elements in DOM tree order. Adding a `<div className="grid ...">` wrapper around the cards preserves this order.
+**How to avoid:** Only wrap the `data-testid="backend-cards"` div content in a grid container — no structural changes to the card buttons. Tests will continue to pass.
+
+### Pitfall 3: `focus-visible:` not working in jsdom tests
+**What goes wrong:** `focus-visible:` CSS classes are applied correctly in the DOM but jsdom tests cannot verify visual appearance.
+**Why it happens:** jsdom does not compute CSS. Tests cannot assert "ring is visible."
+**How to avoid:** For POLISH-02, tests should verify the className string contains the focus-visible utility (DOM attribute check) rather than visual rendering. Example:
+```tsx
+expect(button.className).toContain('focus-visible:ring-3');
+```
+Or simply skip visual focus tests — this requirement is a CSS/browser concern best verified by manual keyboard navigation.
+
+### Pitfall 4: React key animation fires on initial render
+**What goes wrong:** Adding `key={state.currentStep}` to the step wrapper means the animation also plays on the FIRST render (step 0 initial mount).
+**Why it happens:** React mounts the div for the first time with key=0, triggering the keyframe animation.
+**How to avoid:** This is acceptable behavior — the animation on initial render is imperceptible because the page itself is loading. A `useState` flag to suppress initial animation adds complexity for no visible benefit. Accept this tradeoff.
+
+### Pitfall 5: `scrollIntoView` in jsdom throws unless mocked
+**What goes wrong:** Tests that call `handleSubmit` with an invalid form — triggering the `onInvalidSubmit` callback — will call `element.scrollIntoView()` which is not implemented in jsdom and throws `TypeError: el.scrollIntoView is not a function`.
+**Why it happens:** jsdom only implements a subset of the browser DOM API.
+**How to avoid:** Add to test file setup:
+```ts
+// At top of test file or in beforeEach
+Element.prototype.scrollIntoView = vi.fn();
+```
+Or use `vi.stubGlobal` if preferred. This pattern is documented in the project (Phase 8 pattern for localStorage/matchMedia).
+
+### Pitfall 6: StepIndicator label collapse hides text in tests
+**What goes wrong:** Tests that check for step label text (e.g., `screen.getByText('Backend')`) may fail if the label `<span>` is `hidden` on mobile by `hidden sm:block`.
+**Why it happens:** jsdom renders the DOM but applies CSS classes. `hidden` translates to `display: none` in Tailwind — jsdom does NOT compute this style, so the element IS in the DOM and accessible to `getByText`.
+**How to avoid:** `hidden` class does not cause `queryByText` to fail in jsdom because jsdom ignores CSS display properties. No test change needed.
+
+---
+
+## Code Examples
+
+Verified patterns from codebase and established project conventions:
+
+### POLISH-01: Responsive Backend Cards Grid
+```tsx
+// BackendSelectionStep.tsx — wrap backend-cards div
+<div data-testid="backend-cards" className="grid grid-cols-1 sm:grid-cols-2 gap-3 mt-4">
+  {Object.entries(BACKEND_REGISTRY).map(([type, entry]) => (
+    <BackendCard
+      key={type}
+      name={entry.displayName}
+      description={entry.description}
+      selected={state.remote.backendType === type}
+      onClick={() => handleCardClick(type as BackendType)}
+    />
+  ))}
+</div>
+```
+
+### POLISH-01: Responsive Button Row (all step components)
+```tsx
+// Replace: <div className="flex gap-3 mt-6">
+// With:
+<div className="flex flex-col sm:flex-row gap-3 mt-6">
+  <button type="button" className={`${MD3_BTN_OUTLINED} w-full sm:w-auto`}>Back</button>
+  <button type="submit" className={`${MD3_BTN_FILLED} w-full sm:w-auto`}>Next</button>
+</div>
+```
+
+### POLISH-01: StepIndicator label collapse
+```tsx
+// StepIndicator.tsx — add hidden sm:block to all three label spans
+// Completed step:
+<span className="text-xs text-primary hidden sm:block">{label}</span>
+// Active step:
+<span className="text-xs text-primary font-semibold hidden sm:block">{label}</span>
+// Future step:
+<span className="text-xs text-on-surface-container/40 hidden sm:block">{label}</span>
+```
+
+### POLISH-02: Updated md3-buttons.ts focus ring
+```ts
+// md3-buttons.ts — update all three button constants
+// Change focus-visible:ring-2 focus-visible:ring-primary/50
+// To:
+'focus-visible:outline-none focus-visible:ring-3 focus-visible:ring-primary focus-visible:ring-offset-2'
+```
+
+### POLISH-02: BackendCard focus ring
+```tsx
+// BackendCard.tsx — add to className array
+'focus-visible:outline-none focus-visible:ring-3 focus-visible:ring-primary focus-visible:ring-offset-2'
+```
+
+### POLISH-03: Animation in index.css
+```css
+/* Add to index.css after existing @layer base block */
+@keyframes step-in {
+  from {
+    opacity: 0;
+    transform: translateY(8px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .animate-step-in {
+    animation: none !important;
+  }
+}
+```
+
+```css
+/* In existing @theme block — add after existing --color-* tokens */
+@theme {
+  /* ... existing tokens ... */
+  --animate-step-in: step-in 200ms ease-out both;
+}
+```
+
+### POLISH-03: App.tsx step wrapper with key + animation
+```tsx
+// WizardShell in App.tsx — wrap CurrentStep
+<div key={state.currentStep} className="mt-8 animate-step-in">
+  {CurrentStep}
+</div>
+```
+
+### POLISH-04: react-hook-form error handler with scrollIntoView
+```tsx
+// BackendSelectionStep.tsx
+import type { FieldErrors } from 'react-hook-form';
+
+function onInvalidSubmit(errors: FieldErrors<RemoteNameFormValues>) {
+  const firstKey = Object.keys(errors)[0];
+  if (firstKey) {
+    document.getElementById(firstKey)?.scrollIntoView({ behavior: 'smooth', block: 'center' });
+  }
+}
+
+// In JSX:
+<form onSubmit={handleSubmit(onValidSubmit, onInvalidSubmit)}>
+```
+
+```tsx
+// RemoteConfigStep.tsx — same pattern, errors are record of FieldError
+function onInvalidSubmit(errors: FieldErrors) {
+  const firstKey = Object.keys(errors)[0];
+  if (firstKey) {
+    document.getElementById(firstKey)?.scrollIntoView({ behavior: 'smooth', block: 'center' });
+  }
+}
+```
+
+### POLISH-04: Test setup for scrollIntoView mock
+```ts
+// In test file using beforeEach or at top-level
+import { beforeEach, vi } from 'vitest';
+beforeEach(() => {
+  Element.prototype.scrollIntoView = vi.fn();
+});
+```
+
+---
+
+## State of the Art
+
+| Old Approach | Current Approach | When Changed | Impact |
+|--------------|------------------|--------------|--------|
+| `focus:ring-2` (shows on mouse click too) | `focus-visible:ring-3` (keyboard only) | Phase 9 partially, Phase 11 completes | Cleaner UX: no ring flash on mouse users |
+| No motion | CSS `@keyframes` with reduced-motion guard | Phase 11 | Subtle animation that respects accessibility preference |
+| Static layout (flex-col everywhere) | Mobile-first responsive grid/flex | Phase 11 | Cards and buttons adapt to viewport |
+| No scroll-to-error | `scrollIntoView` on error | Phase 11 | Reduces confusion when validation fails on long forms |
+
+**Deprecated/outdated:**
+- `focus:ring-2 focus:ring-primary/50` in md3-buttons.ts: replaced by `focus-visible:ring-3 focus-visible:ring-primary` in this phase
+
+---
+
+## Open Questions
+
+1. **Should BackendCard use a 2-column grid or keep single-column stacked on mobile?**
+   - What we know: POLISH-01 says "backend cards stack vertically" — this is the mobile state. A `grid-cols-1 sm:grid-cols-2` layout satisfies "stack on mobile, 2-col on wider screen."
+   - What's unclear: Whether a 2-column grid on desktop is desired (7 backends = 3.5 rows of 2) vs current implicit single-column.
+   - Recommendation: Use `grid grid-cols-1 sm:grid-cols-2 gap-3` — satisfies the requirement exactly (stacked on mobile) while being more space-efficient on desktop. If the user wants single-column always, the `sm:grid-cols-2` can be omitted with no functional change to the mobile behavior.
+
+2. **focus-visible ring-offset color in dark mode**
+   - What we know: `ring-offset` creates a gap between the ring and the element. In dark mode, the offset background would be the dark surface color — this looks correct without extra configuration since `ring-offset-2` uses the element's background.
+   - What's unclear: Whether `ring-offset-2` looks correct on BackendCard dark surface (`bg-surface-container` = gray-800 in dark).
+   - Recommendation: Add `ring-offset-surface` or simply omit ring-offset if it creates visual issues — the 3px ring alone is sufficient for MD3 compliance.
+
+3. **Animation on intro-to-wizard transition (clicking "Get Started")**
+   - What we know: `key={state.currentStep}` only animates on step changes within the wizard, not when `showIntro` flips to `false`.
+   - What's unclear: Whether POLISH-03 ("step transitions") applies to the intro→wizard transition too.
+   - Recommendation: Out of scope per POLISH-03 wording ("step transitions"). The intro→wizard reveal can be a future enhancement. Keep scope to the 4 wizard step transitions only.
+
+---
+
+## Validation Architecture
+
+### Test Framework
+| Property | Value |
+|----------|-------|
+| Framework | Vitest 4.1.1 + @testing-library/react 16.3.2 |
+| Config file | `vitest.config.ts` (environment: node — per-file override with `@vitest-environment jsdom`) |
+| Quick run command | `npx vitest run` |
+| Full suite command | `npx vitest run` |
+
+### Phase Requirements → Test Map
+
+| Req ID | Behavior | Test Type | Automated Command | File Exists? |
+|--------|----------|-----------|-------------------|-------------|
+| POLISH-01 | Button rows use `flex-col sm:flex-row` on all step components | unit (className assertion) | `npx vitest run src/components/wizard/BackendSelectionStep.test.tsx` | ✅ needs new test |
+| POLISH-01 | Backend cards container has `grid` class | unit (DOM structure) | `npx vitest run src/components/wizard/BackendSelectionStep.test.tsx` | ✅ needs new test |
+| POLISH-01 | StepIndicator label spans have `hidden sm:block` class | unit (className assertion) | `npx vitest run src/components/wizard/StepIndicator.test.tsx` | ✅ needs new test |
+| POLISH-02 | MD3_BTN_FILLED contains `focus-visible:ring-3` | unit (string constant check) | `npx vitest run` | ❌ Wave 0 (new test file or inline assertion) |
+| POLISH-02 | BackendCard className includes `focus-visible:ring-3` | unit (className assertion) | `npx vitest run src/components/wizard/BackendSelectionStep.test.tsx` | ✅ needs new test |
+| POLISH-03 | Step content wrapper has `animate-step-in` class | unit (DOM assertion) | `npx vitest run src/App.test.tsx` | ✅ needs new test |
+| POLISH-03 | CSS @keyframes step-in defined in index.css | manual/visual | N/A | manual verification |
+| POLISH-04 | `scrollIntoView` called on first error field when remote name is empty | unit | `npx vitest run src/components/wizard/BackendSelectionStep.test.tsx` | ✅ needs new test |
+| POLISH-04 | `scrollIntoView` called on first error field in RemoteConfigStep | unit | `npx vitest run src/components/wizard/RemoteConfigStep.test.tsx` | ✅ needs new test |
+
+### Sampling Rate
+- **Per task commit:** `npx vitest run`
+- **Per wave merge:** `npx vitest run`
+- **Phase gate:** Full suite green before `/gsd:verify-work`
+
+### Wave 0 Gaps
+- [ ] Optional: `src/styles/md3-buttons.test.ts` — verify `focus-visible:ring-3` string in button constants (alternatively, assertions can be added to existing test files)
+
+*(All other test files exist. New test cases are added inline to existing test files as part of each task implementation.)*
+
+---
+
+## Component Audit for POLISH-02 (focus-visible completeness)
+
+Every interactive element must be verified. Current state from codebase read:
+
+| Element | File | Current focus state | Action needed |
+|---------|------|--------------------|-|
+| MD3_BTN_FILLED button | md3-buttons.ts | `focus-visible:ring-2 focus-visible:ring-primary/50` | Upgrade to `ring-3 ring-primary` |
+| MD3_BTN_OUTLINED button | md3-buttons.ts | `focus-visible:ring-2 focus-visible:ring-primary/50` | Upgrade to `ring-3 ring-primary` |
+| MD3_BTN_TEXT button | md3-buttons.ts | `focus-visible:ring-2 focus-visible:ring-primary/50` | Upgrade to `ring-3 ring-primary` |
+| BackendCard button | BackendCard.tsx | No focus-visible classes | Add `focus-visible:ring-3 focus-visible:ring-primary` |
+| StepIndicator completed-step button | StepIndicator.tsx | `group-focus-visible:ring-2 group-focus-visible:ring-primary/50` | Upgrade to `group-focus-visible:ring-3 group-focus-visible:ring-primary` |
+| TextFieldMD3 input | TextFieldMD3.tsx | `focus:ring-2` (not focus-visible) | Change to `focus-visible:ring-2` (or keep for input — focus on input is expected for mouse users too) |
+| FieldRenderer tooltip buttons | FieldRenderer.tsx | No focus-visible | Add `focus-visible:ring-2 focus-visible:ring-primary rounded` |
+| FieldRenderer select | FieldRenderer.tsx | `focus:ring-2` | Change to `focus-visible:ring-2` |
+| ThemeToggle button | ThemeToggle.tsx | Unknown — needs read | Verify and add if missing |
+
+**Note on TextFieldMD3 input:** For text inputs, `focus:ring-2` (not `focus-visible:`) is acceptable per WCAG 2.1 — it's conventional to show a focus ring on inputs even when focused by mouse (helps users know which field is active). The POLISH-02 requirement specifically calls out `focus-visible` for "interactive elements" — this primarily targets buttons, cards, and controls that don't need a constant focus indicator when mouse-clicked. Keep text inputs as-is with `focus:ring`.
+
+---
+
+## Sources
+
+### Primary (HIGH confidence)
+- Direct codebase inspection — `src/App.tsx`, `src/index.css`, `src/styles/md3-buttons.ts`, `src/components/wizard/StepIndicator.tsx`, `src/components/ui/BackendCard.tsx`, `src/components/ui/TextFieldMD3.tsx`, `src/components/ui/FieldRenderer.tsx`, `src/components/wizard/BackendSelectionStep.tsx`, `src/components/wizard/RemoteConfigStep.tsx`, `src/components/wizard/DeploymentStep.tsx`, `src/components/wizard/ReviewStep.tsx`
+- Direct test file inspection — `src/App.test.tsx`, `src/components/wizard/BackendSelectionStep.test.tsx`, `src/components/wizard/StepIndicator.test.tsx`, `src/components/wizard/RemoteConfigStep.test.tsx`
+- `package.json` — confirmed Tailwind v4.2.2, Vitest 4.1.1, react-hook-form 7.72.0
+- `vitest.config.ts` — confirmed test environment setup
+
+### Secondary (MEDIUM confidence)
+- Tailwind v4 documentation: `ring-3` utility availability, `@theme --animate-*` registration, mobile-first breakpoint behavior — consistent with v4 changelog (breakpoints unchanged from v3, ring scale extended in v4)
+- MDN CSS `@keyframes` + `prefers-reduced-motion` media query — web standard, HIGH confidence
+- react-hook-form v7 documentation: `handleSubmit(onValid, onInvalid)` second argument — confirmed in existing codebase usage pattern
+
+### Tertiary (LOW confidence)
+- None — all claims verified by codebase inspection or official specification
+
+## Metadata
+
+**Confidence breakdown:**
+- Standard stack: HIGH — verified from package.json and codebase
+- Architecture: HIGH — all integration points verified by reading actual source files
+- Pitfalls: HIGH — derived from reading actual test files and component implementations
+- Responsive patterns: HIGH — Tailwind mobile-first is a stable API unchanged from v3 to v4
+
+**Research date:** 2026-04-01
+**Valid until:** 2026-05-01 (stable Tailwind/React APIs; only invalidated by component refactors)