Ready2Blob/.planning/REQUIREMENTS.md

Requirements: Ready2Blob

Defined: 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.

v1.2 Requirements

Theme

• THEME-01: App uses a consistent MD3 color token system (CSS custom properties) that all components reference instead of hardcoded Tailwind color classes
• THEME-02: User can toggle between System, Light, and Dark themes, with choice persisted across sessions and no flash of unstyled content on load

Components

• COMP-01: All text inputs render as MD3 outlined text fields with floating labels that animate on focus and when the field has content
• COMP-02: Buttons follow MD3 hierarchy — filled for primary actions (Next, Download), outlined for secondary (Back, Copy), text for tertiary
• COMP-03: Backend selection cards and output blocks use MD3 elevation with tonal surface tint, consistent padding, and shape tokens
• COMP-04: Step indicator displays as numbered circles connected by lines, with completed steps showing a checkmark, current step highlighted, and future steps muted

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
• 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
• UX-04: All backend credential fields have contextual help text explaining what to enter and where to find it

Polish

• POLISH-01: Wizard layout adapts to mobile screens — backend cards stack, form fields go full-width, step indicator collapses, buttons stretch
• POLISH-02: All interactive elements have visible MD3 focus indicators (3px outline) using focus-visible for keyboard navigation
• POLISH-03: Step transitions use subtle fade/slide animation that respects prefers-reduced-motion
• POLISH-04: On validation failure, the view auto-scrolls to the first errored field

Tech Debt

• DEBT-01: FieldRenderer uses consistent aria-label pattern across text-branch and select-branch (resolving v1.1 cosmetic debt)

Future Requirements

• Accent color presets (5-8 curated themes) — deferred from v1.2 scoping
• Code block syntax highlighting in ReviewStep output blocks
• Upgraded tooltip popovers with Floating UI positioning
• Custom styled select/dropdown replacing native <select>

Out of Scope

Feature	Reason
MUI or Material Tailwind component library	Bundle bloat (~300KB+) for 4-step wizard; custom tokens + Tailwind lighter and fully controlled
Page-per-step routing (React Router)	Wizard state is ephemeral credentials in memory; refreshing loses context; bookmarking credential step is security anti-pattern
Glassmorphism / neomorphism effects	CPU-intensive, low contrast accessibility issues, will look dated quickly
Arbitrary user-picked hex color	Breaks accessibility (contrast ratios); curated presets cover 95% of personalization need
Custom checkbox/radio styling	High effort for few toggles; native inputs with MD3-inspired wrappers sufficient

Traceability

Requirement	Phase	Status
THEME-01	Phase 8	Complete
THEME-02	Phase 8	Complete
COMP-01	Phase 9	Complete
COMP-02	Phase 9	Complete
COMP-03	Phase 9	Complete
COMP-04	Phase 9	Complete
DEBT-01	Phase 9	Complete
UX-01	Phase 10	Complete
UX-02	Phase 10	Complete
UX-03	Phase 10	Complete
UX-04	Phase 10	Complete
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: 15
• Unmapped: 0

---

Requirements defined: 2026-03-31 Last updated: 2026-03-31 after roadmap creation