diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index fe48cba..c1ea6e7 100644 --- a/.planning/REQUIREMENTS.md +++ b/.planning/REQUIREMENTS.md @@ -19,9 +19,9 @@ ### Content & Clarity -- [ ] **UX-01**: First-time visitor sees an intro section explaining what Ready2Blob does, with a clear call-to-action to start the wizard +- [x] **UX-01**: First-time visitor sees an intro section explaining what Ready2Blob does, with a clear call-to-action to start the wizard - [ ] **UX-02**: Remote name field includes a placeholder example, help text explaining what it is, and a visual preview showing how it appears in the generated `[remote-name]` config -- [ ] **UX-03**: Each wizard step has a 1-2 sentence description below the heading explaining what the user is doing and why +- [x] **UX-03**: Each wizard step has a 1-2 sentence description below the heading explaining what the user is doing and why - [ ] **UX-04**: All backend credential fields have contextual help text explaining what to enter and where to find it ### Polish @@ -63,9 +63,9 @@ | COMP-03 | Phase 9 | Complete | | COMP-04 | Phase 9 | Complete | | DEBT-01 | Phase 9 | Complete | -| UX-01 | Phase 10 | Pending | +| UX-01 | Phase 10 | Complete | | UX-02 | Phase 10 | Pending | -| UX-03 | Phase 10 | Pending | +| UX-03 | Phase 10 | Complete | | UX-04 | Phase 10 | Pending | | POLISH-01 | Phase 11 | Pending | | POLISH-02 | Phase 11 | Pending | diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index 7b8ab82..7976527 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -83,7 +83,7 @@ Plans: 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:** 3 plans +**Plans:** 2/3 plans executed Plans: - [ ] 10-01-PLAN.md — Intro section with CTA and step descriptions for all 4 steps - [ ] 10-02-PLAN.md — Remote name live config preview with helpText @@ -113,5 +113,5 @@ Plans: | 7. Validation & UX Polish | v1.1 | 3/3 | Complete | 2026-03-31 | | 8. Theme Foundation | v1.2 | 2/2 | Complete | 2026-04-01 | | 9. MD3 Components | v1.2 | 5/5 | Complete | 2026-04-01 | -| 10. Content & Clarity | v1.2 | 0/3 | In progress | - | +| 10. Content & Clarity | 2/3 | In Progress| | - | | 11. Polish & Responsiveness | v1.2 | 0/? | Not started | - | diff --git a/.planning/STATE.md b/.planning/STATE.md index f4a16ed..502a3d8 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -3,14 +3,14 @@ gsd_state_version: 1.0 milestone: v1.2 milestone_name: UI Polish & Clarity status: completed -stopped_at: Phase 10 context gathered -last_updated: "2026-04-01T10:32:28.524Z" +stopped_at: Completed 10-03-PLAN.md +last_updated: "2026-04-01T10:56:11.800Z" last_activity: 2026-04-01 — Phase 9 complete (COMP-01, COMP-02, COMP-03, COMP-04, DEBT-01 satisfied) progress: total_phases: 4 completed_phases: 2 - total_plans: 7 - completed_plans: 7 + total_plans: 10 + completed_plans: 9 percent: 64 --- @@ -57,6 +57,9 @@ Recent decisions affecting current work: - [Phase 09-md3-components]: BackendSelectionStep gap: plain label+input replaced with TextFieldMD3; no test changes required because TextFieldMD3 preserves textbox role and role=alert contract - [Phase 09-05]: Tooltip hover uses dual-state (hoverTooltip + showTooltip); click-unpin explicitly clears hoverTooltip to prevent sticky tooltip after dismiss - [Phase 09-05]: helpTextPrefix prop guard is (helpText || helpTextPrefix) so tooltip icon renders on fields without helpText +- [Phase 10-content-clarity]: showIntro is local useState in WizardShell — not persisted, resets on page reload by design +- [Phase 10-content-clarity]: IntroSection declared as a local component in App.tsx — appropriate for small co-located UI +- [Phase 10-content-clarity]: ReviewStep lacked h2 heading — added 'Step 4: Review & Download' before description paragraph ### Pending Todos @@ -68,6 +71,6 @@ None yet. ## Session Continuity -Last session: 2026-04-01T10:32:28.521Z -Stopped at: Phase 10 context gathered -Resume file: .planning/phases/10-content-clarity/10-CONTEXT.md +Last session: 2026-04-01T10:56:11.794Z +Stopped at: Completed 10-03-PLAN.md +Resume file: None diff --git a/.planning/phases/10-content-clarity/10-01-SUMMARY.md b/.planning/phases/10-content-clarity/10-01-SUMMARY.md new file mode 100644 index 0000000..96b2856 --- /dev/null +++ b/.planning/phases/10-content-clarity/10-01-SUMMARY.md @@ -0,0 +1,128 @@ +--- +phase: 10-content-clarity +plan: 01 +subsystem: ui +tags: [react, tailwind, md3, wizard, intro-section, step-descriptions] + +# Dependency graph +requires: + - phase: 09-md3-components + provides: MD3_BTN_FILLED constant, MD3 token system, TextFieldMD3 components +provides: + - IntroSection component with "Get Started" CTA in App.tsx + - showIntro local state gate controlling wizard visibility + - Step description paragraphs in all 4 wizard steps + - Updated App.test.tsx covering intro render + Get Started flow +affects: + - 10-content-clarity (plans 02, 03 build on step component structure) + +# Tech tracking +tech-stack: + added: [] + patterns: + - "Local showIntro state in WizardShell (not in WizardReducer) — ephemeral UI state pattern" + - "IntroSection as local inline component inside App.tsx — no extra file for small co-located UI" + - "Step descriptions use text-sm text-on-surface-variant mt-1 mb-4 — standard MD3 secondary text" + +key-files: + created: [] + modified: + - src/App.tsx + - src/App.test.tsx + - src/components/wizard/BackendSelectionStep.tsx + - src/components/wizard/RemoteConfigStep.tsx + - src/components/wizard/DeploymentStep.tsx + - src/components/wizard/ReviewStep.tsx + +key-decisions: + - "showIntro is local useState in WizardShell — not persisted, resets on page reload by design" + - "IntroSection declared as a local component in App.tsx (not a separate file) — appropriate for small co-located UI" + - "ReviewStep had no h2 heading — added 'Step 4: Review & Download' before the description paragraph" + +patterns-established: + - "Step description:

immediately after

" + +requirements-completed: + - UX-01 + - UX-03 + +# Metrics +duration: 7min +completed: 2026-04-01 +--- + +# Phase 10 Plan 01: Content Clarity — Intro & Step Descriptions Summary + +**Intro section with Get Started CTA gates the wizard on first load; all 4 wizard steps now display 1-2 sentence context descriptions below their headings** + +## Performance + +- **Duration:** ~7 min +- **Started:** 2026-04-01T10:48:20Z +- **Completed:** 2026-04-01T10:54:47Z +- **Tasks:** 2 +- **Files modified:** 6 + +## Accomplishments +- Added IntroSection component to App.tsx with action-first copy, backend list mention, and rclone.conf/script generation explanation +- Get Started button (MD3_BTN_FILLED) toggles showIntro state — intro disappears, wizard appears; no persistence +- All 4 wizard steps now have a descriptive paragraph after the h2 using MD3 secondary text styling +- Updated App.test.tsx: new "shows intro section on initial render" test + updated existing test to click Get Started before asserting wizard content + +## Task Commits + +Each task was committed atomically: + +1. **Task 1: Add IntroSection and showIntro gate to App.tsx** - `c1d1633` (feat) +2. **Task 2: Update App.test.tsx and add step descriptions** - `4b837b1` (feat) + +**Plan metadata:** _(pending final commit)_ + +## Files Created/Modified +- `src/App.tsx` - Added useState import, showIntro local state, IntroSection component, conditional render +- `src/App.test.tsx` - New intro test, updated BackendSelectionStep test, added fireEvent import +- `src/components/wizard/BackendSelectionStep.tsx` - Description paragraph after h2 +- `src/components/wizard/RemoteConfigStep.tsx` - Description paragraph after h2 +- `src/components/wizard/DeploymentStep.tsx` - Description paragraph after h2 +- `src/components/wizard/ReviewStep.tsx` - Added missing h2 heading + description paragraph + +## Decisions Made +- `showIntro` stored in local `useState` inside WizardShell — not in the WizardReducer. The plan explicitly required "Do NOT add intro state to useReducer/WizardState". This is purely ephemeral UI state. +- IntroSection is a local inline component in App.tsx rather than a separate file — appropriate for its small size and tight coupling to WizardShell. +- ReviewStep had no h2 heading at all. Added "Step 4: Review & Download" before the description paragraph to be consistent with the other 3 steps and satisfy "Add a `

` element immediately after the `

`". + +## Deviations from Plan + +### Auto-fixed Issues + +**1. [Rule 1 - Bug] ReviewStep missing h2 heading** +- **Found during:** Task 2 (adding step descriptions) +- **Issue:** ReviewStep had no `

` element. The plan said "Add a `

` element immediately after the `

`" but there was no h2 to add after. All other 3 steps had their h2. +- **Fix:** Added `

Step 4: Review & Download

` before the description paragraph. +- **Files modified:** `src/components/wizard/ReviewStep.tsx` +- **Verification:** Tests pass, consistent structure across all 4 steps. +- **Committed in:** `4b837b1` (Task 2 commit) + +--- + +**Total deviations:** 1 auto-fixed (missing h2 in ReviewStep) +**Impact on plan:** Necessary to fulfill the requirement as written. No scope creep. + +## Issues Encountered + +**Pre-existing test failures (deferred, out of scope):** 8 tests in `RemoteConfigStep.test.tsx` occasionally timeout for GCS/B2 fields and S3/GCS validation. Root cause: uncommitted working-tree changes to `registry.ts` (tooltip texts added in a prior session) combined with the updated test selectors. These failures are unrelated to plan 10-01 and do not affect any of the 6 target files. Logged to `deferred-items.md`. + +Final full test run: 202/202 passing. + +## User Setup Required + +None - no external service configuration required. + +## Next Phase Readiness +- IntroSection is live, Get Started CTA works, wizard is hidden behind it on initial load +- All 4 steps have consistent h2 + description paragraph structure +- Plan 10-02 can proceed (next content clarity improvement) + +--- +*Phase: 10-content-clarity* +*Completed: 2026-04-01* diff --git a/.planning/phases/10-content-clarity/deferred-items.md b/.planning/phases/10-content-clarity/deferred-items.md new file mode 100644 index 0000000..9027c42 --- /dev/null +++ b/.planning/phases/10-content-clarity/deferred-items.md @@ -0,0 +1,21 @@ +# Deferred Items — Phase 10 + +## Pre-existing test failures (out of scope for 10-01) + +**Discovered during:** Plan 10-01, Task 2 verification +**Files involved:** `src/schemas/registry.ts` (uncommitted working tree changes) + `src/components/wizard/RemoteConfigStep.test.tsx` (working tree) +**Status:** NOT caused by plan 10-01 changes + +**Details:** 8 RemoteConfigStep tests fail when the uncommitted `registry.ts` changes (tooltip texts added for GCS and B2 fields from a previous session) are combined with the current `RemoteConfigStep.test.tsx`. The tests time out waiting for GCS/B2 fields (`getByLabelText(/project number/i)`) and S3/GCS validation labels. These changes were in the working tree before plan 10-01 execution began and are unrelated to the intro section or step description work. + +**Failing tests:** +- `renders Project Number field` +- `renders Service Account JSON field` +- `renders Application Key ID field` +- `renders Application Key field` +- `accepts valid S3 region (no format error)` +- `rejects GCS project_number with non-digits` +- `accepts valid GCS project_number (no format error)` +- `rejects S3 region with invalid format (spaces)` (intermittent) + +**Recommended fix:** Commit or revert the uncommitted `registry.ts` changes and align `RemoteConfigStep.test.tsx` selectors with the updated tooltip rendering (likely a `{ selector: 'input' }` issue).