From 43c83bf3991f2f4292c6c9a0975364b34c2f6a19 Mon Sep 17 00:00:00 2001 From: Kawa Date: Wed, 1 Apr 2026 12:32:24 +0200 Subject: [PATCH] docs(10): capture phase context Co-Authored-By: Claude Opus 4.6 (1M context) --- .../phases/10-content-clarity/10-CONTEXT.md | 92 +++++++++++++++++++ 1 file changed, 92 insertions(+) create mode 100644 .planning/phases/10-content-clarity/10-CONTEXT.md diff --git a/.planning/phases/10-content-clarity/10-CONTEXT.md b/.planning/phases/10-content-clarity/10-CONTEXT.md new file mode 100644 index 0000000..e10545b --- /dev/null +++ b/.planning/phases/10-content-clarity/10-CONTEXT.md @@ -0,0 +1,92 @@ +# Phase 10: Content & Clarity - Context + +**Gathered:** 2026-04-01 +**Status:** Ready for planning + + +## Phase Boundary + +A first-time visitor understands what Ready2Blob does and what each wizard step expects without external documentation. This phase adds an intro section, remote name guidance with live preview, step descriptions, and contextual help text for all backend credential fields. + + + + +## Implementation Decisions + +### Intro section (UX-01) +- Inline above wizard in the same page — no routing, no separate landing page +- Action-first tone: lead with the outcome ("Go from zero to a deployable rclone setup in minutes") +- Mention top 3 backends + count: "Azure Blob, S3, OneDrive, and 4 more cloud backends" +- CTA button "Get Started" — clicking hides the intro and reveals Step 1 with StepIndicator +- On page reload, intro shows again (no persistence — wizard state is ephemeral) +- No collapse/shrink behavior — intro simply disappears when wizard starts + +### Remote name experience (UX-02) +- Inline config preview below the TextFieldMD3 field, styled with MD3 surface tokens +- Live preview updates as user types, showing `[remote-name]` config syntax in a small code box +- When field is empty: show grayed-out placeholder example `[my-remote]` with note "Type a name to see how it appears in your config" +- Field placeholder: `e.g. my-backup` +- Help text: detailed with example — "This becomes the section header [name] in your rclone.conf. Example: azure-prod, backup-s3. Letters, numbers, dashes, underscores only." +- Preview depth (header only vs header + type line): Claude's discretion + +### Step descriptions (UX-03) +- Claude's discretion on tone and wording +- Each of the 4 steps gets a 1-2 sentence description below the heading explaining what the user is doing and why + +### Credential help text (UX-04) +- Add tooltipText to all fields that lack it (S3, S3-compatible, GCS, SFTP, B2, OneDrive drive_id) — tooltip explains where to find the value in the provider's console +- Include links to provider docs only for complex/non-obvious flows (OneDrive token procedure, GCS service account JSON creation). No links for straightforward fields like S3 keys. +- Add short helpText only where the label alone is ambiguous (S3 access_key_id, secret_access_key, S3-compatible equivalents). Skip self-explanatory fields (SFTP Username, Host). +- Existing helpText and tooltipText (Azure Blob fields, OneDrive token, SFTP password/key_pem) are already good — don't rewrite + +### Claude's Discretion +- Step description wording and tone for all 4 steps +- Remote name preview depth (header only vs header + type line) +- Exact tooltip wording for each backend field +- Which fields qualify as "non-obvious" enough to warrant doc links +- Intro section visual styling (spacing, typography, icon/illustration presence) + + + + +## Existing Code Insights + +### Reusable Assets +- `TextFieldMD3` (src/components/ui/TextFieldMD3.tsx): Floating label input — remote name field already uses it +- `FieldRenderer` (src/components/ui/FieldRenderer.tsx): Renders fields with tooltip (hover+click) and helpText infrastructure +- `PasswordField` (src/components/ui/PasswordField.tsx): Handles password fields with show/hide toggle +- MD3 button constants (`MD3_BTN_FILLED`, `MD3_BTN_OUTLINED`): Available for CTA button +- MD3 color tokens: `bg-surface`, `text-on-surface`, `bg-primary`, etc. — all in place from Phase 8 + +### Established Patterns +- Tooltip infrastructure: `tooltipText` field in FieldDef triggers info icon with hover+click behavior in FieldRenderer +- `helpText` renders as small text below inputs; `helpTextPrefix` prop on TextFieldMD3 for icon placement +- BACKEND_REGISTRY in `src/schemas/registry.ts` is single source of truth for field definitions +- No routing — wizard is state-driven via `currentStep` in useReducer + +### Integration Points +- `src/App.tsx` WizardShell: Intro section goes above StepIndicator, controlled by local state (showIntro) +- `src/components/wizard/BackendSelectionStep.tsx`: Remote name TextFieldMD3 needs preview component added below it +- `src/schemas/registry.ts`: All helpText and tooltipText additions go here +- Each step component (`BackendSelectionStep`, `RemoteConfigStep`, `DeploymentStep`, `ReviewStep`): Step descriptions go below existing `

` headings + + + + +## Specific Ideas + +No specific requirements — open to standard approaches + + + + +## Deferred Ideas + +None — discussion stayed within phase scope + + + +--- + +*Phase: 10-content-clarity* +*Context gathered: 2026-04-01*