kawaandClaude Opus 4.6
4d4b01d9b7
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
221 lines
22 KiB
Markdown
221 lines
22 KiB
Markdown
# Feature Research
|
|
|
|
**Domain:** Material Design 3 UI polish for rclone configuration wizard
|
|
**Project:** Ready2Blob v1.2
|
|
**Researched:** 2026-03-31
|
|
**Confidence:** MEDIUM (MD3 web patterns well-documented; custom Tailwind implementation patterns less established than MUI-based approaches)
|
|
|
|
## Feature Landscape
|
|
|
|
This research covers the UI polish milestone only. The functional wizard (4 steps, 7 backends, validation, ZIP download) is already shipped. The question is: what transforms a bare, functional wizard into a professional, self-explanatory tool?
|
|
|
|
### Table Stakes (Users Expect These)
|
|
|
|
Features that any polished web form/wizard must have in 2026. Without these, the app looks like a prototype.
|
|
|
|
| Feature | Why Expected | Complexity | Notes |
|
|
|---------|--------------|------------|-------|
|
|
| **MD3 text field styling (outlined variant)** | Outlined text fields with floating labels are the modern standard for form inputs. The current bare `<input>` with static labels above looks dated. | MEDIUM | MD3 "outlined" style: 1px border that highlights on focus, label that floats into the border on focus/fill. Requires CSS-only animation or a small wrapper component. Tailwind v4 `@theme` tokens map well to MD3 color roles. |
|
|
| **MD3 button hierarchy (filled, outlined, text)** | Users expect visual hierarchy between primary actions (Next, Download) and secondary (Back, Copy). Current buttons use ad-hoc blue/gray with no consistent system. | LOW | Three tiers: filled (primary actions), outlined (secondary/back), text (tertiary). Use MD3 shape tokens (rounded-xl for buttons). Map to `--md-sys-color-primary` and `--md-sys-color-on-primary`. |
|
|
| **MD3 card components with elevation** | Backend selection cards and output blocks need consistent elevation, padding, and shape. Current cards have inconsistent border-only styling. | LOW | MD3 elevation uses tonal surface tint (not just shadows). Levels 0-5. Cards typically at level 1 (subtle tint + minimal shadow). Selected state bumps to level 2. |
|
|
| **Dark mode** | 87% of users prefer apps that support automatic theme switching. A dev/IT tool without dark mode feels incomplete. | MEDIUM | Three-state toggle: System / Light / Dark. Respect `prefers-color-scheme` as default. Persist choice in `localStorage`. Implement via `data-theme` attribute on `<html>` + CSS custom properties. Tailwind v4 `dark:` variant works with `@media (prefers-color-scheme: dark)` or class strategy. |
|
|
| **Consistent color token system** | Hardcoded `text-gray-700`, `bg-blue-600`, `border-red-500` scattered across components creates maintenance burden and makes theming impossible. | MEDIUM | Define MD3 color roles as CSS custom properties: `--color-primary`, `--color-on-primary`, `--color-surface`, `--color-on-surface`, `--color-error`, etc. All components reference tokens, not raw Tailwind colors. Enables dark mode and accent colors with a single layer of indirection. |
|
|
| **Proper step indicator / progress bar** | Current StepIndicator uses inline styles, plain text with ">" separators, and checkbox emoji. Looks unprofessional. | MEDIUM | MD3 stepper pattern: numbered circles connected by lines. Completed steps show checkmark icon in filled circle. Active step is highlighted with primary color. Future steps are muted. Must show step labels and be responsive (collapse labels on mobile, show numbers only). |
|
|
| **Responsive layout (mobile-friendly forms)** | IT admins use phones/tablets for quick reference or field work. Current `max-w-2xl` centered layout does not adapt form fields for small screens. | MEDIUM | Backend cards: grid `grid-cols-1 sm:grid-cols-2 lg:grid-cols-3`. Form fields: full-width on mobile, optionally 2-column on wide screens for short fields. Step indicator: horizontal on desktop, compact (numbers-only or dots) on mobile. Buttons: full-width on mobile. |
|
|
| **Form field error states (MD3 style)** | Current red border + small text is functional but not MD3-compliant. MD3 errors use the error color role, an error icon, and supporting text below the field. | LOW | Error state: border changes to `--color-error`, label text changes to error color, trailing error icon appears, supporting text shows error message in error color. Already have error messages; need to style them consistently. |
|
|
| **Step-level descriptions** | Each wizard step needs a brief explanation of what the user is doing and why. Current steps jump straight to form fields with only "Step N: Title". | LOW | 1-2 sentence description below each step heading. Examples: "Choose your cloud storage provider. This determines which credentials you will need." Static text, no logic. |
|
|
| **Accessible focus states** | EAA compliance (June 2025) requires visible focus indicators for keyboard navigation. Current `:focus` uses `ring-2` which is minimal. | LOW | MD3 focus: 3px outline using `--color-primary` with 2px offset. All interactive elements (buttons, inputs, cards, links) must have visible focus. Tailwind `focus-visible:` variant preferred over `focus:` to avoid showing focus on mouse click. |
|
|
|
|
### Differentiators (Competitive Advantage)
|
|
|
|
Features that elevate Ready2Blob from "functional tool" to "tool that inspires confidence."
|
|
|
|
| Feature | Value Proposition | Complexity | Notes |
|
|
|---------|-------------------|------------|-------|
|
|
| **User-selectable accent color** | Personalizes the tool. IT admins often match internal tools to company brand colors. Also demonstrates the token system works. | MEDIUM | Offer 5-8 preset accent colors (blue default, teal, purple, green, orange, pink). User picks one, CSS custom properties update for `--color-primary` and its derivatives. Persist in `localStorage`. Use MD3 tonal palette generation: from one source color, derive on-primary, primary-container, on-primary-container. |
|
|
| **App intro / landing section** | First-time visitors need to understand what Ready2Blob does before diving into the wizard. Current app jumps straight to Step 1 with no context. | LOW | Hero section above the wizard: app name, one-sentence value prop ("Generate rclone configs and deployment scripts for Windows endpoints"), 3-4 feature bullets (client-side only, 7 backends, Intune + RMM scripts), and a "Get Started" button that scrolls to or reveals the wizard. Collapses/hides once wizard is started. |
|
|
| **Animated step transitions** | Smooth transitions between wizard steps make the app feel responsive and polished rather than jarring page swaps. | LOW | CSS-only fade or slide transition on step change. Use `opacity` + `transform: translateX()` with 200ms ease. Keep it subtle -- this is a productivity tool, not a marketing site. Respect `prefers-reduced-motion`. |
|
|
| **Contextual help popovers (upgraded)** | Current tooltip toggle (click to show/hide inline text) works but is basic. MD3-style popovers with arrow indicators and rich content feel more professional. | MEDIUM | Replace inline toggle with a proper popover component: positioned above/below the trigger, with arrow, dismissed on outside click or Escape. Still click-triggered (not hover -- touch devices need click). Consider using Floating UI (lightweight, ~3KB) for positioning math. |
|
|
| **Remote name field clarity** | The "Remote name" field confuses users who do not know rclone conventions. Needs prominent explanation, examples, and format hint. | LOW | Add: placeholder "e.g., corp-backup", help text explaining "This name identifies the storage target in rclone commands and scripts", and an inline example showing how it appears in the generated config `[corp-backup]`. Already partially addressed in v1.1 tooltips; needs more prominent treatment. |
|
|
| **MD3 select/dropdown styling** | Native `<select>` elements look different on every OS and cannot be themed. Breaks the visual consistency of MD3 forms. | HIGH | Custom dropdown component matching MD3 outlined field style. Must handle keyboard navigation, ARIA `listbox` role, focus management. Significantly more complex than native select. Consider whether the 2-3 selects in the app justify the effort. Alternative: style the surrounding label/container as MD3 and accept native select rendering. |
|
|
| **Code block syntax highlighting (review step)** | Output blocks (rclone.conf, PowerShell scripts) currently render as plain `<pre>` text. Syntax highlighting adds professionalism and readability. | MEDIUM | Use a lightweight highlighter like Prism.js or highlight.js (INI + PowerShell grammars only -- tree-shake aggressively). Alternatively, minimal hand-rolled highlighting for INI format (`[section]` headers in primary color, `key = value` with key bold). Dark mode must invert colors. |
|
|
| **Smooth scroll-to-error on validation failure** | When a user clicks Next with invalid fields, scrolling to the first error field reduces confusion on longer forms (RemoteConfigStep with many fields). | LOW | On form submit failure, call `element.scrollIntoView({ behavior: 'smooth', block: 'center' })` on the first errored field. Minor polish, large UX impact on mobile where fields extend below fold. |
|
|
|
|
### Anti-Features (Commonly Requested, Often Problematic)
|
|
|
|
Features that seem good for UI polish but create problems.
|
|
|
|
| Feature | Why Requested | Why Problematic | Alternative |
|
|
|---------|---------------|-----------------|-------------|
|
|
| **Full MUI or Material Tailwind component library** | "Just use MUI for MD3" -- seems like it would save time | Massive bundle size increase (MUI is ~300KB+ gzipped). Overrides existing Tailwind approach. Migration tax is high. Most MUI components are unnecessary for a 4-step wizard with ~15 form fields. Creates a dependency on MUI's theming system instead of owning your tokens. | Build a thin MD3 design token layer in CSS custom properties + Tailwind utilities. Create 4-5 custom components (TextField, Button, Card, StepIndicator, Toggle). Total code is smaller than MUI's tree-shaken output for the same components. |
|
|
| **Animated wizard with page-per-step routing** | "Each step should be its own route for bookmarkability" | Adds React Router dependency. Wizard state is ephemeral (credentials in memory) -- refreshing a step would lose context. Back/forward browser buttons would conflict with wizard Back/Next. Bookmarking a credential-entry step is a security anti-pattern. | Keep single-page wizard with in-memory state. Step indicator serves as navigation. No routing needed. |
|
|
| **Glassmorphism / neomorphism / heavy visual effects** | "Modern UI trends" | These effects are CPU-intensive (backdrop-blur), have accessibility issues (low contrast), and will look dated within a year. IT admins want clarity, not visual flair. | MD3 tonal elevation (surface tint) provides depth without heavy effects. Clean, readable, professional. |
|
|
| **Custom-styled native checkboxes and radios** | "The DeploymentStep checkboxes look plain" | Custom checkbox/radio styling requires hiding the native element and rebuilding focus, checked, indeterminate, and disabled states. High effort for a few toggles. Touch target issues. | Use MD3-inspired wrapper: larger touch target (48px), visible label, proper spacing. Keep native input for accessibility. Style the surrounding container instead. |
|
|
| **Toast notifications for copy-to-clipboard** | "Show a toast when text is copied" | Requires a toast/snackbar system with portal, z-index management, animation, and auto-dismiss timer -- infrastructure overhead for a single use case. | Inline feedback: change the copy button text/icon to "Copied!" for 2 seconds, then revert. Zero infrastructure needed. Already understood by users. |
|
|
| **Theme with arbitrary user-picked hex color** | "Let users enter any hex color" | Arbitrary colors break accessibility (contrast ratios). A random bright yellow as primary makes error states invisible, text unreadable. Generating a full tonal palette from an arbitrary source requires the `@material/material-color-utilities` library (~15KB). | Offer 5-8 curated presets that have been verified for contrast compliance in both light and dark modes. Covers 95% of personalization desire with zero accessibility risk. |
|
|
|
|
## Feature Dependencies
|
|
|
|
```
|
|
Color Token System (CSS custom properties)
|
|
|-- required by --> Dark Mode (tokens swap values per theme)
|
|
|-- required by --> Accent Colors (tokens swap primary hue)
|
|
|-- required by --> MD3 Text Fields (reference token colors)
|
|
|-- required by --> MD3 Buttons (reference token colors)
|
|
|-- required by --> MD3 Cards (reference token colors + elevation tint)
|
|
|-- required by --> Step Indicator (reference token colors)
|
|
|-- required by --> Error States (reference error token)
|
|
|
|
Dark Mode
|
|
|-- requires --> Color Token System
|
|
|-- requires --> localStorage persistence (theme choice)
|
|
|-- enhances --> Accent Colors (must work in both light and dark)
|
|
|
|
Accent Colors
|
|
|-- requires --> Color Token System
|
|
|-- requires --> Curated palette presets (per-accent token sets)
|
|
|
|
Step Indicator (MD3)
|
|
|-- requires --> Color Token System
|
|
|-- independent of --> other component styling
|
|
|
|
App Intro Section
|
|
|-- independent of --> all styling work (content-only)
|
|
|-- enhances --> first-time experience
|
|
|
|
Step Descriptions
|
|
|-- independent of --> all styling work (content-only)
|
|
|
|
Remote Name Clarity
|
|
|-- independent of --> MD3 styling (content improvement)
|
|
|
|
Responsive Layout
|
|
|-- independent of --> color tokens (Tailwind breakpoints)
|
|
|-- should follow --> MD3 component styling (size tokens align)
|
|
|
|
Animated Transitions
|
|
|-- requires --> Step rendering structure (already exists)
|
|
|-- should follow --> MD3 component styling (transition consistent)
|
|
```
|
|
|
|
### Dependency Notes
|
|
|
|
- **Color Token System is the foundation**: Every visual component depends on it. Must be implemented first. Without tokens, each component hardcodes colors and dark mode becomes a per-component rewrite.
|
|
- **Dark Mode requires tokens but tokens do not require dark mode**: Tokens can ship first with light-only, then dark mode adds a second set of token values.
|
|
- **Accent Colors layer on top of both**: Accent colors multiply the token sets (N accents x 2 themes = 2N token sets). Implement after dark mode is stable.
|
|
- **Content improvements (intro, descriptions, remote name) are independent**: Can be done in any order, in parallel with styling work.
|
|
- **Step Indicator is visually complex but logically independent**: Can be rebuilt without affecting other components.
|
|
|
|
## MVP Definition
|
|
|
|
### Launch With (v1.2 Core)
|
|
|
|
Minimum set to achieve "polished, self-explanatory experience" goal.
|
|
|
|
- [ ] **Color token system** -- CSS custom properties for all MD3 color roles, referenced by all components. This is the enabler for everything else.
|
|
- [ ] **MD3 text fields (outlined)** -- Floating labels, proper focus/error states. Applied to FieldRenderer and BackendSelectionStep remote name input.
|
|
- [ ] **MD3 button hierarchy** -- Filled primary, outlined secondary, text tertiary. Applied to all wizard navigation and download buttons.
|
|
- [ ] **MD3 card components** -- Elevation via surface tint. Applied to BackendCard and OutputBlock.
|
|
- [ ] **MD3 step indicator** -- Numbered circles with connecting lines, completed/active/future states.
|
|
- [ ] **Dark mode toggle** -- System/Light/Dark with localStorage persistence.
|
|
- [ ] **App intro section** -- Hero explaining what Ready2Blob is, with Get Started CTA.
|
|
- [ ] **Step-level descriptions** -- Brief explanation text on each wizard step.
|
|
- [ ] **Remote name field clarity** -- Prominent explanation, examples, format hint.
|
|
- [ ] **Responsive layout** -- Mobile-friendly grid, collapsible step indicator, full-width buttons on small screens.
|
|
- [ ] **Accessible focus states** -- Visible focus-visible outlines on all interactive elements.
|
|
- [ ] **FieldRenderer aria consistency fix** -- Existing tech debt from v1.1.
|
|
- [ ] **StepIndicator inline style migration** -- Replace inline styles with Tailwind classes (existing tech debt).
|
|
|
|
### Add After Validation (v1.2.x)
|
|
|
|
Features to add once the core polish is working and tested.
|
|
|
|
- [ ] **Accent color selector** -- 5-8 preset colors, persistent. Add after token system and dark mode are stable.
|
|
- [ ] **Animated step transitions** -- CSS fade/slide on step change. Add after step rendering is finalized.
|
|
- [ ] **Contextual help popovers (upgraded)** -- Replace inline tooltip toggles with positioned popovers. Add after MD3 component styling is settled.
|
|
- [ ] **Scroll-to-error on validation failure** -- Minor polish, add when form field styling is complete.
|
|
|
|
### Future Consideration (v2+)
|
|
|
|
Features to defer until after this milestone.
|
|
|
|
- [ ] **Custom MD3 select/dropdown** -- High complexity for 2-3 selects in the app. Native select with MD3-styled container is sufficient for v1.2.
|
|
- [ ] **Code syntax highlighting** -- Nice but not essential. Plain monospace output blocks are standard for config/script tools.
|
|
- [ ] **Arbitrary user hex color theming** -- Requires color utility library and contrast validation. Curated presets suffice.
|
|
|
|
## Feature Prioritization Matrix
|
|
|
|
| Feature | User Value | Implementation Cost | Priority |
|
|
|---------|------------|---------------------|----------|
|
|
| Color token system | HIGH | MEDIUM | P1 |
|
|
| MD3 text fields | HIGH | MEDIUM | P1 |
|
|
| MD3 buttons | HIGH | LOW | P1 |
|
|
| MD3 cards | MEDIUM | LOW | P1 |
|
|
| Dark mode | HIGH | MEDIUM | P1 |
|
|
| Step indicator (MD3) | HIGH | MEDIUM | P1 |
|
|
| App intro section | HIGH | LOW | P1 |
|
|
| Step descriptions | MEDIUM | LOW | P1 |
|
|
| Remote name clarity | MEDIUM | LOW | P1 |
|
|
| Responsive layout | HIGH | MEDIUM | P1 |
|
|
| Focus states (a11y) | MEDIUM | LOW | P1 |
|
|
| FieldRenderer aria fix | LOW | LOW | P1 (tech debt) |
|
|
| StepIndicator style migration | LOW | LOW | P1 (tech debt) |
|
|
| Accent color selector | MEDIUM | MEDIUM | P2 |
|
|
| Step transitions | LOW | LOW | P2 |
|
|
| Upgraded popovers | LOW | MEDIUM | P2 |
|
|
| Scroll-to-error | LOW | LOW | P2 |
|
|
| Custom select/dropdown | LOW | HIGH | P3 |
|
|
| Syntax highlighting | LOW | MEDIUM | P3 |
|
|
|
|
**Priority key:**
|
|
- P1: Must have for v1.2 launch -- achieves the "polished" goal
|
|
- P2: Should have, add when core P1 features are stable
|
|
- P3: Nice to have, defer unless time permits
|
|
|
|
## What Makes a Config Wizard Feel Professional vs Bare
|
|
|
|
Based on analysis of the current Ready2Blob UI against MD3 patterns and wizard UX best practices:
|
|
|
|
**Current state (bare):**
|
|
- Raw HTML inputs with no visual framework
|
|
- Inline styles on StepIndicator
|
|
- Inconsistent color usage (hardcoded Tailwind values)
|
|
- No dark mode
|
|
- No intro explaining the tool
|
|
- Step headings with no descriptions
|
|
- No visual hierarchy in buttons
|
|
- Backend cards have basic border styling only
|
|
- Output blocks are unstyled pre/textarea elements
|
|
|
|
**Professional target:**
|
|
1. **Visual consistency** -- Every element follows the same design language (spacing, color, shape, elevation)
|
|
2. **Clear information hierarchy** -- Primary actions are obvious, secondary actions are subdued, labels guide the eye
|
|
3. **Contextual guidance** -- The UI explains itself: what each step does, what each field means, what happens next
|
|
4. **Responsive confidence** -- Works smoothly on any screen size without horizontal scrolling or cramped layouts
|
|
5. **Polish details** -- Smooth transitions, proper loading states, visible focus, no flicker on theme change
|
|
6. **Trust signals** -- Professional appearance, security notices styled prominently, client-side-only badge
|
|
|
|
The gap between bare and professional is not one feature -- it is the cumulative effect of the token system enabling consistent styling across every component, combined with content improvements (intro, descriptions, help text) that make the wizard self-explanatory.
|
|
|
|
## Sources
|
|
|
|
- [Material Design 3 Text Fields Guidelines](https://m3.material.io/components/text-fields/guidelines) -- MD3 text field patterns (filled vs outlined, supporting text, error states)
|
|
- [Material Design 3 Components](https://m3.material.io/components) -- Full component catalog
|
|
- [Material Design 3 Elevation](https://m3.material.io/styles/elevation/applying-elevation) -- Surface tint vs shadow, elevation levels 0-5
|
|
- [Material Design 3 Color Roles](https://m3.material.io/styles/color/roles) -- Primary, secondary, tertiary, surface, error color roles
|
|
- [Material Design 3 Dynamic Color](https://m3.material.io/styles/color/dynamic/user-generated-source) -- User-generated source color for theming
|
|
- [MD3 box-shadow CSS values](https://studioncreations.com/blog/material-design-3-box-shadow-css-values/) -- CSS elevation implementation (MEDIUM confidence)
|
|
- [Beyond the Progress Bar: Stepper UI Design](https://medium.com/@david.pham_1649/beyond-the-progress-bar-the-art-of-stepper-ui-design-cfa270a8e862) -- Stepper patterns and best practices
|
|
- [Wizard Design Pattern (UX Planet)](https://uxplanet.org/wizard-design-pattern-8c86e14f2a38) -- Wizard UX fundamentals
|
|
- [Wizards: Definition and Design Recommendations (NN/g)](https://www.nngroup.com/articles/wizards/) -- Nielsen Norman Group wizard guidelines
|
|
- [Dark Mode Toggle and prefers-color-scheme](https://dev.to/abbeyperini/dark-mode-toggle-and-prefers-color-scheme-4f3m) -- Implementation pattern for system/manual toggle
|
|
- [The Ultimate Guide to Coding Dark Mode 2025](https://devieffe.substack.com/p/the-ultimate-guide-to-coding-dark-mode-layouts-in-2025) -- CSS custom properties + data-theme approach
|
|
- [Design Tokens and Theming: Scalable UI Systems 2025](https://materialui.co/blog/design-tokens-and-theming-scalable-ui-2025) -- Token architecture patterns
|
|
- [Tailwind CSS Responsive Design](https://tailwindcss.com/docs/responsive-design) -- Mobile-first breakpoint system
|
|
- [MD3 Theming Tokens (seenode)](https://seenode.com/blog/what-is-material-3-and-why-it-matters-in-2025) -- 141 system tokens, token hierarchy
|
|
- [Input Field Design Best Practices 2025](https://fireart.studio/blog/input-field-design-best-practice/) -- Floating labels, error patterns, accessibility
|
|
|
|
---
|
|
*Feature research for: Ready2Blob v1.2 UI Polish*
|
|
*Researched: 2026-03-31*
|