From 9196d030cc83dd469875086c8a0b6d3f90cea050 Mon Sep 17 00:00:00 2001 From: Kawa Date: Tue, 31 Mar 2026 17:42:16 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20create=20milestone=20v1.2=20roadmap=20(?= =?UTF-8?q?4=20phases)=20=E2=80=94=2015=20requirements=20mapped?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.6 (1M context) --- .planning/REQUIREMENTS.md | 36 +++++++++++------------ .planning/ROADMAP.md | 61 +++++++++++++++++++++++++++++++++++++++ .planning/STATE.md | 30 +++++++++++-------- 3 files changed, 97 insertions(+), 30 deletions(-) diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index a64b81b..53dfeb0 100644 --- a/.planning/REQUIREMENTS.md +++ b/.planning/REQUIREMENTS.md @@ -56,27 +56,27 @@ | Requirement | Phase | Status | |-------------|-------|--------| -| THEME-01 | — | Pending | -| THEME-02 | — | Pending | -| COMP-01 | — | Pending | -| COMP-02 | — | Pending | -| COMP-03 | — | Pending | -| COMP-04 | — | Pending | -| UX-01 | — | Pending | -| UX-02 | — | Pending | -| UX-03 | — | Pending | -| UX-04 | — | Pending | -| POLISH-01 | — | Pending | -| POLISH-02 | — | Pending | -| POLISH-03 | — | Pending | -| POLISH-04 | — | Pending | -| DEBT-01 | — | Pending | +| THEME-01 | Phase 8 | Pending | +| THEME-02 | Phase 8 | Pending | +| COMP-01 | Phase 9 | Pending | +| COMP-02 | Phase 9 | Pending | +| COMP-03 | Phase 9 | Pending | +| COMP-04 | Phase 9 | Pending | +| DEBT-01 | Phase 9 | Pending | +| UX-01 | Phase 10 | Pending | +| UX-02 | Phase 10 | Pending | +| UX-03 | Phase 10 | Pending | +| UX-04 | Phase 10 | Pending | +| POLISH-01 | Phase 11 | Pending | +| POLISH-02 | Phase 11 | Pending | +| POLISH-03 | Phase 11 | Pending | +| POLISH-04 | Phase 11 | Pending | **Coverage:** - v1.2 requirements: 15 total -- Mapped to phases: 0 -- Unmapped: 15 ⚠️ +- Mapped to phases: 15 +- Unmapped: 0 --- *Requirements defined: 2026-03-31* -*Last updated: 2026-03-31 after initial definition* +*Last updated: 2026-03-31 after roadmap creation* diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index 4e4b823..4ca359a 100644 --- a/.planning/ROADMAP.md +++ b/.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 +### 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 | - | diff --git a/.planning/STATE.md b/.planning/STATE.md index 1fef907..4e42727 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -2,12 +2,12 @@ gsd_state_version: 1.0 milestone: v1.2 milestone_name: UI Polish & Clarity -status: planning -stopped_at: Defining requirements -last_updated: "2026-03-31T15:30:00Z" -last_activity: 2026-03-31 — Milestone v1.2 started +status: roadmap_complete +stopped_at: Roadmap created, ready to plan Phase 8 +last_updated: "2026-03-31T16:00:00Z" +last_activity: 2026-03-31 — Roadmap created (4 phases, 15 requirements mapped) progress: - total_phases: 0 + total_phases: 4 completed_phases: 0 total_plans: 0 completed_plans: 0 @@ -21,14 +21,14 @@ progress: See: .planning/PROJECT.md (updated 2026-03-31) **Core value:** An IT pro can go from zero to a deployable rclone setup in minutes — without needing to know rclone's config syntax or PowerShell deployment conventions. -**Current focus:** v1.2 — UI Polish & Clarity (defining requirements) +**Current focus:** v1.2 — UI Polish & Clarity (Phase 8: Theme Foundation next) ## Current Position -Phase: Not started (defining requirements) +Phase: 8 of 11 (Theme Foundation) — not yet started Plan: — -Status: Defining requirements -Last activity: 2026-03-31 — Milestone v1.2 started +Status: Ready to plan Phase 8 +Last activity: 2026-03-31 — Roadmap created for v1.2 Progress: [░░░░░░░░░░] 0% (v1.2) @@ -37,6 +37,11 @@ Progress: [░░░░░░░░░░] 0% (v1.2) ### Decisions Decisions are logged in PROJECT.md Key Decisions table. +Recent decisions affecting current work: + +- v1.2 roadmap: Zero new runtime dependencies — Tailwind v4 @theme + CSS custom properties only +- v1.2 roadmap: Bottom-up migration order (tokens -> primitives -> migration -> content -> polish) +- v1.2 roadmap: ThemeToggle via DOM class toggle, not React Context (avoids re-render cascade) ### Pending Todos @@ -44,10 +49,11 @@ None yet. ### Blockers/Concerns -None yet. +- 73 hardcoded color classes need migration to semantic tokens (Phase 9 risk) +- 131 test selectors could break during component restyling — one-component-at-a-time discipline required ## Session Continuity -Last session: 2026-03-31T15:30:00Z -Stopped at: Milestone v1.2 started — defining requirements +Last session: 2026-03-31T16:00:00Z +Stopped at: Roadmap created for v1.2 — ready to plan Phase 8 Resume file: None