From 68fe57f5855a61d96638918f672b47e4bd4b038c Mon Sep 17 00:00:00 2001
From: Kawa <us.fame.sq@gmail.com>
Date: Wed, 1 Apr 2026 09:05:56 +0200
Subject: [PATCH] docs(phase-09): research MD3 components phase

---
 .../phases/09-md3-components/09-RESEARCH.md   | 679 ++++++++++++++++++
 1 file changed, 679 insertions(+)
 create mode 100644 .planning/phases/09-md3-components/09-RESEARCH.md

diff --git a/.planning/phases/09-md3-components/09-RESEARCH.md b/.planning/phases/09-md3-components/09-RESEARCH.md
new file mode 100644
index 0000000..62455c6
--- /dev/null
+++ b/.planning/phases/09-md3-components/09-RESEARCH.md
@@ -0,0 +1,679 @@
+# Phase 9: MD3 Components - Research
+
+**Researched:** 2026-04-01
+**Domain:** React + Tailwind v4 CSS-custom-property-based MD3 component styling
+**Confidence:** HIGH
+
+---
+
+## Summary
+
+Phase 9 delivers five component-level upgrades to a working wizard that already has a complete
+MD3 color token system (Phase 8 complete). The token layer (`--r2b-*` CSS custom properties
+mapped to Tailwind semantic utilities via `@theme`) is the foundation — every new component
+pattern must consume `bg-primary`, `text-on-surface`, `border-outline`, etc., never raw colors.
+
+The work divides into four visual domains: (1) outlined text fields with CSS-only floating
+labels, (2) a three-tier button hierarchy (filled / outlined / text), (3) MD3 elevation on
+BackendCard and OutputBlock, and (4) a rebuilt StepIndicator with numbered circles and a
+connector line. One non-visual task (DEBT-01) fixes an aria-label inconsistency inside
+FieldRenderer's tooltip button.
+
+The project has a hard constraint of **zero new runtime dependencies**. All styling must be
+achieved with Tailwind v4 utility classes and plain CSS transitions — no component library, no
+animation library. The existing 166 tests are GREEN and must stay GREEN throughout. The
+critical test-breaking risk is that 131 test selectors use `getByLabelText` with
+`htmlFor`/`id` relationships; the floating label pattern must preserve those relationships
+exactly.
+
+**Primary recommendation:** Build a new `<TextFieldMD3>` wrapper component, styled button
+variant classes (not a separate component), an elevation mixin via Tailwind `shadow-` tokens,
+and a rebuilt `<StepIndicator>` using Tailwind flex + absolute-positioned connector — all
+consuming the existing semantic token utilities.
+
+---
+
+<phase_requirements>
+## Phase Requirements
+
+| ID | Description | Research Support |
+|----|-------------|-----------------|
+| COMP-01 | All text inputs render as MD3 outlined text fields with floating labels that animate on focus and when the field has content | Floating label via CSS `peer` + `placeholder=" "` trick; `<TextFieldMD3>` wraps `<input>` + `<label>`; replaces current static label pattern in FieldRenderer and PasswordField |
+| COMP-02 | Buttons follow MD3 hierarchy — filled for primary (Next, Download), outlined for secondary (Back, Copy), text for tertiary | Three Tailwind class sets; applied inline to existing button elements across BackendSelectionStep, RemoteConfigStep, DeploymentStep, ReviewStep, OutputBlock |
+| COMP-03 | Backend selection cards and output blocks use MD3 elevation with tonal surface tint, consistent padding, and shape tokens | BackendCard already uses semantic tokens; needs `shadow-` utility + `bg-primary/5` tint on `surface-container`; OutputBlock `<pre>` needs shape token consistency |
+| COMP-04 | Step indicator displays as numbered circles connected by lines, with completed steps showing a checkmark, current step highlighted, and future steps muted | Full StepIndicator rebuild; flex layout with absolute-positioned `<hr>` or `border-t` connector; existing dispatch logic and WIZD-03 tests preserved |
+| DEBT-01 | FieldRenderer uses consistent `aria-label` pattern across text-branch and select-branch (resolving v1.1 cosmetic debt) | Text-branch tooltip button uses `<span className="sr-only">` while select-branch uses `aria-label={...}` directly; fix: add `aria-label` to text-branch button and remove sr-only span |
+</phase_requirements>
+
+---
+
+## Standard Stack
+
+### Core (already installed — zero new dependencies)
+| Library | Version | Purpose | Why Standard |
+|---------|---------|---------|--------------|
+| Tailwind v4 | 4.2.2 | Utility classes for all styling | Project constraint: no MUI/component lib |
+| @tailwindcss/vite | 4.2.2 | Vite integration, `@theme` directive | Enables semantic token utilities |
+| react | 18.3.1 | Component model | App foundation |
+| react-hook-form | 7.72.0 | Form state; `register()` must pass through to inputs | All fields use RHF registration |
+
+### Supporting (dev, already installed)
+| Library | Version | Purpose | When to Use |
+|---------|---------|---------|-------------|
+| vitest | 4.1.1 | Test runner | All component tests |
+| @testing-library/react | 16.3.2 | Render + query | `getByLabelText`, `getByRole`, `userEvent` |
+
+### Alternatives NOT to use
+| Instead of | Could Use | Why Not |
+|------------|-----------|---------|
+| CSS-only floating label | `@material/web` `<md-outlined-text-field>` | Bundle bloat; requires separate package; conflicts with RHF register pattern |
+| Hand-rolled box-shadow elevation | Headless UI / Radix | No need — pure Tailwind shadow utilities sufficient |
+| Custom stepper library | Any npm stepper lib | Zero new deps; simple 4-step indicator is straightforward with Tailwind flex |
+
+**Installation:** None. All dependencies already present.
+
+---
+
+## Architecture Patterns
+
+### Existing Token Map (from `src/index.css`)
+
+Phase 8 established a two-layer pattern. All new components reference these Tailwind utilities:
+
+```
+bg-primary            text-on-primary
+bg-surface            text-on-surface
+bg-surface-container  text-on-surface-container
+bg-surface-variant    text-on-surface-variant
+border-outline
+text-error            bg-error/10
+text-primary          bg-primary/10
+```
+
+These utilities work in both light and dark mode because they resolve through CSS custom
+properties that are overridden by the `.dark` class.
+
+### Recommended Component Additions
+
+```
+src/components/ui/
+├── TextFieldMD3.tsx      # NEW: outlined input with floating label (COMP-01)
+├── BackendCard.tsx       # EDIT: add MD3 elevation shadow (COMP-03)
+├── PasswordField.tsx     # EDIT: replace static label with TextFieldMD3 inner layout (COMP-01)
+├── FieldRenderer.tsx     # EDIT: replace text+select branches with TextFieldMD3; fix aria (DEBT-01)
+src/components/wizard/
+├── StepIndicator.tsx     # FULL REBUILD: numbered circles + connector line (COMP-04)
+├── BackendSelectionStep.tsx  # EDIT: button styling (COMP-02)
+├── RemoteConfigStep.tsx      # EDIT: button styling (COMP-02)
+├── DeploymentStep.tsx        # EDIT: button styling (COMP-02)
+├── ReviewStep.tsx            # EDIT: button styling + OutputBlock (COMP-02, COMP-03)
+├── OutputBlock.tsx           # EDIT: button styling + elevation (COMP-02, COMP-03)
+```
+
+### Pattern 1: Floating Label Outlined Text Field (COMP-01)
+
+**What:** CSS-only floating label using Tailwind `peer` utilities. The input has a space as
+placeholder (`placeholder=" "`), which allows `:placeholder-shown` to detect whether the
+field is empty. The label is absolutely positioned and transitions between center (empty,
+unfocused) and top-left (focused OR has value) states.
+
+**When to use:** All `<input type="text">` and `<input type="password">` fields inside
+FieldRenderer and PasswordField.
+
+**Critical constraint:** The `id` attribute on the input and `htmlFor` on the label MUST be
+preserved unchanged. All existing `getByLabelText` test selectors depend on this pairing.
+
+**Structure:**
+```tsx
+// Source: pattern derived from Flowbite floating label docs + MD3 outlined field spec
+// https://flowbite.com/docs/forms/floating-label/
+// https://material-web.dev/components/text-field/
+
+interface TextFieldMD3Props {
+  id: string;
+  label: string;
+  error?: FieldError;
+  registration: UseFormRegisterReturn;
+  type?: 'text' | 'password';
+  placeholder?: string;  // internal use only — always " " for floating label
+  helpText?: string;
+  required?: boolean;
+  suffix?: React.ReactNode;  // for PasswordField show/hide button
+}
+
+export function TextFieldMD3({ id, label, error, registration, type = 'text', helpText, required, suffix }: TextFieldMD3Props) {
+  return (
+    <div className="flex flex-col gap-1">
+      <div className="relative">
+        <input
+          id={id}
+          type={type}
+          placeholder=" "  // CRITICAL: single space triggers :placeholder-shown detection
+          className={[
+            'peer w-full rounded-md border bg-transparent px-3 pb-2 pt-5 text-sm',
+            'focus:outline-none focus:ring-2',
+            'placeholder-transparent',  // hide the space placeholder visually
+            error
+              ? 'border-error focus:ring-error/50'
+              : 'border-outline focus:border-primary focus:ring-primary/20',
+            suffix ? 'pr-10' : '',
+          ].join(' ')}
+          {...registration}
+        />
+        <label
+          htmlFor={id}
+          className={[
+            'absolute left-3 top-1/2 -translate-y-1/2 text-sm text-on-surface-container/70',
+            'origin-left transition-all duration-200',
+            // When input has content or is focused: float to top
+            'peer-placeholder-shown:top-1/2 peer-placeholder-shown:scale-100',
+            'peer-focus:top-3 peer-focus:scale-75 peer-focus:-translate-y-0 peer-focus:text-primary',
+            // When not placeholder-shown (has value): also float
+            'peer-not-placeholder-shown:top-3 peer-not-placeholder-shown:scale-75 peer-not-placeholder-shown:-translate-y-0',
+            error ? 'peer-focus:text-error' : '',
+          ].join(' ')}
+        >
+          {label}
+          {required && <span className="ml-1 text-error">*</span>}
+        </label>
+        {suffix && (
+          <div className="absolute right-2 top-1/2 -translate-y-1/2">
+            {suffix}
+          </div>
+        )}
+      </div>
+      {helpText && !error && <p className="text-xs text-on-surface-container/70">{helpText}</p>}
+      {error && <p className="text-xs text-error">{error.message}</p>}
+    </div>
+  );
+}
+```
+
+**Implementation note on `peer-not-placeholder-shown`:** Tailwind v4 supports arbitrary
+variants. If `peer-not-placeholder-shown` is not available as a built-in, use
+`peer-[:not(:placeholder-shown)]:top-3` syntax. Verify against Tailwind v4.2.2 docs.
+Alternatively, the `data-has-value` attribute approach (set via RHF `watch` or `onBlur`)
+is a reliable fallback.
+
+**Alternative approach (data attribute):** If peer-variant coverage is incomplete in Tailwind
+v4, use a wrapper component that watches the input value via RHF `watch()` and adds
+`data-has-value` to the container, then target `group-data-[has-value]:` on the label.
+This is MORE JavaScript but less reliance on CSS pseudo-class availability.
+
+### Pattern 2: MD3 Button Hierarchy (COMP-02)
+
+**What:** Three button class sets applied consistently wherever navigation buttons appear.
+No new component — apply className patterns directly.
+
+```tsx
+// Source: MD3 button spec https://m3.material.io/components/all-buttons
+// Primary / Filled: background = primary, text = on-primary
+const btnFilled = 'px-6 py-2.5 rounded-full bg-primary text-on-primary text-sm font-medium ' +
+  'hover:opacity-90 active:opacity-80 disabled:opacity-40 disabled:cursor-not-allowed ' +
+  'focus-visible:ring-2 focus-visible:ring-primary/50 focus-visible:outline-none transition-opacity';
+
+// Secondary / Outlined: transparent background, primary border and text
+const btnOutlined = 'px-6 py-2.5 rounded-full border border-outline text-on-surface text-sm font-medium ' +
+  'hover:bg-primary/8 active:bg-primary/12 disabled:opacity-40 disabled:cursor-not-allowed ' +
+  'focus-visible:ring-2 focus-visible:ring-primary/50 focus-visible:outline-none transition-colors';
+
+// Tertiary / Text: no border, no background
+const btnText = 'px-4 py-2.5 rounded-full text-primary text-sm font-medium ' +
+  'hover:bg-primary/8 active:bg-primary/12 disabled:opacity-40 disabled:cursor-not-allowed ' +
+  'focus-visible:ring-2 focus-visible:ring-primary/50 focus-visible:outline-none transition-colors';
+```
+
+**Corner radius:** MD3 uses `rounded-full` (28dp height / pill shape) for standard buttons.
+Current codebase uses `rounded-md` — this is a deliberate MD3 upgrade.
+
+**Action mapping:**
+| Button | Type | Location |
+|--------|------|----------|
+| Next | Filled | BackendSelectionStep, RemoteConfigStep, DeploymentStep |
+| Download All (ZIP) | Filled | ReviewStep |
+| Back | Outlined | RemoteConfigStep, DeploymentStep, ReviewStep |
+| Copy | Outlined | OutputBlock |
+| Download (per file) | Outlined | OutputBlock |
+| SAS URL / Access Key toggle | — | AzureAuthToggle (segmented control, not a button hierarchy concern) |
+| Password / Private Key toggle | — | SftpAuthToggle (segmented control) |
+
+### Pattern 3: MD3 Elevation + Tonal Surface (COMP-03)
+
+**What:** MD3 elevation level 1 (the lightest surface lift) for cards and code blocks.
+MD3 uses two mechanisms together: a drop shadow AND a tonal overlay (primary color at low
+opacity over the surface).
+
+**MD3 Elevation Level 1 shadow (verified source: studioncreations.com):**
+```css
+box-shadow: 0 1px 4px 0 rgba(0, 0, 0, 0.37);
+```
+Tailwind equivalent: `shadow-md` (`0 4px 6px -1px rgba(0,0,0,0.1)...`) is close but not
+exact. Use `shadow` (standard) or a custom Tailwind shadow token via `@theme` in index.css.
+
+**Tonal surface tint:** Add `bg-primary/5` to card container on top of `bg-surface-container`
+to implement the MD3 tonal tint. In practice, this means the container background class
+becomes a layered effect or the value of `--r2b-surface-container` is adjusted.
+
+**Recommended approach for BackendCard:**
+```tsx
+// Before: border-2 p-4 rounded-lg
+// After: border-2 p-4 rounded-xl shadow + tonal tint
+className={[
+  'flex flex-col items-start gap-1 rounded-xl border-2 p-4 text-left transition-all',
+  'shadow hover:shadow-md',  // elevation lift on hover
+  selected
+    ? 'border-primary bg-primary/10 shadow-md'
+    : 'border-outline bg-surface-container hover:border-primary hover:bg-primary/5',
+].join(' ')}
+```
+
+**Shape token:** MD3 card shape is "medium" (12dp corner radius). Use `rounded-xl` (12px).
+Current `rounded-lg` is 8px — upgrade to `rounded-xl`.
+
+**OutputBlock elevation:**
+```tsx
+// Pre block (code display) — add subtle elevation to differentiate from page surface
+className="bg-surface-variant text-on-surface-variant rounded-xl p-4 text-xs overflow-x-auto whitespace-pre-wrap shadow-sm"
+```
+
+### Pattern 4: Rebuilt StepIndicator (COMP-04)
+
+**What:** Replace the current text-based breadcrumb (spans with `›` separator) with a visual
+step indicator: horizontal row of numbered circles connected by a line, showing state via
+icon/color.
+
+**Current implementation issues:**
+- Uses inline `style={{}}` instead of Tailwind classes (style violations)
+- No visual connector line between steps
+- No checkmark on completed steps
+- `#999` hardcoded color (not token)
+
+**Structure:**
+```tsx
+// Horizontal step indicator with connector lines between circles
+return (
+  <nav aria-label="Wizard steps">
+    <ol className="flex items-center w-full">
+      {STEP_LABELS.map((label, i) => {
+        const isCompleted = i < currentStep;
+        const isActive = i === currentStep;
+        const isFuture = i > currentStep;
+
+        return (
+          <li key={i} className={['flex items-center', i < STEP_LABELS.length - 1 ? 'flex-1' : ''].join(' ')}>
+            {/* Step circle */}
+            <div className="flex flex-col items-center gap-1 shrink-0">
+              {isCompleted ? (
+                <button
+                  type="button"
+                  onClick={() => handleStepClick(i)}
+                  className="w-8 h-8 rounded-full bg-primary text-on-primary flex items-center justify-center text-sm font-medium focus-visible:ring-2 focus-visible:ring-primary/50"
+                  aria-label={`Go to step ${i + 1}: ${label}`}
+                >
+                  ✓
+                </button>
+              ) : isActive ? (
+                <span className="w-8 h-8 rounded-full border-2 border-primary bg-primary/10 text-primary flex items-center justify-center text-sm font-bold">
+                  {i + 1}
+                </span>
+              ) : (
+                <span className="w-8 h-8 rounded-full border-2 border-outline text-on-surface-container/40 flex items-center justify-center text-sm">
+                  {i + 1}
+                </span>
+              )}
+              <span className={[
+                'text-xs mt-1 text-center',
+                isCompleted ? 'text-primary' : isActive ? 'text-on-surface font-medium' : 'text-on-surface-container/40',
+              ].join(' ')}>
+                {label}
+              </span>
+            </div>
+            {/* Connector line between steps */}
+            {i < STEP_LABELS.length - 1 && (
+              <div className={[
+                'flex-1 h-0.5 mx-2 self-start mt-4',
+                isCompleted ? 'bg-primary' : 'bg-outline',
+              ].join(' ')} aria-hidden="true" />
+            )}
+          </li>
+        );
+      })}
+    </ol>
+  </nav>
+);
+```
+
+**CRITICAL:** The existing WIZD-03 tests query by button presence and click behavior. The
+rebuilt component must still render completed steps as `<button>` elements and dispatch
+`SET_STEP` and `SET_REMOTE_PARAMS({})` on click. The test suite does NOT test visual
+appearance — only behavior — so the internal restructure is safe.
+
+**Test impact:** `screen.getAllByRole('button')` queries will still find completed step
+buttons. Text queries like `screen.findByText(/Deployment/)` will still find the step label.
+No test changes expected.
+
+### Pattern 5: DEBT-01 — FieldRenderer aria-label Fix
+
+**Current state (inconsistency):**
+- Select branch tooltip button: `aria-label={\`More info about ${field.label}\`}` — CORRECT
+- Text branch tooltip button: uses `<span className="sr-only">More info about {field.label}</span>` + `<span aria-hidden="true">ⓘ</span>` — INCONSISTENT
+
+**Fix:** Update the text-branch tooltip button to match the select-branch pattern:
+```tsx
+// Before (text branch):
+<button type="button" onClick={...} className="...">
+  <span className="sr-only">More info about {field.label}</span>
+  <span aria-hidden="true">ⓘ</span>
+</button>
+
+// After (matching select branch):
+<button
+  type="button"
+  onClick={...}
+  aria-label={`More info about ${field.label}`}
+  className="..."
+>
+  ⓘ
+</button>
+```
+
+**Test impact:** The DEBT-01 fix changes tooltip button structure. Any test using
+`screen.getByRole('button', { name: /more info about.../i })` will now correctly find both
+branches. The RemoteConfigStep.test.tsx UX-01 tests query by `screen.getByRole('button')`
+patterns — verify these still pass after fix.
+
+### Anti-Patterns to Avoid
+
+- **Hardcoding colors:** Never use `text-gray-700` or `bg-indigo-500`. Always use semantic
+  tokens (`text-on-surface`, `bg-primary`).
+- **Inline style prop:** StepIndicator currently uses `style={{ fontWeight: 'bold' }}` and
+  `style={{ color: '#999' }}`. Phase 9 removes ALL inline style props.
+- **Changing DOM structure that tests depend on:** `getByLabelText` links `<label htmlFor>`
+  to `<input id>`. Any floating label pattern MUST keep both attributes intact.
+- **Multiple `placeholder` values:** The floating label trick requires `placeholder=" "`
+  (space). If the field also needs a real placeholder (e.g., "https://..."), the two purposes
+  conflict. Resolution: use `placeholder=" "` for the CSS trick and show placeholder-like
+  text as help text below the field instead.
+- **Changing button DOM content that tests depend on:** RemoteConfigStep tests use
+  `getByRole('button', { name: /next/i })` — button text must remain "Next" (case-insensitive
+  match). Verify all button label changes don't break test selectors.
+
+---
+
+## Don't Hand-Roll
+
+| Problem | Don't Build | Use Instead | Why |
+|---------|-------------|-------------|-----|
+| Floating label that tracks input value | useState + JS event listener | CSS `peer-placeholder-shown` + `placeholder=" "` | Pure CSS, zero JS, better performance |
+| Theme-aware shadow values | Switch statement in JS | Tailwind `shadow` utilities — already correct in dark mode | Tailwind shadow colors respect `dark:` variant |
+| Accessible step navigation | Custom focus management | `<button>` elements with `aria-label` | Browser handles tab order and keyboard naturally |
+| Component library for inputs | Copy MUI TextField source | `TextFieldMD3` custom component with 30 lines | Zero bundle cost, full token control |
+
+---
+
+## Common Pitfalls
+
+### Pitfall 1: Floating Label Blocks `getByLabelText` Queries
+**What goes wrong:** If the `<label>` is moved inside the `<input>` wrapper without keeping
+`htmlFor` and `id` matched, `screen.getByLabelText(/storage account name/i)` throws. This
+breaks 30+ existing test assertions.
+**Why it happens:** Floating label patterns sometimes wrap label inside input's container
+without proper `for`/`id` association.
+**How to avoid:** Always include `<label htmlFor={id}>` paired with `<input id={id}>`. The
+label can be absolutely positioned visually while keeping the semantic association.
+**Warning signs:** `getByLabelText` test failures immediately after TextFieldMD3 integration.
+
+### Pitfall 2: `placeholder=" "` Conflicts with Real Placeholder Text
+**What goes wrong:** Fields like `sas_url` have meaningful placeholder text
+(`"https://mystorageaccount.blob.core.windows.net/?sv=..."`). Replacing it with `" "` loses
+the hint.
+**Why it happens:** The CSS floating label trick requires `placeholder=" "` to trigger
+`:placeholder-shown`, but fields want real placeholder hints too.
+**How to avoid:** Use `helpText` prop for the contextual hint instead of placeholder. The
+field shows the hint below the input. This is actually MORE accessible (visible even after
+typing). Verify existing `helpText` content is adequate before removing real placeholders.
+**Warning signs:** User confusion about what to enter in credential fields.
+
+### Pitfall 3: `peer-not-placeholder-shown` Availability in Tailwind v4
+**What goes wrong:** The Tailwind v4 `peer-placeholder-shown:` variant works, but
+`peer-not-placeholder-shown:` may not be a built-in variant. Without it, a field with a
+pre-filled value (RHF `defaultValues`) won't show the floated label on initial render.
+**Why it happens:** Tailwind v4 generates variants from pseudo-classes, but negation of
+`placeholder-shown` may require the arbitrary variant syntax.
+**How to avoid:** Use `peer-[:not(:placeholder-shown)]:` for Tailwind v4 arbitrary variant,
+or manage a `data-has-value` attribute via a thin React wrapper that checks the registration
+value. The data-attribute approach is the most reliable cross-version fallback.
+**Warning signs:** Label overlaps with pre-filled text on initial render.
+
+### Pitfall 4: Button Test Selectors Break After Role Change
+**What goes wrong:** `screen.getByRole('button', { name: /next/i })` fails after button
+text changes from "Next" to an icon-only or different label.
+**Why it happens:** MD3 button redesign may tempt relabeling buttons.
+**How to avoid:** Keep button text labels unchanged. Style only className, never innerText.
+Audit existing test selectors before any button className change: `getByRole('button', { name: /next/i })`, `getByRole('button', { name: /back/i })`, `getByRole('button', { name: /copy/i })`.
+**Warning signs:** `Unable to find an accessible element with the role "button" and name /next/i` in test output.
+
+### Pitfall 5: StepIndicator Test Selector Drift
+**What goes wrong:** After StepIndicator rebuild, `screen.getAllByRole('button')` returns
+different count, and `buttons.find(b => b.textContent?.includes('Backend'))` fails because
+completed-step buttons now show "✓" instead of "✓ 1. Backend".
+**Why it happens:** Button textContent changed in the rebuild.
+**How to avoid:** Keep button `aria-label` meaningful AND keep the label text visible within
+the button (or as adjacent text). Test the rebuilt StepIndicator immediately. Adjust
+WIZD-03 test selectors if needed (which is expected and acceptable for this phase).
+**Warning signs:** `backendButton` undefined in StepIndicator tests.
+
+### Pitfall 6: PasswordField Show/Hide Button Interferes with Floating Label
+**What goes wrong:** The absolute-positioned show/hide toggle button overlaps the floating
+label when it's in the "up" position.
+**Why it happens:** Label transitions from bottom to top; toggle is at right-center.
+**How to avoid:** The toggle is `absolute right-2 top-1/2` which only overlaps the label
+when label is centered (empty state). Floated label goes to `top-3` which avoids overlap.
+Add sufficient `pr-10` padding to the input so text doesn't underlap the button.
+**Warning signs:** Show/hide button visually overlaps with floating label text.
+
+---
+
+## Code Examples
+
+### Complete TextFieldMD3 Reference Structure
+```tsx
+// Verified pattern from Flowbite floating label docs + MD3 spec
+// Key: placeholder=" " enables CSS-only floating label detection
+
+export function TextFieldMD3({ id, label, error, registration, type = 'text', helpText, required, suffix }: TextFieldMD3Props) {
+  return (
+    <div className="flex flex-col gap-1">
+      <div className="relative">
+        <input
+          id={id}
+          type={type}
+          placeholder=" "
+          className={[
+            'peer w-full rounded-t-md rounded-b-none border-0 border-b-2 bg-surface-container/30',
+            // Or for outlined variant:
+            // 'peer w-full rounded-md border bg-transparent',
+            'px-3 pb-2 pt-5 text-sm text-on-surface placeholder-transparent',
+            'focus:outline-none focus:ring-0',
+            error
+              ? 'border-error focus:border-error'
+              : 'border-outline focus:border-primary',
+            suffix ? 'pr-10' : '',
+          ].join(' ')}
+          {...registration}
+        />
+        <label
+          htmlFor={id}
+          className={[
+            // Starting (centered) position — when input empty and unfocused
+            'pointer-events-none absolute left-3 top-1/2 -translate-y-1/2 text-sm',
+            'origin-left transform transition-all duration-200',
+            'text-on-surface-container/60',
+            // Focused state: float up
+            'peer-focus:top-3 peer-focus:-translate-y-0 peer-focus:scale-75 peer-focus:text-primary',
+            // Has value state (input not showing placeholder):
+            'peer-[:not(:placeholder-shown)]:top-3',
+            'peer-[:not(:placeholder-shown)]:-translate-y-0',
+            'peer-[:not(:placeholder-shown)]:scale-75',
+            error ? 'peer-focus:text-error' : '',
+          ].join(' ')}
+        >
+          {label}
+          {required && <span className="ml-0.5 text-error">*</span>}
+        </label>
+        {suffix && (
+          <div className="absolute right-2 top-1/2 -translate-y-1/2">{suffix}</div>
+        )}
+      </div>
+      {helpText && !error && (
+        <p className="text-xs text-on-surface-container/70">{helpText}</p>
+      )}
+      {error && (
+        <p className="text-xs text-error" role="alert">{error.message}</p>
+      )}
+    </div>
+  );
+}
+```
+
+### MD3 Button Class Sets
+```tsx
+// Source: MD3 button guidelines https://m3.material.io/components/all-buttons
+// Filled — primary action
+export const MD3_BTN_FILLED =
+  'px-6 py-2.5 rounded-full bg-primary text-on-primary text-sm font-medium ' +
+  'hover:opacity-90 active:opacity-80 transition-opacity ' +
+  'disabled:opacity-40 disabled:cursor-not-allowed ' +
+  'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary/50';
+
+// Outlined — secondary action
+export const MD3_BTN_OUTLINED =
+  'px-6 py-2.5 rounded-full border border-outline text-on-surface text-sm font-medium ' +
+  'hover:bg-primary/8 active:bg-primary/12 transition-colors ' +
+  'disabled:opacity-40 disabled:cursor-not-allowed ' +
+  'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary/50';
+
+// Text — tertiary action  
+export const MD3_BTN_TEXT =
+  'px-4 py-2.5 rounded-full text-primary text-sm font-medium ' +
+  'hover:bg-primary/8 active:bg-primary/12 transition-colors ' +
+  'disabled:opacity-40 disabled:cursor-not-allowed ' +
+  'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary/50';
+```
+
+### MD3 Elevation Level 1 CSS
+```css
+/* Source: studioncreations.com/blog/material-design-3-box-shadow-css-values/ */
+/* MD3 elevation-1 */
+.elevation-1 {
+  box-shadow: 0 1px 4px 0 rgba(0, 0, 0, 0.37);
+}
+/* In Tailwind, `shadow` utility is approximately equivalent.
+   For closer match, can extend @theme in index.css: */
+@theme {
+  --shadow-elevation-1: 0 1px 4px 0 rgb(0 0 0 / 0.37);
+}
+```
+
+---
+
+## State of the Art
+
+| Old Approach | Current Approach | When Changed | Impact |
+|--------------|------------------|--------------|--------|
+| Static `<label>` above input | CSS floating label via `peer` | Phase 9 | More visual richness; same DOM semantics |
+| Inline `style={{}}` on StepIndicator | Tailwind classes only | Phase 9 | Token-aware, dark-mode compatible |
+| `rounded-md` for cards | `rounded-xl` (MD3 medium shape) | Phase 9 | Matches MD3 12dp corner radius |
+| Raw `#999` color | `text-on-surface-container/40` | Phase 9 | Token-driven, dark-mode aware |
+| `rounded` buttons | `rounded-full` (MD3 pill buttons) | Phase 9 | MD3 standard button shape |
+
+**Deprecated/outdated in this codebase:**
+- Any remaining `style={{ color: '#...' }}` or `style={{ fontWeight: ... }}` — all must become Tailwind classes
+
+---
+
+## Open Questions
+
+1. **`peer-[:not(:placeholder-shown)]` Tailwind v4 support**
+   - What we know: Tailwind v4 supports arbitrary variants with bracket syntax
+   - What's unclear: Whether the specific `peer-[:not(:placeholder-shown)]:` form compiles correctly in v4.2.2
+   - Recommendation: Test in Wave 0 with a minimal test case; if it fails, use the `data-has-value` attribute approach
+
+2. **Button text changes breaking existing tests**
+   - What we know: Several tests use `getByRole('button', { name: /next/i })` etc.
+   - What's unclear: Whether any planned button text changes (e.g., "Next / Review" → "Next") would break selectors
+   - Recommendation: Audit test expectations against planned button labels before implementation; keep inner text identical
+
+3. **StepIndicator WIZD-03 test compatibility after rebuild**
+   - What we know: Tests use `buttons.find(b => b.textContent?.includes('Backend'))` to locate step buttons
+   - What's unclear: After adding "✓" and changing button structure, does `textContent?.includes('Backend')` still match?
+   - Recommendation: New button structure should include the label text. If buttons render as `<button aria-label="Go to step 1: Backend">✓</button>`, the textContent test will fail. Consider keeping label text visible inside button OR updating the test (acceptable in Phase 9).
+
+---
+
+## Validation Architecture
+
+### Test Framework
+| Property | Value |
+|----------|-------|
+| Framework | Vitest 4.1.1 |
+| Config file | `vite.config.ts` (has `test.environment: jsdom`) |
+| Quick run command | `npx vitest run --reporter=dot` |
+| Full suite command | `npx vitest run` |
+
+### Phase Requirements → Test Map
+| Req ID | Behavior | Test Type | Automated Command | File Exists? |
+|--------|----------|-----------|-------------------|-------------|
+| COMP-01 | TextFieldMD3 floating label floats on focus and when has value | unit | `npx vitest run src/components/ui/TextFieldMD3.test.tsx` | ❌ Wave 0 |
+| COMP-01 | FieldRenderer text-branch uses TextFieldMD3 (label still queryable) | unit | `npx vitest run src/components/wizard/RemoteConfigStep.test.tsx` | ✅ (existing coverage) |
+| COMP-02 | Buttons have correct role and text (Next, Back, Copy, Download) | unit | `npx vitest run src/components/wizard/ReviewStep.test.tsx` | ✅ (existing coverage) |
+| COMP-03 | BackendCard has `rounded-xl` className | unit | `npx vitest run src/components/ui/BackendCard.test.tsx` | ❌ Wave 0 |
+| COMP-04 | StepIndicator: completed steps are clickable buttons | unit | `npx vitest run src/components/wizard/StepIndicator.test.tsx` | ✅ (existing coverage) |
+| COMP-04 | StepIndicator: clicking step 0 dispatches SET_REMOTE_PARAMS({}) | unit | `npx vitest run src/components/wizard/StepIndicator.test.tsx` | ✅ (existing coverage) |
+| DEBT-01 | FieldRenderer select-branch tooltip button has aria-label | unit | `npx vitest run src/components/ui/FieldRenderer.test.tsx` | ❌ Wave 0 |
+| DEBT-01 | FieldRenderer text-branch tooltip button has aria-label | unit | `npx vitest run src/components/ui/FieldRenderer.test.tsx` | ❌ Wave 0 |
+
+### Sampling Rate
+- **Per task commit:** `npx vitest run --reporter=dot` (full suite, ~7s)
+- **Per wave merge:** `npx vitest run` (verbose, all 166+ tests)
+- **Phase gate:** Full suite green before `/gsd:verify-work`
+
+### Wave 0 Gaps
+- [ ] `src/components/ui/TextFieldMD3.test.tsx` — covers COMP-01 floating label behavior
+- [ ] `src/components/ui/BackendCard.test.tsx` — covers COMP-03 elevation class presence
+- [ ] `src/components/ui/FieldRenderer.test.tsx` — covers DEBT-01 aria-label consistency
+
+*(Existing StepIndicator.test.tsx covers COMP-04 behavioral requirements. Update to
+match rebuilt component's button textContent if needed.)*
+
+---
+
+## Sources
+
+### Primary (HIGH confidence)
+- Flowbite floating label docs — https://flowbite.com/docs/forms/floating-label/ — floating label peer structure
+- material-web.dev text field — https://material-web.dev/components/text-field/ — MD3 outlined field behavior spec
+- MD3 buttons guidelines — https://m3.material.io/components/buttons/guidelines — button hierarchy and specs
+- MD3 all buttons — https://m3.material.io/components/all-buttons — filled/outlined/text specs
+
+### Secondary (MEDIUM confidence)
+- studioncreations.com MD3 box-shadow values — https://studioncreations.com/blog/material-design-3-box-shadow-css-values/ — elevation CSS values (note: elevation spec was alpha status)
+- DEV Community floating label with Tailwind — https://dev.to/chrsgrrtt/floating-label-input-with-react-and-tailwind-2e5h — React + Tailwind implementation
+- jakedawkins.com accessible floating label — https://jakedawkins.com/blog/accessible-input-floating-label/ — accessibility considerations
+
+### Tertiary (LOW confidence)
+- MD3 elevation tonal tint behavior — from WebSearch summary only; tonal tint percentage (5% primary overlay) is an estimate from pattern observation, not precisely measured from spec
+
+---
+
+## Metadata
+
+**Confidence breakdown:**
+- Standard stack: HIGH — all dependencies already installed, no new additions
+- Architecture: HIGH — current component code fully audited, patterns verified
+- Pitfalls: HIGH — based on direct code analysis of existing test selectors and component structure
+- Floating label CSS: MEDIUM — Tailwind v4 `peer-[:not(:placeholder-shown)]` syntax needs runtime verification
+- MD3 elevation shadow values: MEDIUM — sourced from third-party CSS values article, not official spec
+
+**Research date:** 2026-04-01
+**Valid until:** 2026-05-01 (stable libraries; Tailwind v4 is releasing updates)