docs(10-content-clarity): create phase plan
3 plans in 1 wave covering UX-01 through UX-04: intro section, remote name preview, step descriptions, and credential help text. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Claude Opus 4.6
@@ -0,0 +1,199 @@
|
||||
---
|
||||
phase: 10-content-clarity
|
||||
plan: 01
|
||||
type: execute
|
||||
wave: 1
|
||||
depends_on: []
|
||||
files_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
|
||||
autonomous: true
|
||||
requirements:
|
||||
- UX-01
|
||||
- UX-03
|
||||
|
||||
must_haves:
|
||||
truths:
|
||||
- "First-time visitor sees an intro section explaining what Ready2Blob does before the wizard loads"
|
||||
- "Clicking Get Started hides the intro and reveals Step 1 with StepIndicator"
|
||||
- "On page reload, intro shows again (no persistence)"
|
||||
- "Each of the 4 wizard steps has a 1-2 sentence description below the heading"
|
||||
artifacts:
|
||||
- path: "src/App.tsx"
|
||||
provides: "IntroSection component and showIntro state gate in WizardShell"
|
||||
contains: "showIntro"
|
||||
- path: "src/App.test.tsx"
|
||||
provides: "Tests for intro rendering and Get Started button behavior"
|
||||
contains: "Get Started"
|
||||
- path: "src/components/wizard/BackendSelectionStep.tsx"
|
||||
provides: "Step 1 description paragraph"
|
||||
contains: "text-sm"
|
||||
- path: "src/components/wizard/RemoteConfigStep.tsx"
|
||||
provides: "Step 2 description paragraph"
|
||||
contains: "text-sm"
|
||||
- path: "src/components/wizard/DeploymentStep.tsx"
|
||||
provides: "Step 3 description paragraph"
|
||||
contains: "text-sm"
|
||||
- path: "src/components/wizard/ReviewStep.tsx"
|
||||
provides: "Step 4 description paragraph"
|
||||
contains: "text-sm"
|
||||
key_links:
|
||||
- from: "src/App.tsx"
|
||||
to: "IntroSection"
|
||||
via: "showIntro state toggle"
|
||||
pattern: "setShowIntro\\(false\\)"
|
||||
- from: "src/App.tsx"
|
||||
to: "StepIndicator"
|
||||
via: "conditional render when showIntro is false"
|
||||
pattern: "showIntro.*StepIndicator"
|
||||
---
|
||||
|
||||
<objective>
|
||||
Add the intro section that greets first-time visitors and step descriptions for all 4 wizard steps.
|
||||
|
||||
Purpose: A first-time user immediately understands what Ready2Blob does and what each step expects, without external documentation.
|
||||
Output: IntroSection in App.tsx with CTA, step description paragraphs in all 4 step components, updated App.test.tsx.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@C:/Users/SebastienQUEROL/.claude/get-shit-done/workflows/execute-plan.md
|
||||
@C:/Users/SebastienQUEROL/.claude/get-shit-done/templates/summary.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.planning/PROJECT.md
|
||||
@.planning/ROADMAP.md
|
||||
@.planning/STATE.md
|
||||
@.planning/phases/10-content-clarity/10-CONTEXT.md
|
||||
@.planning/phases/10-content-clarity/10-RESEARCH.md
|
||||
|
||||
<interfaces>
|
||||
<!-- Key types and contracts the executor needs -->
|
||||
|
||||
From src/App.tsx (current structure):
|
||||
```tsx
|
||||
function WizardShell() {
|
||||
const { state } = useWizard();
|
||||
// steps array, stepIndex clamped, renders StepIndicator + CurrentStep
|
||||
return (
|
||||
<div className="min-h-screen bg-surface flex flex-col items-center py-12 px-4">
|
||||
<div className="w-full max-w-2xl">
|
||||
<div className="flex items-center justify-between mb-8">
|
||||
<h1 className="text-3xl font-bold text-on-surface">Ready2Blob</h1>
|
||||
<ThemeToggle />
|
||||
</div>
|
||||
<StepIndicator />
|
||||
<div className="mt-8">{CurrentStep}</div>
|
||||
</div>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
From src/App.test.tsx (line 55-63 — WILL BREAK, must update):
|
||||
```tsx
|
||||
it('renders BackendSelectionStep when currentStep is 0', () => {
|
||||
render(<App />);
|
||||
const heading = screen.getByText(/Select Backend/);
|
||||
expect(heading).toBeDefined();
|
||||
const stepNav = screen.getByRole('navigation', { name: /Wizard steps/i });
|
||||
expect(stepNav).toBeDefined();
|
||||
});
|
||||
```
|
||||
Note: The renderAtStep() helper bypasses WizardShell entirely, so step 1/2 tests are UNAFFECTED.
|
||||
|
||||
MD3 button constant available:
|
||||
```tsx
|
||||
import { MD3_BTN_FILLED } from '../components/ui/TextFieldMD3'; // or wherever exported
|
||||
```
|
||||
Check actual export location — may be in a shared constants file.
|
||||
</interfaces>
|
||||
</context>
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 1: Add IntroSection and showIntro gate to App.tsx</name>
|
||||
<files>src/App.tsx</files>
|
||||
<action>
|
||||
Add `useState` import from React. Add `showIntro` local state (default `true`) to `WizardShell`.
|
||||
|
||||
When `showIntro` is true, render an IntroSection inline (can be a local component or JSX block) INSTEAD of StepIndicator + step content. The intro section must:
|
||||
- Keep the existing header layout (h1 "Ready2Blob" + ThemeToggle) at the top
|
||||
- Show action-first copy: "Go from zero to a deployable rclone setup in minutes" per user decision
|
||||
- Mention "Azure Blob, S3, OneDrive, and 4 more cloud backends" per user decision
|
||||
- Briefly explain what the tool generates (rclone config + deployment scripts)
|
||||
- Show a "Get Started" CTA button using MD3_BTN_FILLED style that sets `showIntro(false)`
|
||||
- Use MD3 tokens for all styling: `bg-surface`, `text-on-surface`, `bg-primary`, `text-on-primary`, etc.
|
||||
- No persistence — on page reload, intro shows again (wizard state is ephemeral)
|
||||
- No collapse/shrink behavior — intro simply disappears when wizard starts
|
||||
|
||||
When `showIntro` is false, render the existing wizard content (StepIndicator + step) unchanged.
|
||||
|
||||
IMPORTANT: Do NOT add intro state to useReducer/WizardState. This is purely local UI state via useState.
|
||||
IMPORTANT: Check where MD3_BTN_FILLED is exported from — grep for it. Use the correct import path.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>npx vitest run src/App.test.tsx</automated>
|
||||
</verify>
|
||||
<done>App renders IntroSection on initial load with "Get Started" button. Clicking it reveals the wizard. Page reload shows intro again.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 2: Update App.test.tsx and add step descriptions to all 4 step components</name>
|
||||
<files>src/App.test.tsx, src/components/wizard/BackendSelectionStep.tsx, src/components/wizard/RemoteConfigStep.tsx, src/components/wizard/DeploymentStep.tsx, src/components/wizard/ReviewStep.tsx</files>
|
||||
<action>
|
||||
**App.test.tsx updates:**
|
||||
|
||||
The existing test "renders BackendSelectionStep when currentStep is 0" will fail because `<App />` now shows IntroSection first. Update this test to:
|
||||
1. First assert that IntroSection content is visible (e.g., check for "Get Started" button or the intro copy)
|
||||
2. Click "Get Started"
|
||||
3. THEN assert "Select Backend" heading and StepIndicator navigation are visible
|
||||
|
||||
Add a new test:
|
||||
- "shows intro section on initial render" — render `<App />`, assert intro copy is present, assert StepIndicator is NOT in the DOM
|
||||
|
||||
The renderAtStep() tests (step 1, step 2) bypass WizardShell entirely so they need NO changes.
|
||||
|
||||
**Step descriptions (UX-03):**
|
||||
|
||||
Add a `<p>` element immediately after the `<h2>` in each of the 4 step components. Use className `text-sm text-on-surface-variant mt-1 mb-4`. Claude has discretion on wording, but each must be 1-2 sentences explaining what the user is doing and why. Suggested tone — direct, practical, no jargon:
|
||||
|
||||
- BackendSelectionStep: Explain that the user names their remote and picks a cloud storage provider
|
||||
- RemoteConfigStep: Explain that the user enters credentials for the selected backend
|
||||
- DeploymentStep: Explain that the user chooses how the config gets deployed to the target machine
|
||||
- ReviewStep: Explain that the user reviews generated files and downloads them
|
||||
|
||||
IMPORTANT: Do NOT change any heading text (h2 content must remain identical). Only ADD a `<p>` after the `<h2>`.
|
||||
IMPORTANT: Use `text-on-surface-variant` (not `text-on-surface-container/70`) — this is the standard MD3 secondary text token.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>npx vitest run</automated>
|
||||
</verify>
|
||||
<done>All tests pass. Intro renders on initial App load, clicking Get Started reveals wizard. All 4 steps show a description paragraph below the heading.</done>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<verification>
|
||||
1. `npx vitest run` — full suite green
|
||||
2. IntroSection visible on initial `<App />` render
|
||||
3. "Get Started" click transitions to wizard with StepIndicator
|
||||
4. Each step component has a descriptive `<p>` after its `<h2>`
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
- First-time visitor sees intro with "Get Started" CTA before wizard
|
||||
- Clicking CTA reveals Step 1 with StepIndicator
|
||||
- Page reload brings back intro (no persistence)
|
||||
- All 4 steps have description text below headings
|
||||
- All existing tests pass (including updated App.test.tsx)
|
||||
</success_criteria>
|
||||
|
||||
<output>
|
||||
After completion, create `.planning/phases/10-content-clarity/10-01-SUMMARY.md`
|
||||
</output>
|
||||
Reference in New Issue
Block a user