docs: create milestone v1.2 roadmap (4 phases) — 15 requirements mapped

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

.planning/ROADMAP.md

@@ -4,6 +4,7 @@
 
 - ✅ **v1.0 MVP** — Phases 1–4 (shipped 2026-03-27)
 - ✅ **v1.1 Backlog & Tech Debt** — Phases 5–7 (shipped 2026-03-31)
+- **v1.2 UI Polish & Clarity** — Phases 8–11 (in progress)
 
 ## Phases
 
@@ -30,6 +31,62 @@ Full phase details: [.planning/milestones/v1.1-ROADMAP.md](milestones/v1.1-ROADM
 
 </details>
 
+### v1.2 UI Polish & Clarity (In Progress)
+
+**Milestone Goal:** Transform the bare functional wizard into a polished, self-explanatory experience with Material Design 3 styling, dark mode, contextual help, and responsive layout.
+
+- [ ] **Phase 8: Theme Foundation** - MD3 color token system and dark mode infrastructure
+- [ ] **Phase 9: MD3 Components** - UI primitives and component migration to semantic tokens
+- [ ] **Phase 10: Content & Clarity** - Intro section, step descriptions, and contextual help
+- [ ] **Phase 11: Polish & Responsiveness** - Mobile layout, focus states, transitions, scroll-to-error
+
+## Phase Details
+
+### Phase 8: Theme Foundation
+**Goal**: App has a complete MD3 color token system and working dark mode toggle with no flash of unstyled content
+**Depends on**: Phase 7 (v1.1 complete)
+**Requirements**: THEME-01, THEME-02
+**Success Criteria** (what must be TRUE):
+  1. All color values in the app flow from CSS custom properties defined in a single token file, not from hardcoded Tailwind color classes
+  2. User can toggle between System, Light, and Dark themes via a visible control, and the entire UI responds immediately
+  3. Theme preference persists in localStorage and applies on reload without any flash of wrong theme
+  4. Tailwind v4 `@theme` directive maps MD3 token names to utility classes (e.g., `bg-surface`, `text-on-primary`)
+**Plans**: TBD
+
+### Phase 9: MD3 Components
+**Goal**: All interactive elements use MD3-styled primitives with consistent visual language across the entire wizard
+**Depends on**: Phase 8
+**Requirements**: COMP-01, COMP-02, COMP-03, COMP-04, DEBT-01
+**Success Criteria** (what must be TRUE):
+  1. Text inputs render as outlined fields with floating labels that animate on focus and when the field has content
+  2. Buttons visually distinguish primary (filled), secondary (outlined), and tertiary (text) actions across all wizard steps
+  3. Backend selection cards and output blocks display MD3 elevation with tonal surface tint and consistent shape tokens
+  4. Step indicator shows numbered circles connected by lines, with checkmarks on completed steps, highlight on current, and muted future steps
+  5. FieldRenderer produces identical `aria-label` attributes for both text-branch and select-branch inputs
+**Plans**: TBD
+
+### Phase 10: Content & Clarity
+**Goal**: A first-time visitor understands what Ready2Blob does and what each wizard step expects without external documentation
+**Depends on**: Phase 8 (tokens needed for consistent styling of new content)
+**Requirements**: UX-01, UX-02, UX-03, UX-04
+**Success Criteria** (what must be TRUE):
+  1. Landing view shows an intro section explaining what Ready2Blob does with a clear call-to-action to start the wizard
+  2. Remote name field displays a placeholder example, help text, and a live preview showing how the name appears in `[remote-name]` config syntax
+  3. Every wizard step has a 1-2 sentence description below the heading explaining what the user is doing and why
+  4. All backend credential fields have contextual help text explaining what to enter and where to find the value
+**Plans**: TBD
+
+### Phase 11: Polish & Responsiveness
+**Goal**: The wizard feels production-ready on any device with smooth interactions and accessible keyboard navigation
+**Depends on**: Phase 9, Phase 10
+**Requirements**: POLISH-01, POLISH-02, POLISH-03, POLISH-04
+**Success Criteria** (what must be TRUE):
+  1. On a mobile viewport (< 640px), backend cards stack vertically, form fields span full width, step indicator collapses, and buttons stretch to fill width
+  2. Every interactive element shows a visible 3px MD3 focus outline when navigated via keyboard (using `focus-visible`)
+  3. Step transitions use a subtle fade/slide animation that is suppressed when the user has `prefers-reduced-motion` enabled
+  4. When form validation fails, the view auto-scrolls to the first field with an error
+**Plans**: TBD
+
 ## Progress
 
 | Phase | Milestone | Plans Complete | Status | Completed |
@@ -41,3 +98,7 @@ Full phase details: [.planning/milestones/v1.1-ROADMAP.md](milestones/v1.1-ROADM
 | 5. Tech Debt | v1.1 | 4/4 | Complete | 2026-03-30 |
 | 6. New Backends | v1.1 | 4/4 | Complete | 2026-03-31 |
 | 7. Validation & UX Polish | v1.1 | 3/3 | Complete | 2026-03-31 |
+| 8. Theme Foundation | v1.2 | 0/? | Not started | - |
+| 9. MD3 Components | v1.2 | 0/? | Not started | - |
+| 10. Content & Clarity | v1.2 | 0/? | Not started | - |
+| 11. Polish & Responsiveness | v1.2 | 0/? | Not started | - |