680 lines
34 KiB
Markdown
680 lines
34 KiB
Markdown
# 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)
|