mirror of
https://github.com/jhbruhn/respira.git
synced 2026-01-27 02:13:41 +00:00
doc: Add Readme
This commit is contained in:
parent
254b09271e
commit
5f46f67cb4
10 changed files with 81 additions and 2941 deletions
81
README.md
Normal file
81
README.md
Normal file
|
|
@ -0,0 +1,81 @@
|
|||
# Respira
|
||||
|
||||
Respira is an pattern transmission and embroidery monitoring application for the Brother PP-1 SKiTCH embroidery machine.
|
||||
It replaces the Artspira app and allows the user to transmit .PES patterns directly from a computer without having to go through the app.
|
||||
This allows the user to operate the embroidery machine fully offline and from the comfortable screen of a computer.
|
||||
|
||||
|
||||
|
||||
## Installation
|
||||
|
||||
The latest release of Respira can be downloaded [here](https://github.com/jhbruhn/respira/releases/latest). Choose the appropriate installer for your Operating System.
|
||||
Be aware that the macOS release has difficulties because it is neither signed nor notarized by Apple[^1].
|
||||
The application will offer updates automatically, at least on Windows.
|
||||
On macOS it does not because of the aforementioned issue.
|
||||
|
||||
If you are using Chrome, Edge or another browser with WebBluetooth capabilities, you can also use it directly in the browser: https://jhbruhn.github.io/respira
|
||||
|
||||
## Usage
|
||||
|
||||
After first starting, you are prompted to connect to your machine.
|
||||
Respira will only show Bluetooth devices which are Brother PP-1 machines.
|
||||
Respira has a handy step-guide at the top.
|
||||
Clicking on the current step will show hints what needs to be done in the current step.
|
||||
|
||||
### Pairing
|
||||
|
||||
If you never used Respira with your machine before, you will have to pair your machine with your computer first.
|
||||
To do so, head to your operating systems Bluetooth settings, long-press the Bluetooth-Button on your Brother PP-1 until the LED changes its blinking pattern or there is a beep, and then pair your computer with the machine from your operating systems Bluetooth settings.
|
||||
Only after this pairing has been done, Respira will be able to successfully connect with your machine.
|
||||
Otherwise, the connection will fail silently.
|
||||
|
||||
### Homing
|
||||
|
||||
After startup, the machine has to home itself.
|
||||
Remove the hoop and press the accept button.
|
||||
The machine will move a bit.
|
||||
Afterwards, you can reinsert the hoop.
|
||||
|
||||
### Upload Pattern
|
||||
|
||||
To import and prepare a pattern, click the _Choose PES File_ button and import a PES embroidery pattern.
|
||||
Before uploading it, you can move the pattern in the preview window so that it is embroidered at the correct position.
|
||||
Upload the pattern using the Upload Pattern button.
|
||||
|
||||
### Embroidering
|
||||
|
||||
After the pattern has been uploaded, you can start embroidering.
|
||||
First do a mask trace so that the machine can check whether the whole embroidery area is accessible.
|
||||
Press the _Start Mask Trace_ button, then press the _Accept_ button on the machine.
|
||||
When the mask trace was successful, you can start sewing by pressing the _Start Sewing_ button, and then pressing the _Start/Pause_ button on the machine.
|
||||
|
||||
While the machine is embroidering, watch your sewing progress using the live preview in the Pattern Preview pane and know which color to change to from the Color Block list in the Sewing Progress pane.
|
||||
|
||||
After the embroidery is done, remove your fabric from the hoop and press the _Accept_ button on the machine to continue with a new job, or repeat the current job by pressing the _Start/Pause_ button again.
|
||||
|
||||
## Pattern Preparation
|
||||
|
||||
Embroidery software seems to be a niche product and thus is quite expensive.
|
||||
But fear not because the great people of [Ink/Stitch built and Inkscape extension](https://inkstitch.org/) which allows you to create embroidery patterns with Free and Open Source software.
|
||||
How great is that?
|
||||
I think it's great.
|
||||
All my tests were done with PES patterns exported from Ink/Stitch.
|
||||
In fact, Respira is using their pystitch library to import PES patterns.
|
||||
|
||||
But PES patterns from other software or downloaded from the internet should work as well.
|
||||
|
||||
## Vibe Code Warning
|
||||
|
||||
For reasons of fairness and possibly also as a warning, be aware that 99% of the code has been written using LLMs, specifically Claude Code.
|
||||
|
||||
That does not mean that the code is untested, bad or dysfunctional.
|
||||
In fact, LLMs were a great tool for reverse engineering the Bluetooth Protocol and pattern format the Brother PP-1 uses to communicate with Brothers App.
|
||||
|
||||
This project wouldn't have happened without the existence of LLMs.
|
||||
So, while LLMs are still being heavily oversold and the circulary economy of the big AI companies is not exactly a healthy market IMO, they do still offer _some_ benefits.
|
||||
|
||||
## License
|
||||
|
||||
See `LICENSE.md`.
|
||||
|
||||
[^1]: To me this is frankly insane. It effectively makes a computer running macOS not a computer that can run general compute anymore, but only applications that were explicitly allowed by Apple. Not only does signing and notarizing the application require the developer to pay a yearly 99€ fee, but it also strips every Apple computer of its generic compute capabilities, unless you know how to circumvent the security measures.
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
# Placeholder for build resources
|
||||
# Add your icon files here:
|
||||
# - icon.ico (Windows, 256x256)
|
||||
# - icon.icns (macOS)
|
||||
# - icon.png (Linux, 512x512)
|
||||
|
|
@ -1,504 +0,0 @@
|
|||
# Quick UI Improvements - Action Guide
|
||||
|
||||
This is a condensed, actionable guide for immediately improving the SKiTCH Controller UI. For detailed analysis, see `UI_DESIGN_ANALYSIS.md`.
|
||||
|
||||
---
|
||||
|
||||
## Priority 1: Color System (30 minutes)
|
||||
|
||||
### Create Design Tokens File
|
||||
|
||||
**File: `src/styles/design-tokens.css`**
|
||||
|
||||
```css
|
||||
@theme {
|
||||
/* Primary - Blue */
|
||||
--color-primary: #2563eb;
|
||||
--color-primary-light: #3b82f6;
|
||||
--color-primary-dark: #1d4ed8;
|
||||
|
||||
/* Secondary - Slate */
|
||||
--color-secondary: #64748b;
|
||||
--color-secondary-light: #94a3b8;
|
||||
|
||||
/* Success - Green */
|
||||
--color-success: #16a34a;
|
||||
--color-success-bg: #dcfce7;
|
||||
|
||||
/* Warning - Amber */
|
||||
--color-warning: #d97706;
|
||||
--color-warning-bg: #fef3c7;
|
||||
|
||||
/* Danger - Red */
|
||||
--color-danger: #dc2626;
|
||||
--color-danger-bg: #fee2e2;
|
||||
|
||||
/* Info - Cyan */
|
||||
--color-info: #0891b2;
|
||||
--color-info-bg: #cffafe;
|
||||
|
||||
/* Neutral */
|
||||
--color-neutral-50: #f9fafb;
|
||||
--color-neutral-100: #f3f4f6;
|
||||
--color-neutral-200: #e5e7eb;
|
||||
--color-neutral-300: #d1d5db;
|
||||
--color-neutral-600: #4b5563;
|
||||
--color-neutral-900: #111827;
|
||||
}
|
||||
```
|
||||
|
||||
Import in `App.css`:
|
||||
```css
|
||||
@import "tailwindcss";
|
||||
@import "./styles/design-tokens.css";
|
||||
```
|
||||
|
||||
### Find & Replace Color Classes
|
||||
|
||||
**Throughout all components:**
|
||||
|
||||
```tsx
|
||||
// Primary action buttons
|
||||
bg-blue-600 → bg-primary
|
||||
bg-blue-700 → bg-primary-dark
|
||||
hover:bg-blue-700 → hover:bg-primary-light
|
||||
|
||||
// Text colors
|
||||
text-blue-900 → text-primary-dark
|
||||
text-blue-800 → text-primary
|
||||
text-gray-600 → text-neutral-600
|
||||
text-gray-900 → text-neutral-900
|
||||
|
||||
// Backgrounds
|
||||
bg-gray-50 → bg-neutral-50
|
||||
bg-gray-100 → bg-neutral-100
|
||||
|
||||
// Borders
|
||||
border-gray-300 → border-neutral-300
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Priority 2: Button States (20 minutes)
|
||||
|
||||
### Standard Button Classes
|
||||
|
||||
**Replace all button classes with these variants:**
|
||||
|
||||
```tsx
|
||||
// PRIMARY BUTTON (Connect, Upload, Start Sewing)
|
||||
className="
|
||||
px-6 py-3
|
||||
bg-primary text-white
|
||||
rounded-lg font-semibold text-sm
|
||||
shadow-sm
|
||||
hover:bg-primary-light hover:shadow-md
|
||||
active:bg-primary-dark active:scale-[0.98]
|
||||
focus:outline-none focus:ring-2 focus:ring-primary focus:ring-offset-2
|
||||
disabled:bg-neutral-300 disabled:text-neutral-500 disabled:cursor-not-allowed
|
||||
transition-all duration-150
|
||||
cursor-pointer
|
||||
"
|
||||
|
||||
// SECONDARY BUTTON (Mask Trace)
|
||||
className="
|
||||
px-6 py-3
|
||||
bg-white text-neutral-700 border border-neutral-300
|
||||
rounded-lg font-semibold text-sm
|
||||
shadow-sm
|
||||
hover:bg-neutral-50 hover:border-neutral-400
|
||||
active:bg-neutral-100 active:scale-[0.98]
|
||||
focus:outline-none focus:ring-2 focus:ring-neutral-400 focus:ring-offset-2
|
||||
disabled:bg-neutral-50 disabled:text-neutral-400 disabled:cursor-not-allowed
|
||||
transition-all duration-150
|
||||
cursor-pointer
|
||||
"
|
||||
|
||||
// DANGER BUTTON (Delete, Disconnect)
|
||||
className="
|
||||
px-6 py-3
|
||||
bg-danger text-white
|
||||
rounded-lg font-semibold text-sm
|
||||
shadow-sm
|
||||
hover:bg-red-700 hover:shadow-md
|
||||
active:bg-red-800 active:scale-[0.98]
|
||||
focus:outline-none focus:ring-2 focus:ring-danger focus:ring-offset-2
|
||||
disabled:bg-neutral-300 disabled:text-neutral-500 disabled:cursor-not-allowed
|
||||
transition-all duration-150
|
||||
cursor-pointer
|
||||
"
|
||||
|
||||
// ICON BUTTON (Zoom controls)
|
||||
className="
|
||||
w-10 h-10
|
||||
flex items-center justify-center
|
||||
bg-white border border-neutral-300
|
||||
rounded-lg
|
||||
text-neutral-700
|
||||
hover:bg-primary hover:text-white hover:border-primary
|
||||
active:bg-primary-dark active:scale-95
|
||||
focus:outline-none focus:ring-2 focus:ring-primary focus:ring-offset-2
|
||||
transition-all duration-150
|
||||
cursor-pointer
|
||||
"
|
||||
```
|
||||
|
||||
**KEY CHANGES:**
|
||||
- Remove `disabled:grayscale-[0.3]` everywhere
|
||||
- Add `active:scale-[0.98]` for press feedback
|
||||
- Add `focus:ring-2` for accessibility
|
||||
- Use semantic color tokens
|
||||
|
||||
---
|
||||
|
||||
## Priority 3: Typography Scale (15 minutes)
|
||||
|
||||
### Standard Text Classes
|
||||
|
||||
**Apply throughout components:**
|
||||
|
||||
```tsx
|
||||
// Headings
|
||||
h1: "text-2xl font-bold text-neutral-900" // Main title
|
||||
h2: "text-xl font-semibold text-neutral-900" // Section titles
|
||||
h3: "text-base font-semibold text-neutral-900" // Subsections
|
||||
h4: "text-sm font-semibold text-neutral-700" // Small headings
|
||||
|
||||
// Body text
|
||||
"text-base text-neutral-900" // Large body
|
||||
"text-sm text-neutral-700" // Regular body
|
||||
"text-xs text-neutral-600" // Small text
|
||||
"text-[11px] text-neutral-500" // Caption (minimal use)
|
||||
```
|
||||
|
||||
### Quick Fixes
|
||||
|
||||
**WorkflowStepper.tsx:**
|
||||
```tsx
|
||||
// Line 102: Make step labels larger
|
||||
<div className="text-sm font-semibold"> {/* was text-xs */}
|
||||
```
|
||||
|
||||
**ProgressMonitor.tsx:**
|
||||
```tsx
|
||||
// Line 169: Larger thread labels
|
||||
<span className="text-sm flex-1 font-semibold"> {/* was unlabeled size */}
|
||||
|
||||
// Line 179: More readable stitch counts
|
||||
<span className="text-sm text-neutral-600 font-medium"> {/* was text-xs */}
|
||||
```
|
||||
|
||||
**PatternCanvas.tsx:**
|
||||
```tsx
|
||||
// Line 278: Clearer thread legend text
|
||||
<span className="text-sm text-neutral-900">Thread {index + 1}</span> {/* was text-xs */}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Priority 4: Spacing Consistency (15 minutes)
|
||||
|
||||
### Standard Card Padding
|
||||
|
||||
**Apply to all card components:**
|
||||
|
||||
```tsx
|
||||
// Standard card
|
||||
<div className="bg-white p-6 rounded-lg shadow-md border border-neutral-100">
|
||||
|
||||
// Compact card (ProgressMonitor)
|
||||
<div className="bg-white p-5 rounded-lg shadow-md border border-neutral-100">
|
||||
```
|
||||
|
||||
### Standard Section Spacing
|
||||
|
||||
```tsx
|
||||
// Between major sections
|
||||
<div className="flex flex-col gap-6">
|
||||
|
||||
// Within sections
|
||||
<div className="space-y-4">
|
||||
|
||||
// Within subsections
|
||||
<div className="space-y-3">
|
||||
|
||||
// Tight grouping
|
||||
<div className="space-y-2">
|
||||
```
|
||||
|
||||
### Quick Fixes
|
||||
|
||||
**App.tsx:**
|
||||
```tsx
|
||||
// Line 126: Increase main grid gap
|
||||
<div className="grid grid-cols-1 lg:grid-cols-[400px_1fr] gap-8"> {/* was gap-6 */}
|
||||
|
||||
// Line 128: Standard spacing in left column
|
||||
<div className="flex flex-col gap-6">
|
||||
```
|
||||
|
||||
**ProgressMonitor.tsx:**
|
||||
```tsx
|
||||
// Line 116: Better grid gap
|
||||
<div className="grid grid-cols-1 md:grid-cols-2 gap-6"> {/* was gap-4 */}
|
||||
|
||||
// Line 143: Better color block spacing
|
||||
<div className="flex flex-col gap-3"> {/* was gap-2 */}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Priority 5: Visual Hierarchy (20 minutes)
|
||||
|
||||
### Section Headers
|
||||
|
||||
**Replace all section headers:**
|
||||
|
||||
```tsx
|
||||
// OLD
|
||||
<h2 className="text-xl font-semibold mb-4 pb-2 border-b-2 border-gray-300">
|
||||
|
||||
// NEW
|
||||
<div className="mb-5 pb-3 border-b border-neutral-200">
|
||||
<h2 className="text-xl font-bold text-neutral-900">Pattern Preview</h2>
|
||||
</div>
|
||||
```
|
||||
|
||||
### Color Block Enhancement
|
||||
|
||||
**ProgressMonitor.tsx - Lines 157-191:**
|
||||
|
||||
```tsx
|
||||
<div className={`
|
||||
p-3 rounded-lg border-2 transition-all duration-200
|
||||
${isCompleted ? 'border-success bg-success-bg/50' : ''}
|
||||
${isCurrent ? 'border-primary bg-primary/5 shadow-lg shadow-primary/10 ring-2 ring-primary/20' : ''}
|
||||
${!isCompleted && !isCurrent ? 'border-neutral-200 bg-neutral-50 opacity-70' : ''}
|
||||
`}>
|
||||
<div className="flex items-center gap-3">
|
||||
<div
|
||||
className="w-6 h-6 rounded-md border-2 border-white shadow-md ring-1 ring-neutral-300 flex-shrink-0"
|
||||
style={{ backgroundColor: block.threadHex }}
|
||||
/>
|
||||
<span className="font-semibold text-sm flex-1">
|
||||
Thread {block.colorIndex + 1}
|
||||
</span>
|
||||
{/* Status icons */}
|
||||
{isCompleted && <CheckCircleIcon className="w-5 h-5 text-success" />}
|
||||
{isCurrent && <ArrowRightIcon className="w-5 h-5 text-primary" />}
|
||||
{!isCompleted && !isCurrent && <CircleStackIcon className="w-5 h-5 text-neutral-400" />}
|
||||
<span className="text-sm text-neutral-600 font-medium">
|
||||
{block.stitchCount.toLocaleString()}
|
||||
</span>
|
||||
</div>
|
||||
{/* Progress bar */}
|
||||
{isCurrent && (
|
||||
<div className="mt-2.5 h-1.5 bg-neutral-200 rounded-full overflow-hidden">
|
||||
<div
|
||||
className="h-full bg-primary transition-all duration-300"
|
||||
style={{ width: `${blockProgress}%` }}
|
||||
/>
|
||||
</div>
|
||||
)}
|
||||
</div>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Priority 6: Accessibility Quick Wins (15 minutes)
|
||||
|
||||
### Add ARIA Labels to Icon Buttons
|
||||
|
||||
**PatternCanvas.tsx - Zoom controls:**
|
||||
|
||||
```tsx
|
||||
<button
|
||||
onClick={handleZoomIn}
|
||||
aria-label="Zoom in on pattern preview"
|
||||
title="Zoom In"
|
||||
className="..."
|
||||
>
|
||||
<PlusIcon className="w-5 h-5" />
|
||||
</button>
|
||||
|
||||
<button
|
||||
onClick={handleZoomOut}
|
||||
aria-label="Zoom out from pattern preview"
|
||||
title="Zoom Out"
|
||||
className="..."
|
||||
>
|
||||
<MinusIcon className="w-5 h-5" />
|
||||
</button>
|
||||
|
||||
<button
|
||||
onClick={handleZoomReset}
|
||||
aria-label="Reset zoom to fit pattern"
|
||||
title="Reset Zoom"
|
||||
className="..."
|
||||
>
|
||||
<ArrowPathIcon className="w-5 h-5" />
|
||||
</button>
|
||||
```
|
||||
|
||||
### Increase Touch Targets
|
||||
|
||||
**All icon buttons:**
|
||||
|
||||
```tsx
|
||||
// Change from w-8 h-8 to w-10 h-10
|
||||
<button className="w-10 h-10 ..."> {/* was w-8 h-8 */}
|
||||
```
|
||||
|
||||
### Add Progress Bar ARIA
|
||||
|
||||
**ProgressMonitor.tsx - Line 207:**
|
||||
|
||||
```tsx
|
||||
<div
|
||||
className="h-full bg-gradient-to-r from-primary to-primary-light transition-all duration-300"
|
||||
style={{ width: `${progressPercent}%` }}
|
||||
role="progressbar"
|
||||
aria-valuenow={progressPercent}
|
||||
aria-valuemin={0}
|
||||
aria-valuemax={100}
|
||||
aria-label="Sewing progress"
|
||||
/>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Priority 7: Polish Details (20 minutes)
|
||||
|
||||
### Better Progress Bar Styling
|
||||
|
||||
**Both upload and sewing progress bars:**
|
||||
|
||||
```tsx
|
||||
<div className="h-2.5 bg-neutral-200 rounded-full overflow-hidden shadow-inner">
|
||||
<div
|
||||
className="h-full bg-gradient-to-r from-primary to-primary-light transition-all duration-300 ease-out relative overflow-hidden"
|
||||
style={{ width: `${progress}%` }}
|
||||
>
|
||||
{/* Shimmer effect */}
|
||||
<div className="absolute inset-0 bg-gradient-to-r from-transparent via-white/30 to-transparent animate-[shimmer_2s_infinite]" />
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
### Enhanced Status Badges
|
||||
|
||||
**MachineConnection.tsx - Line 116:**
|
||||
|
||||
```tsx
|
||||
<span className={`
|
||||
inline-flex items-center gap-2
|
||||
px-3.5 py-2
|
||||
rounded-lg
|
||||
font-semibold text-sm
|
||||
border border-current/20
|
||||
${statusBadgeColors[stateVisual.color]}
|
||||
`}>
|
||||
<span className="text-base leading-none">{stateVisual.icon}</span>
|
||||
<span>{machineStatusName}</span>
|
||||
</span>
|
||||
```
|
||||
|
||||
### Unified Canvas Overlays
|
||||
|
||||
**PatternCanvas.tsx - All overlays:**
|
||||
|
||||
```tsx
|
||||
// Use consistent overlay styling
|
||||
className="absolute ... bg-white/98 backdrop-blur-sm p-3 rounded-xl shadow-lg border border-neutral-200 z-10"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference: Common Patterns
|
||||
|
||||
### Card Component
|
||||
```tsx
|
||||
<div className="bg-white p-6 rounded-lg shadow-md border border-neutral-100">
|
||||
<div className="mb-5 pb-3 border-b border-neutral-200">
|
||||
<h2 className="text-xl font-bold text-neutral-900">Title</h2>
|
||||
</div>
|
||||
<div className="space-y-4">
|
||||
{/* Content */}
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
### Info Box / Alert
|
||||
```tsx
|
||||
<div className="bg-blue-50 border-l-4 border-blue-600 p-4 rounded-lg">
|
||||
<div className="flex items-start gap-3">
|
||||
<InformationCircleIcon className="w-6 h-6 text-blue-600 flex-shrink-0" />
|
||||
<div>
|
||||
<h4 className="font-semibold text-blue-900 mb-1">Title</h4>
|
||||
<p className="text-sm text-blue-800">Message</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
### Data Grid
|
||||
```tsx
|
||||
<div className="bg-neutral-50 p-4 rounded-lg border border-neutral-200 space-y-3">
|
||||
<div className="flex justify-between items-center">
|
||||
<span className="text-sm font-medium text-neutral-600">Label:</span>
|
||||
<span className="text-base font-bold text-neutral-900">Value</span>
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Testing Checklist
|
||||
|
||||
After making changes, verify:
|
||||
|
||||
- [ ] All buttons have visible hover states
|
||||
- [ ] All buttons have press feedback (scale on active)
|
||||
- [ ] All buttons have focus rings (test with Tab key)
|
||||
- [ ] All disabled buttons are clearly grayed out
|
||||
- [ ] Colors are consistent (no random blue-500, blue-600 mixing)
|
||||
- [ ] Text is readable (no tiny 10px text)
|
||||
- [ ] Touch targets are at least 44×44px
|
||||
- [ ] Section headers stand out clearly
|
||||
- [ ] Spacing feels consistent across components
|
||||
- [ ] Status colors match semantic meaning (green=success, red=danger, etc.)
|
||||
|
||||
---
|
||||
|
||||
## Estimated Time: 2.5 Hours Total
|
||||
|
||||
1. Color system setup: 30 min
|
||||
2. Button state updates: 20 min
|
||||
3. Typography fixes: 15 min
|
||||
4. Spacing consistency: 15 min
|
||||
5. Visual hierarchy: 20 min
|
||||
6. Accessibility: 15 min
|
||||
7. Polish details: 20 min
|
||||
8. Testing: 15 min
|
||||
|
||||
---
|
||||
|
||||
## Impact Summary
|
||||
|
||||
These changes will:
|
||||
- **Improve usability** - Clearer buttons, better hierarchy
|
||||
- **Enhance accessibility** - WCAG compliant, better focus states
|
||||
- **Create consistency** - Unified color system, spacing
|
||||
- **Polish appearance** - Professional, cohesive design
|
||||
- **Maintain compactness** - Still efficient for technical users
|
||||
|
||||
---
|
||||
|
||||
## Need More Details?
|
||||
|
||||
See `UI_DESIGN_ANALYSIS.md` for:
|
||||
- Detailed analysis of each component
|
||||
- Comprehensive accessibility guidelines
|
||||
- Advanced implementation recommendations
|
||||
- Full code examples
|
||||
- Design system specifications
|
||||
|
|
@ -1,196 +0,0 @@
|
|||
# Respira Typography System
|
||||
|
||||
## Current Problems
|
||||
❌ 12 different font sizes including arbitrary values (7px, 9px, 10px, 11px, 13px)
|
||||
❌ Inconsistent hierarchy - unclear when to use which size
|
||||
❌ Poor accessibility - text as small as 7px
|
||||
❌ Responsive scaling is inconsistent
|
||||
|
||||
## New Typography System (Tailwind Classes Only)
|
||||
|
||||
### **5-Level Hierarchy**
|
||||
|
||||
```
|
||||
Level Desktop (lg:) Mobile/Tablet Weight Usage
|
||||
─────────────────────────────────────────────────────────────────────────────────
|
||||
Display text-xl (20px) text-lg (18px) font-bold App title, page headers
|
||||
Heading text-lg (18px) text-base (16px) font-semibold Section titles, dialogs
|
||||
Subheading text-sm (14px) text-sm (14px) font-semibold Card titles
|
||||
Body text-sm (14px) text-sm (14px) font-medium Content, buttons
|
||||
Label text-xs (12px) text-xs (12px) font-medium Metadata, helpers, tags
|
||||
```
|
||||
|
||||
**Key Decisions:**
|
||||
- ✅ **No custom pixel sizes** - only Tailwind standards
|
||||
- ✅ **Minimum 12px** - text-xs (12px) is the smallest size (accessible)
|
||||
- ✅ **Body = text-sm** - 14px is optimal for reading and touch targets
|
||||
- ✅ **Consistent responsive** - most don't need breakpoints except Display/Heading
|
||||
|
||||
### **Font Weight System**
|
||||
```
|
||||
Display: font-bold (700) - Maximum emphasis
|
||||
Heading: font-semibold (600) - Section headers
|
||||
Subheading: font-semibold (600) - Card/component titles
|
||||
Body: font-medium (500) - Interactive elements (buttons)
|
||||
Body: font-normal (400) - Static text
|
||||
Label: font-medium (500) - Small but important
|
||||
Label: font-normal (400) - Decorative/secondary
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Component Mapping
|
||||
|
||||
### **App.tsx**
|
||||
| Element | Old | New |
|
||||
|---------|-----|-----|
|
||||
| "Respira" title | text-lg | text-xl lg:text-xl (Display) |
|
||||
| Serial number | text-sm | text-xs (Label) |
|
||||
| "Not Connected" | text-sm | text-xs (Label) |
|
||||
| Disconnect button | text-xs | text-sm (Body) |
|
||||
| Status badge | text-xs | text-xs (Label) |
|
||||
| Error message | text-sm | text-sm (Body) |
|
||||
| "Pattern Preview" h2 | text-xl | text-lg lg:text-lg (Heading) |
|
||||
| Empty state title | text-xl | text-lg (Heading) |
|
||||
| Empty state body | text-sm | text-sm (Body) |
|
||||
| Feature indicators | text-xs | text-xs (Label) |
|
||||
|
||||
### **FileUpload.tsx**
|
||||
| Element | Old | New |
|
||||
|---------|-----|-----|
|
||||
| "Pattern File" title | text-sm | text-sm font-semibold (Subheading) |
|
||||
| Filename | text-xs | text-xs (Label) |
|
||||
| Stats labels | text-xs | text-xs (Label) |
|
||||
| Button text | text-xs | text-sm (Body) |
|
||||
| "Colors:" label | text-xs | text-xs (Label) |
|
||||
| Error messages | text-xs | text-sm (Body) |
|
||||
| Upload progress | text-xs | text-xs (Label) |
|
||||
| **Remove:** text-[7px] badge → text-xs |
|
||||
|
||||
### **PatternCanvas.tsx**
|
||||
| Element | Old | New |
|
||||
|---------|-----|-----|
|
||||
| "Pattern Preview" | text-sm | text-sm font-semibold (Subheading) |
|
||||
| Dimensions | text-xs | text-xs (Label) |
|
||||
| "Colors" header | text-[10px] sm:text-xs | text-xs (Label) |
|
||||
| Color labels | text-[10px] sm:text-[11px] | text-xs (Label) |
|
||||
| Thread metadata | text-[9px] | text-xs (Label) |
|
||||
| "Pattern Position" | text-[10px] sm:text-[11px] | text-xs (Label) |
|
||||
| "LOCKED" badge | text-[9px] sm:text-[10px] | text-xs (Label) |
|
||||
| Coordinates (X/Y) | text-[11px] sm:text-[13px] | text-sm (Body) |
|
||||
| Help text | text-[9px] sm:text-[10px] | text-xs (Label) |
|
||||
| Zoom % | text-[11px] sm:text-[13px] | text-sm (Body) |
|
||||
|
||||
### **ProgressMonitor.tsx**
|
||||
| Element | Old | New |
|
||||
|---------|-----|-----|
|
||||
| "Progress" title | text-sm | text-sm font-semibold (Subheading) |
|
||||
| Block labels | text-xs | text-xs (Label) |
|
||||
| Stitch counts | text-xs | text-xs (Label) |
|
||||
| Button text | text-xs | text-sm (Body) |
|
||||
|
||||
### **WorkflowStepper.tsx**
|
||||
| Element | Old | New |
|
||||
|---------|-----|-----|
|
||||
| Step numbers | text-[10px] lg:text-xs | text-xs (Label) |
|
||||
| Step labels | text-[10px] lg:text-xs | text-xs (Label) |
|
||||
|
||||
### **NextStepGuide.tsx**
|
||||
| Element | Old | New |
|
||||
|---------|-----|-----|
|
||||
| Step titles | text-lg | text-lg sm:text-base (Heading) |
|
||||
| Instructions | text-sm | text-sm (Body) |
|
||||
| Error codes | text-xs | text-xs font-mono (Label) |
|
||||
|
||||
### **PatternSummaryCard.tsx**
|
||||
| Element | Old | New |
|
||||
|---------|-----|-----|
|
||||
| "Active Pattern" | text-sm | text-sm font-semibold (Subheading) |
|
||||
| Filename | text-xs | text-xs (Label) |
|
||||
| Stats | text-xs | text-xs (Label) |
|
||||
| Button text | text-xs | text-sm (Body) |
|
||||
| **Remove:** text-[7px] badge → text-xs |
|
||||
|
||||
### **MachineConnection.tsx**
|
||||
| Element | Old | New |
|
||||
|---------|-----|-----|
|
||||
| Card titles | text-sm | text-sm font-semibold (Subheading) |
|
||||
| Helper text | text-xs | text-xs (Label) |
|
||||
| Button text | text-xs | text-sm (Body) |
|
||||
| Error details | text-[10px] | text-xs (Label) |
|
||||
|
||||
### **ConfirmDialog.tsx**
|
||||
| Element | Old | New |
|
||||
|---------|-----|-----|
|
||||
| Dialog title | text-xl | text-lg (Heading) |
|
||||
| Button text | text-sm | text-sm (Body) |
|
||||
|
||||
### **BluetoothDevicePicker.tsx**
|
||||
| Element | Old | New |
|
||||
|---------|-----|-----|
|
||||
| Dialog title | text-xl | text-lg (Heading) |
|
||||
| Device names | text-sm | text-sm (Body) |
|
||||
| Device IDs | text-xs | text-xs (Label) |
|
||||
| Button text | text-sm | text-sm (Body) |
|
||||
|
||||
---
|
||||
|
||||
## Benefits
|
||||
|
||||
✅ **5 sizes only** - Down from 12 (much cleaner)
|
||||
✅ **Standard Tailwind** - No custom pixel values
|
||||
✅ **Accessible** - Minimum 12px (text-xs)
|
||||
✅ **Touch-friendly** - Buttons use text-sm (14px)
|
||||
✅ **Clear hierarchy** - Semantic naming (Display → Heading → Subheading → Body → Label)
|
||||
✅ **Easy to maintain** - Standard classes everyone knows
|
||||
✅ **Consistent responsive** - Only Display and Heading scale down
|
||||
|
||||
---
|
||||
|
||||
## Implementation Rules
|
||||
|
||||
### **When to use each level:**
|
||||
|
||||
**Display (text-xl/text-lg)** - Only for:
|
||||
- Main app title ("Respira")
|
||||
- Top-level page headers
|
||||
|
||||
**Heading (text-lg/text-base)** - For:
|
||||
- Section headers ("Pattern Preview", "Step 1: Connect")
|
||||
- Dialog titles
|
||||
- Empty state titles
|
||||
- Major workflow steps
|
||||
|
||||
**Subheading (text-sm semibold)** - For:
|
||||
- Card component titles ("Pattern File", "Active Pattern", "Progress")
|
||||
- Sub-section headers within cards
|
||||
|
||||
**Body (text-sm)** - For:
|
||||
- Primary readable content
|
||||
- Button labels (interactive!)
|
||||
- Error messages
|
||||
- Instructions and descriptions
|
||||
- Input fields
|
||||
|
||||
**Label (text-xs)** - For:
|
||||
- Metadata (filenames, dimensions, stitch counts)
|
||||
- Field labels ("Size:", "Stitches:", "Colors:")
|
||||
- Status badges
|
||||
- Helper text
|
||||
- Timestamps
|
||||
- Tags and small indicators
|
||||
|
||||
---
|
||||
|
||||
## Responsive Strategy
|
||||
|
||||
**Most text doesn't need responsive variants:**
|
||||
- Body (text-sm) stays the same
|
||||
- Label (text-xs) stays the same
|
||||
- Subheading (text-sm) stays the same
|
||||
|
||||
**Only top-level headers scale:**
|
||||
- Display: `text-lg lg:text-xl` (18px → 20px)
|
||||
- Heading: `text-base lg:text-lg` (16px → 18px)
|
||||
|
||||
This creates a subtle hierarchy shift on desktop without fragmenting the system.
|
||||
|
|
@ -1,577 +0,0 @@
|
|||
# UI Improvements: Before & After Examples
|
||||
|
||||
Visual comparison of key UI improvements with code examples.
|
||||
|
||||
---
|
||||
|
||||
## 1. Button States - Primary Action
|
||||
|
||||
### BEFORE
|
||||
```tsx
|
||||
<button
|
||||
onClick={onConnect}
|
||||
className="px-6 py-3 bg-blue-600 text-white rounded font-semibold text-sm hover:bg-blue-700 transition-all hover:shadow-md disabled:opacity-50 disabled:cursor-not-allowed disabled:grayscale-[0.3] cursor-pointer"
|
||||
>
|
||||
Connect to Machine
|
||||
</button>
|
||||
```
|
||||
|
||||
**Issues:**
|
||||
- Grayscale filter on disabled state looks unprofessional
|
||||
- No active/press state feedback
|
||||
- No focus state for keyboard navigation
|
||||
- Generic blue color, not semantic
|
||||
- Rounded corners too subtle (4px)
|
||||
|
||||
### AFTER
|
||||
```tsx
|
||||
<button
|
||||
onClick={onConnect}
|
||||
className="
|
||||
px-6 py-3
|
||||
bg-primary text-white
|
||||
rounded-lg font-semibold text-sm
|
||||
shadow-sm
|
||||
hover:bg-primary-light hover:shadow-md hover:scale-[1.02]
|
||||
active:bg-primary-dark active:scale-[0.98]
|
||||
focus:outline-none focus:ring-2 focus:ring-primary focus:ring-offset-2
|
||||
disabled:bg-neutral-300 disabled:text-neutral-500 disabled:cursor-not-allowed disabled:shadow-none
|
||||
transition-all duration-150 ease-in-out
|
||||
cursor-pointer
|
||||
"
|
||||
aria-label="Connect to Brother embroidery machine via Bluetooth"
|
||||
>
|
||||
Connect to Machine
|
||||
</button>
|
||||
```
|
||||
|
||||
**Improvements:**
|
||||
- Semantic color token (primary)
|
||||
- Clear disabled state (gray, no grayscale filter)
|
||||
- Press feedback (scale down on click)
|
||||
- Visible focus ring for accessibility
|
||||
- Slightly larger border radius (8px)
|
||||
- ARIA label for screen readers
|
||||
- Smooth transitions
|
||||
|
||||
**Visual Impact:**
|
||||
```
|
||||
BEFORE: [Connect to Machine] → (hover) [Connect to Machine] → (disabled) [Connect to Machine]
|
||||
Normal appearance Darker blue + shadow Washed out grayscale
|
||||
|
||||
AFTER: [Connect to Machine] → (hover) [Connect to Machine] → (disabled) [Connect to Machine]
|
||||
Blue with shadow Lighter blue, grows 2% Clean gray appearance
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Color Block Status - Progress Monitor
|
||||
|
||||
### BEFORE
|
||||
```tsx
|
||||
<div className={`
|
||||
p-2 rounded bg-gray-100 border-2 border-transparent transition-all
|
||||
${isCompleted ? 'border-green-600 bg-green-50' : ''}
|
||||
${isCurrent ? 'border-blue-600 bg-blue-50 shadow-md shadow-blue-600/20' : ''}
|
||||
${isUpcoming ? 'opacity-60' : ''}
|
||||
`}>
|
||||
<div className="flex items-center gap-2">
|
||||
<div className="w-5 h-5 rounded border-2 border-gray-300 shadow-sm flex-shrink-0"
|
||||
style={{ backgroundColor: block.threadHex }}
|
||||
/>
|
||||
<span className="font-semibold flex-1 text-sm">
|
||||
Thread {block.colorIndex + 1}
|
||||
</span>
|
||||
{isCompleted ? <CheckCircleIcon className="w-5 h-5 text-green-600" /> : null}
|
||||
{isCurrent ? <ArrowRightIcon className="w-5 h-5 text-blue-600" /> : null}
|
||||
{!isCompleted && !isCurrent ? <CircleStackIcon className="w-5 h-5 text-gray-400" /> : null}
|
||||
<span className="text-xs text-gray-600">
|
||||
{block.stitchCount.toLocaleString()}
|
||||
</span>
|
||||
</div>
|
||||
{isCurrent && (
|
||||
<div className="mt-1.5 h-1 bg-white rounded overflow-hidden">
|
||||
<div className="h-full bg-blue-600 transition-all duration-300"
|
||||
style={{ width: `${blockProgress}%` }}
|
||||
/>
|
||||
</div>
|
||||
)}
|
||||
</div>
|
||||
```
|
||||
|
||||
**Issues:**
|
||||
- Small color swatch (20px)
|
||||
- Thin progress bar (4px)
|
||||
- Small stitch count text (12px)
|
||||
- Minimal visual distinction between states
|
||||
- Upcoming blocks just fade (opacity-60)
|
||||
- Tight spacing (gap-2)
|
||||
|
||||
### AFTER
|
||||
```tsx
|
||||
<div className={`
|
||||
p-3 rounded-lg border-2 transition-all duration-200
|
||||
${isCompleted ? 'border-success bg-success-bg/50 shadow-sm' : ''}
|
||||
${isCurrent ? 'border-primary bg-primary/5 shadow-lg shadow-primary/10 ring-2 ring-primary/20 scale-[1.02]' : ''}
|
||||
${!isCompleted && !isCurrent ? 'border-neutral-200 bg-neutral-50 opacity-70' : ''}
|
||||
`}>
|
||||
<div className="flex items-center gap-3">
|
||||
<div className="w-6 h-6 rounded-md border-2 border-white shadow-md ring-1 ring-neutral-300 flex-shrink-0"
|
||||
style={{ backgroundColor: block.threadHex }}
|
||||
aria-label={`Thread color ${block.threadHex}`}
|
||||
/>
|
||||
<span className="font-semibold text-sm flex-1">
|
||||
Thread {block.colorIndex + 1}
|
||||
</span>
|
||||
{isCompleted && <CheckCircleIcon className="w-5 h-5 text-success" aria-label="Completed" />}
|
||||
{isCurrent && <ArrowRightIcon className="w-5 h-5 text-primary" aria-label="Current thread" />}
|
||||
{!isCompleted && !isCurrent && <CircleStackIcon className="w-5 h-5 text-neutral-400" aria-label="Upcoming" />}
|
||||
<span className="text-sm text-neutral-600 font-medium">
|
||||
{block.stitchCount.toLocaleString()}
|
||||
</span>
|
||||
</div>
|
||||
{isCurrent && (
|
||||
<div className="mt-2.5 h-1.5 bg-neutral-200 rounded-full overflow-hidden">
|
||||
<div className="h-full bg-primary transition-all duration-300 ease-out"
|
||||
style={{ width: `${blockProgress}%` }}
|
||||
role="progressbar"
|
||||
aria-valuenow={blockProgress}
|
||||
aria-valuemin={0}
|
||||
aria-valuemax={100}
|
||||
aria-label={`Thread ${block.colorIndex + 1} progress`}
|
||||
/>
|
||||
</div>
|
||||
)}
|
||||
</div>
|
||||
```
|
||||
|
||||
**Improvements:**
|
||||
- Larger color swatch (24px) - easier to see
|
||||
- Thicker progress bar (6px) - clearer progress indication
|
||||
- Larger stitch count (14px) - more readable
|
||||
- Current block has ring + glow + slight scale
|
||||
- More spacing (gap-3, p-3)
|
||||
- ARIA labels for accessibility
|
||||
- Semantic color tokens
|
||||
- Better rounded corners on swatch
|
||||
|
||||
**Visual Impact:**
|
||||
```
|
||||
BEFORE - Upcoming: [■ Thread 1 ○ 1,234] Faded gray box, small swatch
|
||||
BEFORE - Current: [■ Thread 2 → 2,456] Blue border, thin progress bar
|
||||
BEFORE - Complete: [■ Thread 3 ✓ 1,890] Green border
|
||||
|
||||
AFTER - Upcoming: [■ Thread 1 ○ 1,234] Subtle gray, clear upcoming state
|
||||
AFTER - Current: [■ Thread 2 → 2,456] Blue glow ring, prominent, thicker progress
|
||||
AFTER - Complete: [■ Thread 3 ✓ 1,890] Green with subtle shadow, completed
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Section Headers
|
||||
|
||||
### BEFORE
|
||||
```tsx
|
||||
<h2 className="text-xl font-semibold mb-4 pb-2 border-b-2 border-gray-300">
|
||||
Pattern Preview
|
||||
</h2>
|
||||
```
|
||||
|
||||
**Issues:**
|
||||
- Heavy bottom border (2px) but weak separation
|
||||
- Border too dark (gray-300)
|
||||
- Font weight only semibold (not bold)
|
||||
- No container grouping
|
||||
|
||||
### AFTER
|
||||
```tsx
|
||||
<div className="mb-5 pb-3 border-b border-neutral-200">
|
||||
<h2 className="text-xl font-bold text-neutral-900">Pattern Preview</h2>
|
||||
</div>
|
||||
```
|
||||
|
||||
**Improvements:**
|
||||
- Lighter, more subtle border (1px, neutral-200)
|
||||
- Bolder heading (font-bold)
|
||||
- Explicit text color (neutral-900)
|
||||
- More bottom padding (pb-3)
|
||||
- Wrapped in container for flex control
|
||||
|
||||
**Visual Impact:**
|
||||
```
|
||||
BEFORE:
|
||||
Pattern Preview
|
||||
================== (thick dark line)
|
||||
|
||||
AFTER:
|
||||
Pattern Preview
|
||||
___________________ (thin subtle line)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Workflow Stepper
|
||||
|
||||
### BEFORE
|
||||
```tsx
|
||||
{/* Progress line */}
|
||||
<div className="absolute top-4 left-0 h-0.5 bg-blue-400/30" ... />
|
||||
<div className="absolute top-4 left-0 h-0.5 bg-blue-100 ..." ... />
|
||||
|
||||
{/* Step circles */}
|
||||
<div className={`
|
||||
w-8 h-8 rounded-full flex items-center justify-center font-bold text-xs
|
||||
${isComplete ? 'bg-green-500 border-green-500 text-white' : ''}
|
||||
${isCurrent ? 'bg-blue-600 border-blue-600 text-white scale-110' : ''}
|
||||
${isUpcoming ? 'bg-blue-700 border-blue-400/30 text-blue-200' : ''}
|
||||
`}>
|
||||
{isComplete ? <CheckCircleIcon className="w-5 h-5" /> : step.id}
|
||||
</div>
|
||||
|
||||
{/* Labels */}
|
||||
<div className={`text-xs font-semibold ${isCurrent ? 'text-white' : isComplete ? 'text-blue-100' : 'text-blue-300'}`}>
|
||||
{step.label}
|
||||
</div>
|
||||
```
|
||||
|
||||
**Issues:**
|
||||
- Thin progress line (0.5px) - barely visible
|
||||
- Small step circles (32px)
|
||||
- Tiny text (12px)
|
||||
- Poor contrast for upcoming steps (blue-300 on blue-700)
|
||||
|
||||
### AFTER
|
||||
```tsx
|
||||
{/* Progress line - thicker, more visible */}
|
||||
<div className="absolute top-5 left-0 h-1 bg-blue-900/20" ... />
|
||||
<div className="absolute top-5 left-0 h-1 bg-blue-100 ..." ... />
|
||||
|
||||
{/* Step circles - larger */}
|
||||
<div className={`
|
||||
w-10 h-10 rounded-full flex items-center justify-center font-bold text-sm border-2
|
||||
${isComplete ? 'bg-success border-success text-white' : ''}
|
||||
${isCurrent ? 'bg-primary border-primary text-white scale-110 shadow-lg shadow-primary/30' : ''}
|
||||
${isUpcoming ? 'bg-blue-700 border-blue-400/30 text-blue-100' : ''}
|
||||
`}>
|
||||
{isComplete ? <CheckCircleIcon className="w-6 h-6" /> : step.id}
|
||||
</div>
|
||||
|
||||
{/* Labels - larger, better contrast */}
|
||||
<div className={`text-sm font-bold tracking-wide ${isCurrent ? 'text-white' : isComplete ? 'text-blue-50' : 'text-blue-200'}`}>
|
||||
{step.label}
|
||||
</div>
|
||||
```
|
||||
|
||||
**Improvements:**
|
||||
- Thicker progress line (4px vs 2px)
|
||||
- Larger circles (40px vs 32px)
|
||||
- Bigger text (14px vs 12px)
|
||||
- Better contrast for text (blue-100/50 instead of 300/200)
|
||||
- Shadow on current step
|
||||
- Semantic color tokens
|
||||
- Letter spacing for readability
|
||||
|
||||
**Visual Impact:**
|
||||
```
|
||||
BEFORE: ①---②---③---④---⑤---⑥---⑦ (small, thin line, small labels)
|
||||
|
||||
AFTER: ①━━━②━━━③━━━④━━━⑤━━━⑥━━━⑦ (larger, bold line, bigger labels)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Machine Connection - Status Badge
|
||||
|
||||
### BEFORE
|
||||
```tsx
|
||||
<span className={`flex items-center gap-2 px-3 py-1.5 rounded-lg font-semibold text-sm ${statusBadgeColors[stateVisual.color]}`}>
|
||||
<span className="text-base leading-none">{stateVisual.icon}</span>
|
||||
<span>{machineStatusName}</span>
|
||||
</span>
|
||||
```
|
||||
|
||||
**Issues:**
|
||||
- No border (looks flat)
|
||||
- Minimal padding
|
||||
- No explicit inline-flex
|
||||
|
||||
### AFTER
|
||||
```tsx
|
||||
<span className={`
|
||||
inline-flex items-center gap-2
|
||||
px-3.5 py-2
|
||||
rounded-lg
|
||||
font-semibold text-sm
|
||||
border border-current/20
|
||||
${statusBadgeColors[stateVisual.color]}
|
||||
`}>
|
||||
<span className="text-base leading-none">{stateVisual.icon}</span>
|
||||
<span>{machineStatusName}</span>
|
||||
</span>
|
||||
```
|
||||
|
||||
**Improvements:**
|
||||
- Subtle border using current color (adds depth)
|
||||
- Slightly more padding (3.5 vs 3, py-2 vs 1.5)
|
||||
- Explicit inline-flex for better alignment
|
||||
|
||||
**Visual Impact:**
|
||||
```
|
||||
BEFORE: [🔄 Sewing] Flat badge, no border
|
||||
|
||||
AFTER: [🔄 Sewing] Badge with subtle outline, more prominent
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Pattern Canvas - Overlays
|
||||
|
||||
### BEFORE
|
||||
```tsx
|
||||
{/* Thread Legend */}
|
||||
<div className="absolute top-2.5 left-2.5 bg-white/95 backdrop-blur-sm p-3 rounded-lg shadow-lg z-10 max-w-[150px]">
|
||||
<h4 className="m-0 mb-2 text-[13px] font-semibold text-gray-900 border-b border-gray-300 pb-1.5">
|
||||
Threads
|
||||
</h4>
|
||||
{/* ... */}
|
||||
</div>
|
||||
|
||||
{/* Zoom Controls */}
|
||||
<div className="absolute bottom-5 right-5 flex gap-2 items-center bg-white/95 backdrop-blur-sm px-3 py-2 rounded-lg shadow-lg z-10">
|
||||
<button className="w-8 h-8 p-1 border border-gray-300 ...">
|
||||
<PlusIcon className="w-5 h-5" />
|
||||
</button>
|
||||
{/* ... */}
|
||||
</div>
|
||||
```
|
||||
|
||||
**Issues:**
|
||||
- Inconsistent border radius (rounded-lg vs none)
|
||||
- No border on overlays
|
||||
- Small touch targets (32px buttons)
|
||||
- Mixed font sizes (13px)
|
||||
|
||||
### AFTER
|
||||
```tsx
|
||||
{/* Thread Legend - unified styling */}
|
||||
<div className="absolute top-3 left-3 bg-white/98 backdrop-blur-sm p-4 rounded-xl shadow-lg border border-neutral-200 z-10 max-w-[180px]">
|
||||
<h4 className="text-sm font-bold text-neutral-900 mb-3">Threads</h4>
|
||||
{pesData.threads.map((thread, index) => (
|
||||
<div key={index} className="flex items-center gap-2.5 mb-2 last:mb-0">
|
||||
<div className="w-6 h-6 rounded-md border-2 border-white shadow-sm ring-1 ring-neutral-300"
|
||||
style={{ backgroundColor: thread.hex }}
|
||||
/>
|
||||
<span className="text-sm text-neutral-900 font-medium">Thread {index + 1}</span>
|
||||
</div>
|
||||
))}
|
||||
</div>
|
||||
|
||||
{/* Zoom Controls - larger touch targets */}
|
||||
<div className="absolute bottom-5 right-5 flex items-center gap-1 bg-white/98 backdrop-blur-sm px-2 py-2 rounded-xl shadow-lg border border-neutral-200 z-10">
|
||||
<button className="w-10 h-10 flex items-center justify-center border border-neutral-300 rounded-lg ..."
|
||||
aria-label="Zoom in">
|
||||
<PlusIcon className="w-5 h-5" />
|
||||
</button>
|
||||
<div className="w-px h-6 bg-neutral-200 mx-1"></div>
|
||||
<span className="px-3 text-sm font-semibold text-neutral-900">{zoom}%</span>
|
||||
<div className="w-px h-6 bg-neutral-200 mx-1"></div>
|
||||
<button className="w-10 h-10 ..." aria-label="Zoom out">
|
||||
<MinusIcon className="w-5 h-5" />
|
||||
</button>
|
||||
<button className="w-10 h-10 ..." aria-label="Reset zoom">
|
||||
<ArrowPathIcon className="w-5 h-5" />
|
||||
</button>
|
||||
</div>
|
||||
```
|
||||
|
||||
**Improvements:**
|
||||
- Unified overlay style (rounded-xl, border, neutral colors)
|
||||
- Larger touch targets (40px vs 32px)
|
||||
- Visual separators between controls
|
||||
- Consistent font sizes (text-sm)
|
||||
- ARIA labels for accessibility
|
||||
- Better thread swatch styling (with ring)
|
||||
|
||||
**Visual Impact:**
|
||||
```
|
||||
BEFORE:
|
||||
┌───────────┐ [+] 100% [-] [↻]
|
||||
│ Threads │
|
||||
│ ■ Thread 1│
|
||||
└───────────┘
|
||||
|
||||
AFTER:
|
||||
╔═══════════╗ [+] │ 100% │ [-] [↻]
|
||||
║ Threads ║
|
||||
║ ■ Thread 1║
|
||||
╚═══════════╝
|
||||
(rounder, border) (larger, separated)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. FileUpload - Pattern Information
|
||||
|
||||
### BEFORE
|
||||
```tsx
|
||||
<div className="bg-gray-50 p-4 rounded-lg space-y-3">
|
||||
<div className="flex justify-between">
|
||||
<span className="font-medium text-gray-700">File Name:</span>
|
||||
<span className="font-semibold text-gray-900">{displayFileName}</span>
|
||||
</div>
|
||||
<div className="flex justify-between">
|
||||
<span className="font-medium text-gray-700">Pattern Size:</span>
|
||||
<span className="font-semibold text-gray-900">{size}</span>
|
||||
</div>
|
||||
{/* ... */}
|
||||
</div>
|
||||
```
|
||||
|
||||
**Issues:**
|
||||
- All in one gray box (low hierarchy)
|
||||
- Labels and values on same line (can overflow)
|
||||
- Tight spacing
|
||||
|
||||
### AFTER
|
||||
```tsx
|
||||
<div className="grid grid-cols-2 gap-3">
|
||||
<div className="bg-white p-3 rounded-lg border border-neutral-200 shadow-sm">
|
||||
<div className="text-xs font-medium text-neutral-500 mb-1.5 uppercase tracking-wide">File Name</div>
|
||||
<div className="font-semibold text-sm text-neutral-900 truncate" title={displayFileName}>
|
||||
{displayFileName}
|
||||
</div>
|
||||
</div>
|
||||
<div className="bg-white p-3 rounded-lg border border-neutral-200 shadow-sm">
|
||||
<div className="text-xs font-medium text-neutral-500 mb-1.5 uppercase tracking-wide">Size</div>
|
||||
<div className="font-semibold text-sm text-neutral-900">{size} mm</div>
|
||||
</div>
|
||||
<div className="bg-white p-3 rounded-lg border border-neutral-200 shadow-sm">
|
||||
<div className="text-xs font-medium text-neutral-500 mb-1.5 uppercase tracking-wide">Colors</div>
|
||||
<div className="font-semibold text-sm text-neutral-900">{pesData.colorCount}</div>
|
||||
</div>
|
||||
<div className="bg-white p-3 rounded-lg border border-neutral-200 shadow-sm">
|
||||
<div className="text-xs font-medium text-neutral-500 mb-1.5 uppercase tracking-wide">Stitches</div>
|
||||
<div className="font-semibold text-sm text-neutral-900">{pesData.stitchCount.toLocaleString()}</div>
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
**Improvements:**
|
||||
- 2×2 grid layout - better scannability
|
||||
- Individual cards for each stat
|
||||
- Clear label/value hierarchy
|
||||
- Uppercase labels with tracking
|
||||
- Truncation for long filenames
|
||||
- Better visual separation
|
||||
|
||||
**Visual Impact:**
|
||||
```
|
||||
BEFORE:
|
||||
┌─────────────────────────────────┐
|
||||
│ File Name: pattern.pes │
|
||||
│ Size: 100 × 50 mm │
|
||||
│ Colors: 5 │
|
||||
│ Stitches: 12,345 │
|
||||
└─────────────────────────────────┘
|
||||
|
||||
AFTER:
|
||||
┌──────────────┐ ┌──────────────┐
|
||||
│ FILE NAME │ │ SIZE │
|
||||
│ pattern.pes │ │ 100 × 50 mm │
|
||||
└──────────────┘ └──────────────┘
|
||||
┌──────────────┐ ┌──────────────┐
|
||||
│ COLORS │ │ STITCHES │
|
||||
│ 5 │ │ 12,345 │
|
||||
└──────────────┘ └──────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. Progress Bar - Unified Style
|
||||
|
||||
### BEFORE (Upload)
|
||||
```tsx
|
||||
<div className="h-3 bg-gray-300 rounded-md overflow-hidden shadow-inner">
|
||||
<div className="h-full bg-gradient-to-r from-blue-600 to-blue-700 transition-all duration-300 ease-out relative overflow-hidden after:absolute after:inset-0 after:bg-gradient-to-r after:from-transparent after:via-white/30 after:to-transparent after:animate-[shimmer_2s_infinite]"
|
||||
style={{ width: `${uploadProgress}%` }}
|
||||
/>
|
||||
</div>
|
||||
```
|
||||
|
||||
**Issues:**
|
||||
- Only upload has shimmer effect
|
||||
- Sewing progress bar is plain
|
||||
- Different bar heights in different places
|
||||
- Non-semantic colors
|
||||
|
||||
### AFTER (Unified)
|
||||
```tsx
|
||||
{/* Reusable progress bar component */}
|
||||
<div className="h-2.5 bg-neutral-200 rounded-full overflow-hidden shadow-inner">
|
||||
<div className="h-full bg-gradient-to-r from-primary to-primary-light transition-all duration-300 ease-out relative overflow-hidden"
|
||||
style={{ width: `${progress}%` }}
|
||||
role="progressbar"
|
||||
aria-valuenow={progress}
|
||||
aria-valuemin={0}
|
||||
aria-valuemax={100}
|
||||
aria-label={ariaLabel}
|
||||
>
|
||||
<div className="absolute inset-0 bg-gradient-to-r from-transparent via-white/30 to-transparent animate-[shimmer_2s_infinite]" />
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
**Improvements:**
|
||||
- Consistent height (10px/2.5)
|
||||
- Shimmer on all progress bars
|
||||
- Semantic colors (primary)
|
||||
- ARIA attributes
|
||||
- Rounded ends (rounded-full)
|
||||
- Same gradient style everywhere
|
||||
|
||||
---
|
||||
|
||||
## Summary of Key Visual Changes
|
||||
|
||||
| Element | Before | After | Impact |
|
||||
|---------|--------|-------|--------|
|
||||
| **Buttons** | Grayscale disabled, no press feedback | Clean gray disabled, scale press | Professional, accessible |
|
||||
| **Colors** | Mixed blues (blue-600, blue-700, cyan-600) | Semantic tokens (primary, success) | Consistent, meaningful |
|
||||
| **Typography** | 10-12px text common | 12-14px minimum | More readable |
|
||||
| **Spacing** | Varied (gap-2 to gap-6) | Standardized (2/3/4/6) | Cleaner layout |
|
||||
| **Touch Targets** | 32px buttons | 44px minimum | Better mobile UX |
|
||||
| **Borders** | Heavy (2px) or none | Subtle (1px) everywhere | Cohesive design |
|
||||
| **Focus States** | Missing on many elements | Ring on all interactive | Accessible |
|
||||
| **Shadows** | Inconsistent use | Strategic depth | Better hierarchy |
|
||||
| **Color Blocks** | Minimal distinction | Strong visual hierarchy | Clear progress |
|
||||
| **Overlays** | Mixed styles | Unified rounded-xl + border | Professional |
|
||||
|
||||
---
|
||||
|
||||
## Color Token Reference
|
||||
|
||||
```css
|
||||
Primary (actions): #2563eb (blue-600)
|
||||
Success (complete): #16a34a (green-600)
|
||||
Warning (wait): #d97706 (amber-600)
|
||||
Danger (errors): #dc2626 (red-600)
|
||||
Info (active): #0891b2 (cyan-600)
|
||||
Neutral text: #111827 (gray-900)
|
||||
Secondary text: #4b5563 (gray-600)
|
||||
Borders: #d1d5db (gray-300)
|
||||
Backgrounds: #f9fafb (gray-50)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Implementation Order
|
||||
|
||||
1. Create design tokens file
|
||||
2. Update all button classes
|
||||
3. Fix typography sizes
|
||||
4. Standardize spacing
|
||||
5. Add accessibility attributes
|
||||
6. Polish details (shadows, borders)
|
||||
7. Test all states (hover, active, focus, disabled)
|
||||
|
||||
Total time: ~2.5 hours
|
||||
|
|
@ -1,792 +0,0 @@
|
|||
# SKiTCH Controller UI Design Analysis & Recommendations
|
||||
|
||||
## Executive Summary
|
||||
|
||||
The SKiTCH Controller application has a solid foundation with Tailwind CSS v4, Heroicons, and a clean component structure. However, there are opportunities to improve visual hierarchy, consistency, accessibility, and user experience through refined color usage, typography, spacing, and interactive feedback.
|
||||
|
||||
---
|
||||
|
||||
## Current State Assessment
|
||||
|
||||
### Strengths
|
||||
- Clean, modern aesthetic with Tailwind CSS
|
||||
- Good use of Heroicons for consistent iconography
|
||||
- Responsive two-column layout that maximizes workspace
|
||||
- Workflow stepper provides clear progress indication
|
||||
- NextStepGuide component offers excellent contextual help
|
||||
- Compact design suitable for professional/technical users
|
||||
|
||||
### Areas for Improvement
|
||||
- Inconsistent color usage across components (multiple shades of blue, cyan, yellow)
|
||||
- Typography hierarchy could be stronger
|
||||
- Button states need better visual feedback
|
||||
- Information density varies across components
|
||||
- Some accessibility concerns (color contrast, focus states)
|
||||
- Visual weight of components doesn't always match importance
|
||||
|
||||
---
|
||||
|
||||
## Detailed Analysis & Recommendations
|
||||
|
||||
### 1. COLOR SYSTEM & CONSISTENCY
|
||||
|
||||
#### Current Issues
|
||||
- **Multiple blue variants**: blue-50, blue-100, blue-600, blue-700, cyan-50, cyan-100, cyan-600
|
||||
- **Inconsistent status colors**: Both cyan and blue used for "active" states
|
||||
- **Scattered color definitions**: Colors defined inline throughout components
|
||||
- **No semantic color system**: Colors don't communicate clear meaning
|
||||
|
||||
#### Recommendations
|
||||
|
||||
**Establish a Semantic Color Palette:**
|
||||
|
||||
```css
|
||||
/* Create a design tokens file: src/styles/design-tokens.css */
|
||||
@theme {
|
||||
--color-primary: #2563eb; /* blue-600 - Primary actions, branding */
|
||||
--color-primary-light: #3b82f6; /* blue-500 - Hover states */
|
||||
--color-primary-dark: #1d4ed8; /* blue-700 - Active states */
|
||||
|
||||
--color-secondary: #64748b; /* slate-600 - Secondary actions */
|
||||
--color-secondary-light: #94a3b8; /* slate-400 */
|
||||
|
||||
--color-success: #16a34a; /* green-600 - Success, complete */
|
||||
--color-success-bg: #dcfce7; /* green-100 */
|
||||
|
||||
--color-warning: #d97706; /* amber-600 - Warnings, waiting */
|
||||
--color-warning-bg: #fef3c7; /* amber-100 */
|
||||
|
||||
--color-danger: #dc2626; /* red-600 - Errors, destructive */
|
||||
--color-danger-bg: #fee2e2; /* red-100 */
|
||||
|
||||
--color-info: #0891b2; /* cyan-600 - Information, active */
|
||||
--color-info-bg: #cffafe; /* cyan-100 */
|
||||
|
||||
--color-neutral-50: #f9fafb; /* Backgrounds */
|
||||
--color-neutral-100: #f3f4f6; /* Subtle backgrounds */
|
||||
--color-neutral-300: #d1d5db; /* Borders */
|
||||
--color-neutral-600: #4b5563; /* Secondary text */
|
||||
--color-neutral-900: #111827; /* Primary text */
|
||||
}
|
||||
```
|
||||
|
||||
**Apply Consistently Across Components:**
|
||||
|
||||
Replace scattered color classes with semantic tokens:
|
||||
- `bg-blue-600` → `bg-primary`
|
||||
- `bg-cyan-600` → `bg-info`
|
||||
- `text-blue-900` → `text-primary-dark`
|
||||
|
||||
**Status Color Mapping:**
|
||||
```typescript
|
||||
// Create utility: src/utils/statusColors.ts
|
||||
export const STATUS_COLORS = {
|
||||
idle: 'info', // Cyan/blue - machine ready
|
||||
active: 'info', // Cyan/blue - in progress
|
||||
waiting: 'warning', // Amber - user action needed
|
||||
complete: 'success', // Green - finished
|
||||
error: 'danger', // Red - error state
|
||||
paused: 'warning' // Amber - paused
|
||||
} as const;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. TYPOGRAPHY & READABILITY
|
||||
|
||||
#### Current Issues
|
||||
- Inconsistent heading sizes across components
|
||||
- Some text too small (10px, 11px)
|
||||
- Line height not optimized for readability
|
||||
- Font weight usage inconsistent
|
||||
|
||||
#### Recommendations
|
||||
|
||||
**Establish Typography Scale:**
|
||||
|
||||
```typescript
|
||||
// Component heading hierarchy
|
||||
h1: "text-2xl font-bold" // Main title (SKiTCH Controller)
|
||||
h2: "text-xl font-semibold" // Section titles (Pattern Preview)
|
||||
h3: "text-base font-semibold" // Subsection titles (Pattern Information)
|
||||
h4: "text-sm font-semibold" // Small headings (Color Blocks)
|
||||
|
||||
// Body text scale
|
||||
body-lg: "text-base leading-relaxed" // 16px
|
||||
body: "text-sm leading-normal" // 14px
|
||||
body-sm: "text-xs leading-normal" // 12px
|
||||
caption: "text-[11px] leading-tight" // 11px (use sparingly)
|
||||
```
|
||||
|
||||
**Specific Component Improvements:**
|
||||
|
||||
**WorkflowStepper:**
|
||||
```tsx
|
||||
// Current: text-xs for step labels - TOO SMALL
|
||||
<div className="text-xs font-semibold">
|
||||
|
||||
// Recommended: Larger, more readable
|
||||
<div className="text-sm font-semibold tracking-wide">
|
||||
```
|
||||
|
||||
**ProgressMonitor - Color Blocks:**
|
||||
```tsx
|
||||
// Current: text-xs for thread labels
|
||||
<span className="text-xs text-gray-600">
|
||||
|
||||
// Recommended: Slightly larger for better scannability
|
||||
<span className="text-sm text-neutral-600">
|
||||
```
|
||||
|
||||
**PatternCanvas - Overlays:**
|
||||
```tsx
|
||||
// Current: Mixed sizes (10px, 11px, 13px)
|
||||
<div className="text-[11px]">
|
||||
<div className="text-[13px]">
|
||||
|
||||
// Recommended: Use consistent scale
|
||||
<div className="text-xs"> // 12px
|
||||
<div className="text-sm"> // 14px
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3. SPACING & VISUAL HIERARCHY
|
||||
|
||||
#### Current Issues
|
||||
- Component padding varies (p-3, p-4, p-6)
|
||||
- Inconsistent gap spacing (gap-2, gap-3, gap-4, gap-6)
|
||||
- Section headers don't always stand out
|
||||
- Some areas too cramped, others too spacious
|
||||
|
||||
#### Recommendations
|
||||
|
||||
**Standardize Component Spacing:**
|
||||
|
||||
```css
|
||||
/* Card/Section padding */
|
||||
.card-sm { @apply p-4; } /* Compact cards (ProgressMonitor) */
|
||||
.card-md { @apply p-5; } /* Standard cards (MachineConnection) */
|
||||
.card-lg { @apply p-6; } /* Important cards (NextStepGuide) */
|
||||
|
||||
/* Content spacing */
|
||||
.stack-xs { @apply space-y-2; } /* Tight grouping */
|
||||
.stack-sm { @apply space-y-3; } /* Related items */
|
||||
.stack-md { @apply space-y-4; } /* Section spacing */
|
||||
.stack-lg { @apply space-y-6; } /* Major sections */
|
||||
```
|
||||
|
||||
**Improve Visual Hierarchy in Cards:**
|
||||
|
||||
```tsx
|
||||
// Current header style (weak separation)
|
||||
<h2 className="text-xl font-semibold mb-4 pb-2 border-b-2 border-gray-300">
|
||||
|
||||
// Recommended (stronger presence)
|
||||
<div className="mb-5 pb-3 border-b border-neutral-200">
|
||||
<h2 className="text-xl font-bold text-neutral-900">Pattern Preview</h2>
|
||||
</div>
|
||||
```
|
||||
|
||||
**ProgressMonitor Layout Enhancement:**
|
||||
```tsx
|
||||
// Current: Grid with generic gaps
|
||||
<div className="grid grid-cols-1 md:grid-cols-2 gap-4">
|
||||
|
||||
// Recommended: Better defined sections
|
||||
<div className="grid grid-cols-1 md:grid-cols-2 gap-6">
|
||||
<div className="space-y-4">...</div> {/* Left column */}
|
||||
<div className="space-y-4">...</div> {/* Right column */}
|
||||
</div>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4. BUTTON DESIGN & INTERACTION STATES
|
||||
|
||||
#### Current Issues
|
||||
- Hover effects inconsistent
|
||||
- No active/pressed state visual feedback
|
||||
- Disabled states use grayscale filter (unusual)
|
||||
- Loading states could be clearer
|
||||
- Button hierarchy not always clear
|
||||
|
||||
#### Recommendations
|
||||
|
||||
**Primary Button System:**
|
||||
|
||||
```tsx
|
||||
// Primary actions (Start Sewing, Upload, Connect)
|
||||
className="
|
||||
px-6 py-3
|
||||
bg-primary text-white
|
||||
rounded-lg font-semibold text-sm
|
||||
shadow-sm
|
||||
hover:bg-primary-light hover:shadow-md
|
||||
active:bg-primary-dark active:scale-[0.98]
|
||||
focus:outline-none focus:ring-2 focus:ring-primary focus:ring-offset-2
|
||||
disabled:bg-neutral-300 disabled:text-neutral-500 disabled:cursor-not-allowed disabled:shadow-none
|
||||
transition-all duration-150 ease-in-out
|
||||
cursor-pointer
|
||||
"
|
||||
|
||||
// Secondary actions (Mask Trace, Refresh)
|
||||
className="
|
||||
px-6 py-3
|
||||
bg-white text-neutral-700 border border-neutral-300
|
||||
rounded-lg font-semibold text-sm
|
||||
shadow-sm
|
||||
hover:bg-neutral-50 hover:border-neutral-400
|
||||
active:bg-neutral-100 active:scale-[0.98]
|
||||
focus:outline-none focus:ring-2 focus:ring-neutral-400 focus:ring-offset-2
|
||||
disabled:bg-neutral-50 disabled:text-neutral-400 disabled:cursor-not-allowed
|
||||
transition-all duration-150 ease-in-out
|
||||
cursor-pointer
|
||||
"
|
||||
|
||||
// Destructive actions (Delete, Disconnect)
|
||||
className="
|
||||
px-6 py-3
|
||||
bg-danger text-white
|
||||
rounded-lg font-semibold text-sm
|
||||
shadow-sm
|
||||
hover:bg-red-700 hover:shadow-md
|
||||
active:bg-red-800 active:scale-[0.98]
|
||||
focus:outline-none focus:ring-2 focus:ring-danger focus:ring-offset-2
|
||||
disabled:bg-neutral-300 disabled:text-neutral-500 disabled:cursor-not-allowed disabled:shadow-none
|
||||
transition-all duration-150 ease-in-out
|
||||
cursor-pointer
|
||||
"
|
||||
```
|
||||
|
||||
**Remove Grayscale Filter:**
|
||||
```tsx
|
||||
// Current (problematic)
|
||||
disabled:opacity-50 disabled:cursor-not-allowed disabled:grayscale-[0.3]
|
||||
|
||||
// Recommended (clearer)
|
||||
disabled:bg-neutral-300 disabled:text-neutral-500 disabled:cursor-not-allowed disabled:shadow-none
|
||||
```
|
||||
|
||||
**Icon Buttons (Zoom controls):**
|
||||
```tsx
|
||||
// Current: Generic hover effect
|
||||
<button className="w-8 h-8 p-1 border border-gray-300 bg-white rounded
|
||||
hover:bg-blue-600 hover:text-white hover:border-blue-600">
|
||||
|
||||
// Recommended: More refined interaction
|
||||
<button className="
|
||||
w-9 h-9
|
||||
flex items-center justify-center
|
||||
bg-white border border-neutral-300
|
||||
rounded-lg
|
||||
text-neutral-700
|
||||
hover:bg-primary hover:text-white hover:border-primary
|
||||
active:bg-primary-dark active:scale-95
|
||||
focus:outline-none focus:ring-2 focus:ring-primary focus:ring-offset-2
|
||||
transition-all duration-150
|
||||
cursor-pointer
|
||||
">
|
||||
<PlusIcon className="w-5 h-5" />
|
||||
</button>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 5. COMPONENT-SPECIFIC IMPROVEMENTS
|
||||
|
||||
#### WorkflowStepper
|
||||
|
||||
**Current Issues:**
|
||||
- Steps appear small and hard to read
|
||||
- Progress line is subtle
|
||||
- Color coding could be clearer
|
||||
|
||||
**Recommendations:**
|
||||
```tsx
|
||||
// Larger, more prominent steps
|
||||
<div className="w-10 h-10 rounded-full ..."> {/* was w-8 h-8 */}
|
||||
|
||||
// Stronger progress line
|
||||
<div className="absolute top-5 left-0 right-0 h-1 bg-blue-900/20" ...> {/* was h-0.5 */}
|
||||
<div className="... h-1 bg-blue-100 ..." ...> {/* was h-0.5 */}
|
||||
|
||||
// Better color contrast for text
|
||||
<div className={`text-sm font-bold ${isCurrent ? 'text-white' : isComplete ? 'text-blue-50' : 'text-blue-200'}`}>
|
||||
```
|
||||
|
||||
#### MachineConnection
|
||||
|
||||
**Current Issues:**
|
||||
- Status badge colors defined inline
|
||||
- Machine info grid could be more scannable
|
||||
- Auto-refresh indicator too subtle
|
||||
|
||||
**Recommendations:**
|
||||
```tsx
|
||||
// Status badge with better visual weight
|
||||
<span className={`
|
||||
inline-flex items-center gap-2
|
||||
px-3.5 py-2
|
||||
rounded-lg
|
||||
font-semibold text-sm
|
||||
border border-current/20
|
||||
${statusBadgeColors[stateVisual.color]}
|
||||
`}>
|
||||
|
||||
// Clearer machine info layout
|
||||
<div className="bg-neutral-50 p-4 rounded-lg border border-neutral-200 space-y-3 mb-4">
|
||||
<div className="flex justify-between items-center">
|
||||
<span className="text-sm font-medium text-neutral-600">Model:</span>
|
||||
<span className="text-base font-bold text-neutral-900">{machineInfo.modelNumber}</span>
|
||||
</div>
|
||||
...
|
||||
</div>
|
||||
|
||||
// More prominent auto-refresh indicator
|
||||
<span className="flex items-center gap-2 px-3 py-1.5 bg-blue-50 rounded-full text-xs font-medium text-blue-700 border border-blue-200">
|
||||
<span className="w-2 h-2 bg-blue-500 rounded-full animate-pulse"></span>
|
||||
Auto-refreshing
|
||||
</span>
|
||||
```
|
||||
|
||||
#### ProgressMonitor - Color Blocks
|
||||
|
||||
**Current Issues:**
|
||||
- Current block indication could be stronger
|
||||
- Progress bar within block is small
|
||||
- Thread color swatches are small
|
||||
|
||||
**Recommendations:**
|
||||
```tsx
|
||||
// Larger thread color swatches
|
||||
<div
|
||||
className="w-6 h-6 rounded-md border-2 border-white shadow-md ring-1 ring-neutral-300 flex-shrink-0" {/* was w-5 h-5 */}
|
||||
style={{ backgroundColor: block.threadHex }}
|
||||
/>
|
||||
|
||||
// Stronger current block highlighting
|
||||
<div className={`
|
||||
p-3 rounded-lg border-2 transition-all
|
||||
${isCompleted ? 'border-success bg-success-bg' : ''}
|
||||
${isCurrent ? 'border-primary bg-primary/5 shadow-lg shadow-primary/10 ring-2 ring-primary/20' : ''}
|
||||
${!isCompleted && !isCurrent ? 'border-neutral-200 bg-neutral-50 opacity-70' : ''}
|
||||
`}>
|
||||
|
||||
// More prominent block progress bar
|
||||
<div className="mt-2 h-1.5 bg-neutral-200 rounded-full overflow-hidden"> {/* was h-1 */}
|
||||
<div
|
||||
className="h-full bg-primary transition-all duration-300"
|
||||
style={{ width: `${blockProgress}%` }}
|
||||
/>
|
||||
</div>
|
||||
```
|
||||
|
||||
#### NextStepGuide
|
||||
|
||||
**Current Issues:**
|
||||
- Good overall, but could use better visual differentiation between states
|
||||
- Icon size could be more prominent
|
||||
|
||||
**Recommendations:**
|
||||
```tsx
|
||||
// Larger, more prominent icon
|
||||
<InformationCircleIcon className="w-10 h-10 text-blue-600 flex-shrink-0" /> {/* was w-8 h-8 */}
|
||||
|
||||
// Add subtle shadow for depth
|
||||
<div className="bg-blue-50 border-l-4 border-blue-600 p-6 rounded-lg shadow-md">
|
||||
|
||||
// Enhance list item styling
|
||||
<ul className="list-disc list-inside text-sm text-blue-800 space-y-2 ml-1">
|
||||
<li className="pl-1"><strong>Press the button...</strong></li>
|
||||
</ul>
|
||||
```
|
||||
|
||||
#### PatternCanvas
|
||||
|
||||
**Current Issues:**
|
||||
- Overlays could be more cohesive in styling
|
||||
- Zoom controls could be grouped better
|
||||
- Pattern offset indicator is cluttered
|
||||
|
||||
**Recommendations:**
|
||||
```tsx
|
||||
// Unified overlay styling
|
||||
<div className="absolute top-3 left-3 bg-white/98 backdrop-blur-sm p-4 rounded-xl shadow-lg border border-neutral-200 z-10 max-w-[180px]">
|
||||
|
||||
// Grouped zoom controls with better spacing
|
||||
<div className="absolute bottom-5 right-5 flex items-center gap-1 bg-white/98 backdrop-blur-sm px-2 py-2 rounded-xl shadow-lg border border-neutral-200 z-10">
|
||||
<button className="...">...</button>
|
||||
<div className="w-px h-6 bg-neutral-200 mx-1"></div> {/* Separator */}
|
||||
<span className="px-3 text-sm font-semibold text-neutral-900">{zoom}%</span>
|
||||
<div className="w-px h-6 bg-neutral-200 mx-1"></div>
|
||||
<button className="...">...</button>
|
||||
<button className="...">...</button>
|
||||
</div>
|
||||
|
||||
// Cleaner pattern offset display
|
||||
<div className="absolute bottom-24 right-5 bg-white/98 backdrop-blur-sm p-3 rounded-xl shadow-lg border border-neutral-200 z-10">
|
||||
<div className="text-xs font-semibold text-neutral-500 uppercase tracking-wider mb-1.5">Position</div>
|
||||
<div className="text-sm font-bold text-primary">
|
||||
X: {x}mm Y: {y}mm
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 6. ACCESSIBILITY IMPROVEMENTS
|
||||
|
||||
#### Current Issues
|
||||
- Missing focus states on some interactive elements
|
||||
- Color-only state indication (color blocks)
|
||||
- Small touch targets (zoom buttons: 32px)
|
||||
- No keyboard navigation for canvas
|
||||
- Some contrast ratios below WCAG AA
|
||||
|
||||
#### Recommendations
|
||||
|
||||
**Focus States:**
|
||||
```tsx
|
||||
// Add visible focus rings to all interactive elements
|
||||
focus:outline-none focus:ring-2 focus:ring-primary focus:ring-offset-2
|
||||
```
|
||||
|
||||
**Touch Targets:**
|
||||
```tsx
|
||||
// Minimum 44px × 44px for buttons
|
||||
<button className="min-w-[44px] min-h-[44px] ...">
|
||||
```
|
||||
|
||||
**Color Block Accessibility:**
|
||||
```tsx
|
||||
// Add patterns/icons in addition to colors
|
||||
{isCompleted && <CheckCircleIcon className="w-5 h-5 text-success" />}
|
||||
{isCurrent && <ArrowRightIcon className="w-5 h-5 text-primary animate-pulse" />}
|
||||
{!isCompleted && !isCurrent && <CircleStackIcon className="w-5 h-5 text-neutral-400" />}
|
||||
```
|
||||
|
||||
**Contrast Improvements:**
|
||||
```tsx
|
||||
// Current: text-blue-300 on blue-700 background (low contrast)
|
||||
<div className="text-blue-300">
|
||||
|
||||
// Recommended: Better contrast
|
||||
<div className="text-blue-100">
|
||||
```
|
||||
|
||||
**ARIA Labels:**
|
||||
```tsx
|
||||
<button
|
||||
onClick={handleZoomIn}
|
||||
aria-label="Zoom in on pattern preview"
|
||||
title="Zoom In"
|
||||
>
|
||||
<PlusIcon className="w-5 h-5" />
|
||||
</button>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 7. INFORMATION DENSITY & WHITESPACE
|
||||
|
||||
#### Current Issues
|
||||
- FileUpload pattern info feels cramped
|
||||
- ProgressMonitor tries to show too much in limited space
|
||||
- Some cards have excessive padding while others are tight
|
||||
|
||||
#### Recommendations
|
||||
|
||||
**FileUpload - Pattern Information:**
|
||||
```tsx
|
||||
// Current: Everything in one gray box
|
||||
<div className="bg-gray-50 p-4 rounded-lg space-y-3">
|
||||
|
||||
// Recommended: Use grid for better scannability
|
||||
<div className="grid grid-cols-2 gap-3">
|
||||
<div className="bg-white p-3 rounded-lg border border-neutral-200">
|
||||
<div className="text-xs text-neutral-500 mb-1">File Name</div>
|
||||
<div className="font-semibold text-sm text-neutral-900 truncate">{fileName}</div>
|
||||
</div>
|
||||
<div className="bg-white p-3 rounded-lg border border-neutral-200">
|
||||
<div className="text-xs text-neutral-500 mb-1">Size</div>
|
||||
<div className="font-semibold text-sm text-neutral-900">{size} mm</div>
|
||||
</div>
|
||||
<div className="bg-white p-3 rounded-lg border border-neutral-200">
|
||||
<div className="text-xs text-neutral-500 mb-1">Colors</div>
|
||||
<div className="font-semibold text-sm text-neutral-900">{colors}</div>
|
||||
</div>
|
||||
<div className="bg-white p-3 rounded-lg border border-neutral-200">
|
||||
<div className="text-xs text-neutral-500 mb-1">Stitches</div>
|
||||
<div className="font-semibold text-sm text-neutral-900">{stitches}</div>
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
**Consistent Card Padding:**
|
||||
```tsx
|
||||
// Standard card wrapper
|
||||
<div className="bg-white p-6 rounded-xl shadow-sm border border-neutral-100">
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 8. PROGRESS & LOADING STATES
|
||||
|
||||
#### Current Issues
|
||||
- Upload progress bar has nice shimmer effect, but sewing progress bar doesn't
|
||||
- Loading states (file loading, Python initialization) could be more engaging
|
||||
- No skeleton states for loading content
|
||||
|
||||
#### Recommendations
|
||||
|
||||
**Consistent Progress Bars:**
|
||||
```tsx
|
||||
// Unified progress bar component style
|
||||
<div className="h-2.5 bg-neutral-200 rounded-full overflow-hidden shadow-inner">
|
||||
<div
|
||||
className="h-full bg-gradient-to-r from-primary to-primary-light transition-all duration-300 ease-out relative overflow-hidden"
|
||||
style={{ width: `${progress}%` }}
|
||||
>
|
||||
{/* Shimmer effect */}
|
||||
<div className="absolute inset-0 bg-gradient-to-r from-transparent via-white/30 to-transparent animate-[shimmer_2s_infinite]"></div>
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
**Loading Spinner Component:**
|
||||
```tsx
|
||||
// Create reusable loading indicator
|
||||
export function LoadingSpinner({ size = 'md' }: { size?: 'sm' | 'md' | 'lg' }) {
|
||||
const sizeClasses = {
|
||||
sm: 'w-4 h-4 border-2',
|
||||
md: 'w-6 h-6 border-2',
|
||||
lg: 'w-8 h-8 border-3'
|
||||
};
|
||||
|
||||
return (
|
||||
<div className={`
|
||||
${sizeClasses[size]}
|
||||
border-primary border-t-transparent
|
||||
rounded-full
|
||||
animate-spin
|
||||
`} />
|
||||
);
|
||||
}
|
||||
|
||||
// Use in FileUpload
|
||||
{isLoading && (
|
||||
<div className="flex items-center gap-2">
|
||||
<LoadingSpinner size="sm" />
|
||||
<span>Loading pattern...</span>
|
||||
</div>
|
||||
)}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 9. RESPONSIVE DESIGN ENHANCEMENTS
|
||||
|
||||
#### Current Issues
|
||||
- Two-column layout breaks to single column on mobile (good)
|
||||
- WorkflowStepper text becomes very small on narrow screens
|
||||
- Color blocks in ProgressMonitor could stack better on mobile
|
||||
|
||||
#### Recommendations
|
||||
|
||||
**WorkflowStepper Mobile Optimization:**
|
||||
```tsx
|
||||
// Simplify on small screens
|
||||
<div className="hidden sm:block text-sm font-bold">{step.label}</div>
|
||||
<div className="sm:hidden text-[10px] font-bold">{step.id}</div>
|
||||
```
|
||||
|
||||
**ProgressMonitor Responsive Grid:**
|
||||
```tsx
|
||||
// Better mobile stacking
|
||||
<div className="grid grid-cols-1 lg:grid-cols-2 gap-4 lg:gap-6">
|
||||
{/* Color blocks: scrollable on mobile */}
|
||||
<div className="lg:max-h-none max-h-[300px] overflow-y-auto">
|
||||
{/* Color blocks */}
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Implementation Priority
|
||||
|
||||
### Phase 1: Foundation (High Impact, Low Effort)
|
||||
1. Establish semantic color tokens
|
||||
2. Standardize typography scale
|
||||
3. Update button states and remove grayscale filter
|
||||
4. Add focus states for accessibility
|
||||
5. Improve touch target sizes
|
||||
|
||||
### Phase 2: Polish (High Impact, Medium Effort)
|
||||
1. Refine WorkflowStepper visual prominence
|
||||
2. Enhance color block design in ProgressMonitor
|
||||
3. Improve PatternCanvas overlay cohesion
|
||||
4. Standardize component spacing
|
||||
5. Update status badge styling
|
||||
|
||||
### Phase 3: Enhancement (Medium Impact, Medium Effort)
|
||||
1. Create reusable button component variants
|
||||
2. Refine FileUpload information display
|
||||
3. Add consistent loading states
|
||||
4. Improve responsive behavior
|
||||
5. Add subtle animations and transitions
|
||||
|
||||
### Phase 4: Advanced (Nice to Have)
|
||||
1. Dark mode support
|
||||
2. Custom theme configuration
|
||||
3. Animation performance optimization
|
||||
4. Advanced accessibility features (keyboard nav for canvas)
|
||||
5. User preference persistence
|
||||
|
||||
---
|
||||
|
||||
## Code Examples: Key Component Updates
|
||||
|
||||
### Example 1: Updated MachineConnection Button
|
||||
|
||||
**Before:**
|
||||
```tsx
|
||||
<button
|
||||
onClick={onConnect}
|
||||
className="px-6 py-3 bg-blue-600 text-white rounded font-semibold text-sm hover:bg-blue-700 transition-all hover:shadow-md disabled:opacity-50 disabled:cursor-not-allowed disabled:grayscale-[0.3] cursor-pointer"
|
||||
>
|
||||
Connect to Machine
|
||||
</button>
|
||||
```
|
||||
|
||||
**After:**
|
||||
```tsx
|
||||
<button
|
||||
onClick={onConnect}
|
||||
className="
|
||||
px-6 py-3
|
||||
bg-primary text-white
|
||||
rounded-lg font-semibold text-sm
|
||||
shadow-sm
|
||||
hover:bg-primary-light hover:shadow-md hover:scale-[1.02]
|
||||
active:bg-primary-dark active:scale-[0.98]
|
||||
focus:outline-none focus:ring-2 focus:ring-primary focus:ring-offset-2
|
||||
disabled:bg-neutral-300 disabled:text-neutral-500 disabled:cursor-not-allowed disabled:shadow-none
|
||||
transition-all duration-150 ease-in-out
|
||||
cursor-pointer
|
||||
"
|
||||
aria-label="Connect to Brother embroidery machine via Bluetooth"
|
||||
>
|
||||
Connect to Machine
|
||||
</button>
|
||||
```
|
||||
|
||||
### Example 2: Updated Color Block Design
|
||||
|
||||
**Before:**
|
||||
```tsx
|
||||
<div className={`p-2 rounded bg-gray-100 border-2 border-transparent transition-all ${
|
||||
isCompleted ? 'border-green-600 bg-green-50' :
|
||||
isCurrent ? 'border-blue-600 bg-blue-50 shadow-md shadow-blue-600/20' :
|
||||
'opacity-60'
|
||||
}`}>
|
||||
```
|
||||
|
||||
**After:**
|
||||
```tsx
|
||||
<div className={`
|
||||
p-3 rounded-lg border-2 transition-all duration-200
|
||||
${isCompleted ? 'border-success bg-success-bg/50 shadow-sm' : ''}
|
||||
${isCurrent ? 'border-primary bg-primary/5 shadow-lg shadow-primary/10 ring-2 ring-primary/20 scale-[1.02]' : ''}
|
||||
${!isCompleted && !isCurrent ? 'border-neutral-200 bg-neutral-50 opacity-70' : ''}
|
||||
`}>
|
||||
<div className="flex items-center gap-3"> {/* increased gap */}
|
||||
<div
|
||||
className="w-6 h-6 rounded-md border-2 border-white shadow-md ring-1 ring-neutral-300 flex-shrink-0"
|
||||
style={{ backgroundColor: block.threadHex }}
|
||||
aria-label={`Thread color ${block.threadHex}`}
|
||||
/>
|
||||
<span className="font-semibold text-sm flex-1">Thread {block.colorIndex + 1}</span>
|
||||
{isCompleted && <CheckCircleIcon className="w-5 h-5 text-success" aria-label="Completed" />}
|
||||
{isCurrent && <ArrowRightIcon className="w-5 h-5 text-primary" aria-label="Current" />}
|
||||
{!isCompleted && !isCurrent && <CircleStackIcon className="w-5 h-5 text-neutral-400" aria-label="Upcoming" />}
|
||||
<span className="text-sm text-neutral-600 font-medium">{block.stitchCount.toLocaleString()}</span>
|
||||
</div>
|
||||
{isCurrent && (
|
||||
<div className="mt-2.5 h-1.5 bg-neutral-200 rounded-full overflow-hidden">
|
||||
<div
|
||||
className="h-full bg-primary transition-all duration-300 ease-out"
|
||||
style={{ width: `${blockProgress}%` }}
|
||||
role="progressbar"
|
||||
aria-valuenow={blockProgress}
|
||||
aria-valuemin={0}
|
||||
aria-valuemax={100}
|
||||
/>
|
||||
</div>
|
||||
)}
|
||||
</div>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Accessibility Checklist
|
||||
|
||||
- [ ] All interactive elements have minimum 44×44px touch targets
|
||||
- [ ] Focus states visible on all focusable elements
|
||||
- [ ] Color contrast meets WCAG AA (4.5:1 for text, 3:1 for UI)
|
||||
- [ ] Status information not conveyed by color alone
|
||||
- [ ] All icons have appropriate aria-labels or titles
|
||||
- [ ] Form inputs have associated labels
|
||||
- [ ] Loading states announced to screen readers
|
||||
- [ ] Keyboard navigation works for all controls
|
||||
- [ ] Error messages are clear and actionable
|
||||
- [ ] Progress bars have appropriate ARIA attributes
|
||||
|
||||
---
|
||||
|
||||
## Design System Assets Needed
|
||||
|
||||
### Typography
|
||||
- Font stack: System UI fonts (already handled by Tailwind)
|
||||
- Defined text sizes and line heights
|
||||
- Consistent font weights (400, 500, 600, 700)
|
||||
|
||||
### Colors
|
||||
- Semantic color palette with design tokens
|
||||
- Status color mapping
|
||||
- Neutral grays for backgrounds and borders
|
||||
|
||||
### Spacing
|
||||
- Standardized padding scale (4px increments)
|
||||
- Consistent gap/margin values
|
||||
- Section spacing guidelines
|
||||
|
||||
### Components
|
||||
- Button variants (primary, secondary, danger, ghost)
|
||||
- Card/panel styles
|
||||
- Badge/tag styles
|
||||
- Progress indicators
|
||||
- Loading states
|
||||
- Alert/notification styles
|
||||
|
||||
### Icons
|
||||
- Heroicons (already in use)
|
||||
- Consistent sizing (w-4, w-5, w-6, w-8)
|
||||
- Proper color inheritance
|
||||
|
||||
---
|
||||
|
||||
## Conclusion
|
||||
|
||||
The SKiTCH Controller has a solid UI foundation but would benefit significantly from:
|
||||
|
||||
1. **Systematic color usage** - Define semantic tokens, apply consistently
|
||||
2. **Stronger visual hierarchy** - Clearer typography, better spacing
|
||||
3. **Better interaction feedback** - Refined button states, remove grayscale filter
|
||||
4. **Enhanced accessibility** - Focus states, touch targets, ARIA labels
|
||||
5. **Polished details** - Consistent component styling, unified overlays
|
||||
|
||||
These improvements will create a more professional, usable, and accessible application while maintaining the compact, efficient design suitable for technical users.
|
||||
|
||||
The recommended changes are incremental and can be implemented in phases, starting with the high-impact, low-effort foundational improvements and progressing to more advanced enhancements.
|
||||
|
|
@ -1,173 +0,0 @@
|
|||
# UI/UX Improvements for Brother Embroidery Machine Controller
|
||||
|
||||
## Overview
|
||||
This document outlines the UI/UX improvements made to enhance usability for non-technical users.
|
||||
|
||||
## Key Improvements
|
||||
|
||||
### 1. Workflow Stepper Component
|
||||
**File:** `src/components/WorkflowStepper.tsx`
|
||||
|
||||
A visual progress indicator showing all 7 steps of the embroidery workflow:
|
||||
1. Connect to Machine
|
||||
2. Load Pattern
|
||||
3. Upload Pattern
|
||||
4. Mask Trace
|
||||
5. Start Sewing
|
||||
6. Monitor Progress
|
||||
7. Complete
|
||||
|
||||
**Features:**
|
||||
- Clear visual indication of current step (highlighted in blue with ring)
|
||||
- Completed steps marked with green checkmarks
|
||||
- Future steps shown in gray
|
||||
- Progress bar connecting all steps
|
||||
- Step descriptions for context
|
||||
|
||||
### 2. Next Step Guide Component
|
||||
**File:** `src/components/NextStepGuide.tsx`
|
||||
|
||||
Context-sensitive guidance that shows users exactly what to do next:
|
||||
|
||||
**Features:**
|
||||
- Clear instruction cards with icons
|
||||
- Step-by-step bullet points
|
||||
- Color-coded by urgency:
|
||||
- Blue: Informational/next action
|
||||
- Yellow: Waiting for user/machine action
|
||||
- Green: Success/ready states
|
||||
- Red: Errors
|
||||
- Tailored messages for each machine state
|
||||
- Non-technical language
|
||||
|
||||
### 3. Pattern Upload Lock
|
||||
**Modified:** `src/components/FileUpload.tsx`
|
||||
|
||||
Prevents users from accidentally changing the pattern after upload:
|
||||
|
||||
**Features:**
|
||||
- Pattern file selection disabled after successful upload
|
||||
- Clear notification explaining pattern is locked
|
||||
- Users must complete or delete current pattern before uploading new one
|
||||
- Prevents confusion and potential errors
|
||||
|
||||
### 4. Simplified Information Display
|
||||
|
||||
**Modified Components:**
|
||||
- `MachineConnection.tsx`: Reduced from 5 details to 2 essential ones
|
||||
- `FileUpload.tsx`: Added filename, reformatted with better visual hierarchy
|
||||
- `ProgressMonitor.tsx`: Simplified time display, removed technical coordinates
|
||||
- All components use consistent card-style layouts with gray backgrounds
|
||||
|
||||
**Changes:**
|
||||
- Removed technical details (MAC address, serial number, raw coordinates)
|
||||
- Added thousand separators for numbers (e.g., "12,345 stitches")
|
||||
- Changed time format from "5:30" to "5 min 30 sec" for clarity
|
||||
- Larger progress percentage display (2xl font)
|
||||
- Better visual grouping of related information
|
||||
|
||||
### 5. Contextual UI Visibility
|
||||
|
||||
**Modified:** `src/App.tsx`
|
||||
|
||||
Sections now show/hide based on workflow state:
|
||||
|
||||
**Visibility Rules:**
|
||||
- **Workflow Stepper**: Only visible when connected
|
||||
- **Next Step Guide**: Always visible, content changes based on state
|
||||
- **Machine Connection**: Always visible
|
||||
- **Pattern File**: Only visible when connected
|
||||
- **Sewing Progress**: Only visible when pattern is uploaded
|
||||
- **Pattern Preview**: Shows placeholder when no pattern loaded
|
||||
|
||||
### 6. Enhanced Visual Design
|
||||
|
||||
**Changes:**
|
||||
- New gradient blue header with tagline
|
||||
- Gray background for better card contrast
|
||||
- Consistent rounded corners and shadows
|
||||
- Better spacing and padding
|
||||
- Color-coded status indicators throughout
|
||||
- Improved typography hierarchy
|
||||
|
||||
### 7. Better Error Handling
|
||||
|
||||
**Features:**
|
||||
- Errors displayed prominently at top of page
|
||||
- Clear error messages with left border highlighting
|
||||
- Error guidance in Next Step Guide
|
||||
- Distinct error states in workflow
|
||||
|
||||
## User Experience Flow
|
||||
|
||||
### Before Improvements:
|
||||
1. All panels visible at once
|
||||
2. No clear indication of what to do next
|
||||
3. Technical information overwhelming
|
||||
4. Could change pattern after upload
|
||||
5. No visual workflow guidance
|
||||
|
||||
### After Improvements:
|
||||
1. Clear step-by-step progression shown at top
|
||||
2. Next Step Guide tells users exactly what to do
|
||||
3. Only relevant sections visible for current step
|
||||
4. Pattern locked after upload (prevents mistakes)
|
||||
5. Simple, non-technical language throughout
|
||||
6. Visual feedback at every step
|
||||
|
||||
## Technical Implementation
|
||||
|
||||
### New Files Created:
|
||||
- `src/components/WorkflowStepper.tsx`
|
||||
- `src/components/NextStepGuide.tsx`
|
||||
|
||||
### Modified Files:
|
||||
- `src/App.tsx` - Main layout and state management
|
||||
- `src/components/FileUpload.tsx` - Added pattern lock
|
||||
- `src/components/MachineConnection.tsx` - Simplified display
|
||||
- `src/components/ProgressMonitor.tsx` - Improved readability
|
||||
- `src/utils/errorCodeHelpers.ts` - Fixed TypeScript compatibility
|
||||
|
||||
### State Management:
|
||||
- Added `patternUploaded` state to track upload status
|
||||
- Pattern lock prevents re-upload without delete
|
||||
- Automatic state detection from machine status
|
||||
- Proper cleanup on disconnect/delete
|
||||
|
||||
## Design Principles Applied
|
||||
|
||||
1. **Progressive Disclosure**: Show only what's needed for current step
|
||||
2. **Clarity Over Completeness**: Hide technical details, show user-friendly info
|
||||
3. **Visual Hierarchy**: Use size, color, and spacing to guide attention
|
||||
4. **Feedback**: Always show current state and next action
|
||||
5. **Error Prevention**: Lock pattern after upload, confirm destructive actions
|
||||
6. **Consistency**: Unified visual language across all components
|
||||
|
||||
## Accessibility Considerations
|
||||
|
||||
- Clear visual indicators with icons
|
||||
- Color not the only differentiator (icons + text)
|
||||
- Large touch targets for buttons
|
||||
- Readable font sizes
|
||||
- Semantic HTML structure
|
||||
- Clear labels and descriptions
|
||||
|
||||
## Testing Recommendations
|
||||
|
||||
1. Test complete workflow from connect to complete
|
||||
2. Verify pattern cannot be changed after upload
|
||||
3. Check all machine states show correct guidance
|
||||
4. Test error scenarios display properly
|
||||
5. Verify responsiveness on different screen sizes
|
||||
6. Test with actual embroidery machine if possible
|
||||
|
||||
## Future Enhancement Opportunities
|
||||
|
||||
1. Add estimated time remaining during sewing
|
||||
2. Add pattern preview thumbnails in stepper
|
||||
3. Add sound notifications for state changes
|
||||
4. Add pattern history/favorites
|
||||
5. Add tutorial mode for first-time users
|
||||
6. Add keyboard shortcuts for power users
|
||||
7. Add offline mode indicators
|
||||
8. Add pattern size validation warnings
|
||||
|
|
@ -1,260 +0,0 @@
|
|||
# UI Improvements Implementation Summary
|
||||
|
||||
## Overview
|
||||
Successfully implemented UI/UX enhancements to SKiTCH Controller following the standard approach recommendations. All changes focus on improving visual hierarchy, accessibility, and user experience while maintaining the compact, efficient design.
|
||||
|
||||
---
|
||||
|
||||
## Changes Implemented
|
||||
|
||||
### 1. Design Tokens System ✅
|
||||
**File:** `src/styles/designTokens.ts`
|
||||
|
||||
Created a comprehensive design tokens file with:
|
||||
- **Semantic color system** - primary, success, warning, danger, info, neutral
|
||||
- **Button classes** - Reusable styles for all button variants
|
||||
- **Typography scale** - Defined heading and body text sizes
|
||||
- **Spacing scale** - Consistent gaps and padding
|
||||
- **Alert classes** - Status box patterns
|
||||
|
||||
**Impact:** Provides a single source of truth for design consistency across the app.
|
||||
|
||||
---
|
||||
|
||||
### 2. Enhanced Button States ✅
|
||||
**Files Modified:**
|
||||
- `src/components/ProgressMonitor.tsx`
|
||||
- `src/components/MachineConnection.tsx`
|
||||
- `src/components/FileUpload.tsx`
|
||||
- `src/components/ConfirmDialog.tsx`
|
||||
|
||||
**Improvements:**
|
||||
- ✅ **Rounded corners** - Changed from `rounded` to `rounded-lg` for softer appearance
|
||||
- ✅ **Better padding** - Standardized to `py-2.5` for comfortable click targets
|
||||
- ✅ **Hover effects** - Added `hover:shadow-lg` for depth
|
||||
- ✅ **Active press feedback** - Added `active:scale-[0.98]` for tactile feel
|
||||
- ✅ **Focus rings** - Added `focus:ring-2` with color-matched rings for keyboard navigation
|
||||
- ✅ **Disabled states** - Clean opacity change, no grayscale filter
|
||||
- ✅ **Active states** - Added `active:bg-{color}-800` for click feedback
|
||||
- ✅ **Smooth transitions** - `duration-150` for responsive feel
|
||||
|
||||
**Before:**
|
||||
```tsx
|
||||
className="px-4 py-2 bg-blue-600 text-white rounded hover:bg-blue-700"
|
||||
```
|
||||
|
||||
**After:**
|
||||
```tsx
|
||||
className="px-4 py-2.5 bg-blue-600 text-white rounded-lg font-semibold text-sm
|
||||
hover:bg-blue-700 active:bg-blue-800 hover:shadow-lg active:scale-[0.98]
|
||||
transition-all duration-150 cursor-pointer
|
||||
focus:outline-none focus:ring-2 focus:ring-blue-300 focus:ring-offset-2"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3. Improved WorkflowStepper ✅
|
||||
**File:** `src/components/WorkflowStepper.tsx`
|
||||
|
||||
**Visual Enhancements:**
|
||||
- ✅ **Larger step circles** - Increased from `w-8 h-8` to `w-10 h-10`
|
||||
- ✅ **Gradient progress bar** - `from-green-500 to-blue-500` shows completion visually
|
||||
- ✅ **Better completed state** - Green circles with check icons
|
||||
- ✅ **Enhanced current state** - Ring effect with `ring-2 ring-blue-300`
|
||||
- ✅ **Improved shadows** - Color-matched shadows (`shadow-blue-600/40`)
|
||||
- ✅ **Thicker progress line** - Changed from `h-0.5` to `h-1`
|
||||
|
||||
**Accessibility:**
|
||||
- ✅ Added `role="navigation"` and `aria-label="Workflow progress"`
|
||||
- ✅ Progress bar has `role="progressbar"` with aria-value attributes
|
||||
- ✅ Each step has `role="listitem"` and `aria-current="step"` for current
|
||||
- ✅ Step circles have descriptive `aria-label` with state info
|
||||
|
||||
**Impact:** Clearer workflow visualization with green showing completion and blue showing current/upcoming steps.
|
||||
|
||||
---
|
||||
|
||||
### 4. Enhanced Color Blocks in ProgressMonitor ✅
|
||||
**File:** `src/components/ProgressMonitor.tsx`
|
||||
|
||||
**Visual Improvements:**
|
||||
- ✅ **Larger color swatches** - Increased from `w-5 h-5` to `w-8 h-8`
|
||||
- ✅ **Better borders** - `rounded-lg` instead of `rounded`
|
||||
- ✅ **Enhanced shadows** - Added `shadow-md` to swatches
|
||||
- ✅ **Ring effect on current** - Dynamic ring color for active thread
|
||||
- ✅ **Improved layout** - Two-line thread info (name + stitch count)
|
||||
- ✅ **Larger status icons** - Increased from `w-5 h-5` to `w-6 h-6`
|
||||
- ✅ **Animated current indicator** - Added `animate-pulse` to arrow
|
||||
- ✅ **Better progress bar** - Taller (`h-2`) with rounded ends
|
||||
- ✅ **Clearer states** - Different border colors and backgrounds
|
||||
|
||||
**Accessibility:**
|
||||
- ✅ Added `role="listitem"` to each color block
|
||||
- ✅ Comprehensive `aria-label` with thread number, count, and status
|
||||
- ✅ Color swatch has `aria-label` with hex color
|
||||
- ✅ Progress bar has `role="progressbar"` with aria-value attributes
|
||||
- ✅ Status icons have `aria-label` for screen readers
|
||||
|
||||
**Impact:** Thread colors are now much easier to see, and the current block is clearly indicated.
|
||||
|
||||
---
|
||||
|
||||
### 5. Accessibility Enhancements ✅
|
||||
|
||||
**ARIA Labels Added:**
|
||||
- ✅ All buttons have descriptive `aria-label` attributes
|
||||
- ✅ Progress bars have `role="progressbar"` with value attributes
|
||||
- ✅ Workflow stepper has proper navigation role
|
||||
- ✅ Color blocks have detailed state information
|
||||
- ✅ Dynamic labels update based on context
|
||||
|
||||
**Focus Management:**
|
||||
- ✅ All interactive elements have visible focus rings
|
||||
- ✅ Focus rings use color-matched styling
|
||||
- ✅ `focus:outline-none` with custom ring for consistency
|
||||
- ✅ Ring offset for better visibility
|
||||
|
||||
**Keyboard Navigation:**
|
||||
- ✅ All buttons are keyboard accessible
|
||||
- ✅ Tab order follows logical flow
|
||||
- ✅ Focus states clearly visible
|
||||
|
||||
---
|
||||
|
||||
### 6. Typography Improvements ✅
|
||||
|
||||
**Text Sizes:**
|
||||
- ✅ Maintained minimum 12px (`text-xs`) throughout
|
||||
- ✅ Body text at 14px (`text-sm`)
|
||||
- ✅ Headings properly sized (text-lg, text-xl, text-2xl)
|
||||
- ✅ Consistent font weights (semibold for emphasis)
|
||||
|
||||
**Readability:**
|
||||
- ✅ Proper line height on multi-line text
|
||||
- ✅ Color contrast meets WCAG standards
|
||||
- ✅ Hierarchical sizing for scanability
|
||||
|
||||
---
|
||||
|
||||
## Files Modified
|
||||
|
||||
1. ✅ `src/styles/designTokens.ts` - Created new design system
|
||||
2. ✅ `src/components/ProgressMonitor.tsx` - Enhanced buttons, color blocks, accessibility
|
||||
3. ✅ `src/components/WorkflowStepper.tsx` - Improved visibility, states, accessibility
|
||||
4. ✅ `src/components/MachineConnection.tsx` - Updated button styles
|
||||
5. ✅ `src/components/FileUpload.tsx` - Enhanced upload button
|
||||
6. ✅ `src/components/ConfirmDialog.tsx` - Improved dialog buttons
|
||||
|
||||
---
|
||||
|
||||
## User Experience Improvements
|
||||
|
||||
### Visual Hierarchy
|
||||
- ✅ **Clearer states** - Completed (green), current (blue with ring), pending (muted)
|
||||
- ✅ **Better affordances** - Buttons clearly look clickable with shadows
|
||||
- ✅ **Logical flow** - Color progression in workflow stepper (green → blue)
|
||||
|
||||
### Interaction Feedback
|
||||
- ✅ **Hover feedback** - Shadow increase on hover
|
||||
- ✅ **Press feedback** - Subtle scale-down on click
|
||||
- ✅ **Disabled clarity** - Opacity change without grayscale
|
||||
- ✅ **Focus visibility** - Clear rings for keyboard users
|
||||
|
||||
### Information Density
|
||||
- ✅ **Larger touch targets** - Buttons now have comfortable padding
|
||||
- ✅ **Better spacing** - Consistent gaps between elements
|
||||
- ✅ **Readable text** - All text meets minimum size requirements
|
||||
|
||||
---
|
||||
|
||||
## Accessibility Compliance
|
||||
|
||||
### WCAG 2.1 Level AA
|
||||
- ✅ **Color contrast** - All text meets 4.5:1 ratio minimum
|
||||
- ✅ **Focus indicators** - Visible 2px focus rings with offset
|
||||
- ✅ **Semantic HTML** - Proper roles and ARIA attributes
|
||||
- ✅ **Keyboard navigation** - All interactive elements accessible
|
||||
- ✅ **Screen reader support** - Descriptive labels throughout
|
||||
|
||||
### Touch Targets
|
||||
- ✅ **44px minimum height** - All buttons meet mobile accessibility standards
|
||||
- ✅ **Sufficient spacing** - Buttons have adequate gaps to prevent mis-taps
|
||||
|
||||
---
|
||||
|
||||
## Testing Checklist
|
||||
|
||||
### Visual Testing ✅
|
||||
- [x] All buttons display with proper hover states
|
||||
- [x] Active press feedback works on click
|
||||
- [x] Focus rings appear on keyboard navigation
|
||||
- [x] Color blocks show larger swatches
|
||||
- [x] Workflow stepper shows green for completed steps
|
||||
- [x] Shadows enhance depth perception
|
||||
|
||||
### Interaction Testing ✅
|
||||
- [x] Buttons respond to hover
|
||||
- [x] Buttons provide click feedback
|
||||
- [x] Disabled buttons don't respond to interaction
|
||||
- [x] Tab navigation works logically
|
||||
- [x] Focus rings are clearly visible
|
||||
|
||||
### Accessibility Testing ✅
|
||||
- [x] Screen reader announces button purposes
|
||||
- [x] Progress bars announce current values
|
||||
- [x] Color blocks provide complete state info
|
||||
- [x] Keyboard navigation works without mouse
|
||||
- [x] Focus order is logical
|
||||
|
||||
---
|
||||
|
||||
## Performance Impact
|
||||
|
||||
- ✅ **No performance degradation** - All changes are CSS-only
|
||||
- ✅ **Smooth animations** - 150ms transitions feel responsive
|
||||
- ✅ **No layout shifts** - Size changes handled in CSS
|
||||
- ✅ **Minimal re-renders** - No JavaScript logic changes
|
||||
|
||||
---
|
||||
|
||||
## Maintenance Benefits
|
||||
|
||||
### Code Quality
|
||||
- ✅ **Reusable patterns** - Design tokens provide consistency
|
||||
- ✅ **Self-documenting** - Semantic color names clarify intent
|
||||
- ✅ **Easy to extend** - New buttons can use standard classes
|
||||
|
||||
### Consistency
|
||||
- ✅ **Uniform button styles** - All buttons follow same pattern
|
||||
- ✅ **Predictable spacing** - Standardized gaps and padding
|
||||
- ✅ **Cohesive design** - Color system maintains brand identity
|
||||
|
||||
---
|
||||
|
||||
## Next Steps (Optional Enhancements)
|
||||
|
||||
### Phase 2 Improvements (Not Implemented)
|
||||
These can be added later for additional polish:
|
||||
|
||||
1. **Loading states** - Skeleton screens for pattern loading
|
||||
2. **Micro-interactions** - Subtle animations on state changes
|
||||
3. **Responsive optimizations** - Mobile-specific touch targets
|
||||
4. **Dark mode support** - Alternative color scheme
|
||||
5. **Tooltip system** - Contextual help on hover
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
Successfully implemented **core UI/UX improvements** that enhance:
|
||||
- **Visual hierarchy** through better color usage and state indication
|
||||
- **Accessibility** with ARIA labels, focus states, and semantic HTML
|
||||
- **User feedback** via hover, active, and focus effects
|
||||
- **Design consistency** through design tokens system
|
||||
- **Maintainability** with reusable patterns and semantic naming
|
||||
|
||||
All changes are production-ready and maintain the compact, efficient design while significantly improving usability and professionalism.
|
||||
|
||||
**Estimated implementation time:** 2.5 hours
|
||||
**Actual completion:** Completed in session
|
||||
**Impact:** High - Improved usability, accessibility, and visual polish
|
||||
|
|
@ -1,434 +0,0 @@
|
|||
# SKiTCH Controller UI Improvements - Executive Summary
|
||||
|
||||
## Overview
|
||||
|
||||
I've completed a comprehensive UI/UX analysis of the SKiTCH Controller embroidery machine application and created detailed improvement recommendations across four documentation files.
|
||||
|
||||
---
|
||||
|
||||
## What I Analyzed
|
||||
|
||||
**Application Structure:**
|
||||
- React/TypeScript web app with Tailwind CSS v4
|
||||
- 7 main components across two-column layout
|
||||
- Workflow-driven interface for embroidery machine control
|
||||
- Integration of Heroicons and react-konva for canvas rendering
|
||||
|
||||
**Current State:**
|
||||
- Solid foundation with modern tech stack
|
||||
- Clean component architecture
|
||||
- Good basic functionality
|
||||
|
||||
**Areas Identified for Improvement:**
|
||||
- Inconsistent color usage (multiple blue shades)
|
||||
- Button states lacking polish
|
||||
- Typography hierarchy could be stronger
|
||||
- Accessibility gaps (focus states, touch targets)
|
||||
- Information density variations
|
||||
|
||||
---
|
||||
|
||||
## Documentation Deliverables
|
||||
|
||||
### 1. UI_DESIGN_ANALYSIS.md (Comprehensive Analysis)
|
||||
**Purpose:** Deep-dive analysis with full context and rationale
|
||||
|
||||
**Contents:**
|
||||
- Current state assessment (strengths & weaknesses)
|
||||
- 9 detailed improvement categories:
|
||||
1. Color System & Consistency
|
||||
2. Typography & Readability
|
||||
3. Spacing & Visual Hierarchy
|
||||
4. Button Design & Interaction States
|
||||
5. Component-Specific Improvements
|
||||
6. Accessibility Improvements
|
||||
7. Information Density & Whitespace
|
||||
8. Progress & Loading States
|
||||
9. Responsive Design Enhancements
|
||||
- Implementation priority phases
|
||||
- Complete code examples
|
||||
- Accessibility checklist
|
||||
- Design system specifications
|
||||
|
||||
**Best For:** Understanding the "why" behind recommendations
|
||||
|
||||
---
|
||||
|
||||
### 2. QUICK_UI_IMPROVEMENTS.md (Action Guide)
|
||||
**Purpose:** Fast-reference implementation guide
|
||||
|
||||
**Contents:**
|
||||
- 7 priority improvements with time estimates
|
||||
- Quick code snippets for each fix
|
||||
- Standard button class templates
|
||||
- Common pattern reference
|
||||
- Testing checklist
|
||||
- Impact summary
|
||||
|
||||
**Best For:** Quick implementation (2.5 hours total)
|
||||
|
||||
---
|
||||
|
||||
### 3. UI_BEFORE_AFTER_EXAMPLES.md (Visual Comparison)
|
||||
**Purpose:** Clear before/after code examples
|
||||
|
||||
**Contents:**
|
||||
- 8 detailed before/after comparisons:
|
||||
1. Button States (Primary Action)
|
||||
2. Color Block Status
|
||||
3. Section Headers
|
||||
4. Workflow Stepper
|
||||
5. Status Badges
|
||||
6. Canvas Overlays
|
||||
7. Pattern Information Display
|
||||
8. Progress Bars
|
||||
- Visual impact descriptions
|
||||
- Color token reference
|
||||
- Implementation order
|
||||
|
||||
**Best For:** Seeing concrete examples of each change
|
||||
|
||||
---
|
||||
|
||||
### 4. COMPONENT_IMPLEMENTATION_CHECKLIST.md (Step-by-Step)
|
||||
**Purpose:** Component-by-component implementation guide
|
||||
|
||||
**Contents:**
|
||||
- Setup instructions (design tokens)
|
||||
- Line-by-line changes for each component:
|
||||
- App.tsx
|
||||
- WorkflowStepper.tsx
|
||||
- MachineConnection.tsx
|
||||
- FileUpload.tsx
|
||||
- ProgressMonitor.tsx
|
||||
- PatternCanvas.tsx
|
||||
- NextStepGuide.tsx
|
||||
- Interactive checklists
|
||||
- Testing procedures
|
||||
- Time estimates per component
|
||||
- Common pitfalls to avoid
|
||||
- Success criteria
|
||||
|
||||
**Best For:** Systematic implementation with checkboxes
|
||||
|
||||
---
|
||||
|
||||
## Key Recommendations Summary
|
||||
|
||||
### 1. Semantic Color System
|
||||
**Problem:** Inconsistent blue shades (blue-600, blue-700, cyan-600) scattered throughout
|
||||
|
||||
**Solution:** Design tokens file with semantic colors
|
||||
```css
|
||||
--color-primary: #2563eb (actions)
|
||||
--color-success: #16a34a (complete)
|
||||
--color-warning: #d97706 (waiting)
|
||||
--color-danger: #dc2626 (errors)
|
||||
--color-info: #0891b2 (active)
|
||||
```
|
||||
|
||||
**Impact:** Consistent, meaningful color usage across entire app
|
||||
|
||||
---
|
||||
|
||||
### 2. Button State Improvements
|
||||
**Problem:**
|
||||
- Grayscale filter on disabled (looks unprofessional)
|
||||
- No press feedback
|
||||
- Missing focus states
|
||||
|
||||
**Solution:** Comprehensive button state system
|
||||
```tsx
|
||||
hover:bg-primary-light hover:shadow-md hover:scale-[1.02]
|
||||
active:bg-primary-dark active:scale-[0.98]
|
||||
focus:outline-none focus:ring-2 focus:ring-primary focus:ring-offset-2
|
||||
disabled:bg-neutral-300 disabled:text-neutral-500
|
||||
```
|
||||
|
||||
**Impact:** Professional, responsive, accessible buttons
|
||||
|
||||
---
|
||||
|
||||
### 3. Typography Scale
|
||||
**Problem:** Inconsistent sizes, some text too small (10px-11px)
|
||||
|
||||
**Solution:** Defined hierarchy
|
||||
```
|
||||
h1: text-2xl font-bold (24px)
|
||||
h2: text-xl font-semibold (20px)
|
||||
h3: text-base font-semibold (16px)
|
||||
h4: text-sm font-semibold (14px)
|
||||
body: text-sm (14px minimum)
|
||||
```
|
||||
|
||||
**Impact:** Better readability, clearer hierarchy
|
||||
|
||||
---
|
||||
|
||||
### 4. Visual Hierarchy Enhancement
|
||||
**Problem:** Color blocks don't clearly show current vs completed vs upcoming
|
||||
|
||||
**Solution:**
|
||||
- Larger swatches (24px vs 20px)
|
||||
- Ring + glow effect on current block
|
||||
- Thicker progress bar (6px vs 4px)
|
||||
- Scale animation (1.02x) on current
|
||||
- Clear icon indicators
|
||||
|
||||
**Impact:** Instantly see sewing progress at a glance
|
||||
|
||||
---
|
||||
|
||||
### 5. Accessibility Improvements
|
||||
**Problem:**
|
||||
- Small touch targets (32px)
|
||||
- Missing focus indicators
|
||||
- No ARIA labels on icon buttons
|
||||
- Color-only status indication
|
||||
|
||||
**Solution:**
|
||||
- Minimum 44px touch targets
|
||||
- Focus rings on all interactive elements
|
||||
- ARIA labels and roles
|
||||
- Icons + color for status
|
||||
|
||||
**Impact:** WCAG 2.1 AA compliant, better for all users
|
||||
|
||||
---
|
||||
|
||||
### 6. Workflow Stepper Enhancement
|
||||
**Problem:** Small, hard to read in header
|
||||
|
||||
**Solution:**
|
||||
- Larger circles (40px vs 32px)
|
||||
- Thicker progress line (4px vs 2px)
|
||||
- Bigger text (14px vs 12px)
|
||||
- Better contrast (blue-100 vs blue-300)
|
||||
- Shadow on current step
|
||||
|
||||
**Impact:** Clear progress indication, easier to read
|
||||
|
||||
---
|
||||
|
||||
### 7. Pattern Information Grid
|
||||
**Problem:** Single gray box with stacked info, can feel cramped
|
||||
|
||||
**Solution:** 2×2 grid with individual cards
|
||||
- File name, size, colors, stitches in separate cards
|
||||
- Clear label/value hierarchy
|
||||
- Better scannability
|
||||
|
||||
**Impact:** Professional stats display, easier to read
|
||||
|
||||
---
|
||||
|
||||
### 8. Canvas Overlay Unification
|
||||
**Problem:** Mixed styling across overlays
|
||||
|
||||
**Solution:** Unified design
|
||||
```tsx
|
||||
bg-white/98 backdrop-blur-sm
|
||||
rounded-xl shadow-lg
|
||||
border border-neutral-200
|
||||
```
|
||||
|
||||
**Impact:** Cohesive, polished interface
|
||||
|
||||
---
|
||||
|
||||
## Implementation Approach
|
||||
|
||||
### Quick Win (1.5 hours)
|
||||
Focus on highest impact:
|
||||
1. Design tokens setup
|
||||
2. Button states (all components)
|
||||
3. Color blocks enhancement
|
||||
4. Workflow stepper
|
||||
|
||||
### Standard (2.5 hours)
|
||||
Add medium-priority items:
|
||||
5. Typography fixes
|
||||
6. Pattern info grid
|
||||
7. Canvas overlay unity
|
||||
8. Testing
|
||||
|
||||
### Complete (3.5 hours)
|
||||
Full implementation:
|
||||
9. All accessibility features
|
||||
10. Responsive optimizations
|
||||
11. Polish details
|
||||
12. Comprehensive testing
|
||||
|
||||
---
|
||||
|
||||
## Expected Outcomes
|
||||
|
||||
### User Experience
|
||||
- **Clarity:** Stronger visual hierarchy makes workflow obvious
|
||||
- **Feedback:** Button states provide clear interaction feedback
|
||||
- **Accessibility:** Keyboard navigation, screen readers work properly
|
||||
- **Professionalism:** Polished, cohesive design inspires confidence
|
||||
|
||||
### Developer Experience
|
||||
- **Consistency:** Semantic colors make code more maintainable
|
||||
- **Reusability:** Standard button classes reduce repetition
|
||||
- **Clarity:** Design tokens document intent
|
||||
|
||||
### Business Value
|
||||
- **Trust:** Professional UI increases user confidence
|
||||
- **Adoption:** Better UX reduces learning curve
|
||||
- **Accessibility:** WCAG compliance expands user base
|
||||
- **Maintenance:** Consistent system reduces design debt
|
||||
|
||||
---
|
||||
|
||||
## Color Before/After Comparison
|
||||
|
||||
### Before (Inconsistent)
|
||||
```tsx
|
||||
bg-blue-600, bg-blue-700, bg-cyan-600
|
||||
text-blue-900, text-blue-800, text-gray-600
|
||||
border-gray-300, border-blue-600
|
||||
```
|
||||
|
||||
### After (Semantic)
|
||||
```tsx
|
||||
bg-primary, bg-primary-dark, bg-info
|
||||
text-primary, text-neutral-900, text-neutral-600
|
||||
border-neutral-300, border-primary
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
### Visual Testing
|
||||
- All states (hover, active, focus, disabled)
|
||||
- Color consistency across components
|
||||
- Spacing and alignment
|
||||
|
||||
### Interaction Testing
|
||||
- Keyboard navigation (Tab key)
|
||||
- Button press feedback
|
||||
- Touch targets on mobile
|
||||
- Zoom controls responsiveness
|
||||
|
||||
### Accessibility Testing
|
||||
- Screen reader compatibility
|
||||
- Color contrast ratios
|
||||
- Focus indicator visibility
|
||||
- ARIA attribute correctness
|
||||
|
||||
### Responsive Testing
|
||||
- Mobile (single column)
|
||||
- Tablet (grid breakpoint)
|
||||
- Desktop (full layout)
|
||||
- WorkflowStepper readability
|
||||
|
||||
---
|
||||
|
||||
## File Organization
|
||||
|
||||
```
|
||||
C:\Users\micro\Documents\dev\respira-web\
|
||||
├── UI_DESIGN_ANALYSIS.md (Comprehensive analysis)
|
||||
├── QUICK_UI_IMPROVEMENTS.md (Fast reference)
|
||||
├── UI_BEFORE_AFTER_EXAMPLES.md (Visual comparisons)
|
||||
├── COMPONENT_IMPLEMENTATION_CHECKLIST.md (Step-by-step guide)
|
||||
└── UI_IMPROVEMENTS_SUMMARY.md (This file)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Review Documentation**
|
||||
- Read UI_DESIGN_ANALYSIS.md for full context
|
||||
- Scan QUICK_UI_IMPROVEMENTS.md for overview
|
||||
- Check UI_BEFORE_AFTER_EXAMPLES.md for specifics
|
||||
|
||||
2. **Setup Foundation**
|
||||
- Create design tokens file
|
||||
- Import into App.css
|
||||
- Test token availability
|
||||
|
||||
3. **Choose Approach**
|
||||
- Quick win: 1.5 hours for major impact
|
||||
- Standard: 2.5 hours for comprehensive update
|
||||
- Complete: 3.5 hours for full polish
|
||||
|
||||
4. **Implement Components**
|
||||
- Follow COMPONENT_IMPLEMENTATION_CHECKLIST.md
|
||||
- Check off items as completed
|
||||
- Test after each component
|
||||
|
||||
5. **Final Testing**
|
||||
- Run through all test categories
|
||||
- Verify success criteria met
|
||||
- Document any deviations
|
||||
|
||||
---
|
||||
|
||||
## Maintenance Recommendations
|
||||
|
||||
**After Implementation:**
|
||||
|
||||
1. **Document Design System**
|
||||
- Create Storybook or component library
|
||||
- Document button variants
|
||||
- Record spacing scale
|
||||
|
||||
2. **Establish Guidelines**
|
||||
- When to use each color
|
||||
- Button hierarchy rules
|
||||
- Spacing conventions
|
||||
|
||||
3. **Review Process**
|
||||
- New components use design tokens
|
||||
- PRs check for consistency
|
||||
- Accessibility tested for new features
|
||||
|
||||
4. **Future Enhancements**
|
||||
- Dark mode support
|
||||
- Theme customization
|
||||
- Animation refinements
|
||||
- Performance optimization
|
||||
|
||||
---
|
||||
|
||||
## Questions & Support
|
||||
|
||||
**If you need:**
|
||||
- **Detailed rationale** → Read UI_DESIGN_ANALYSIS.md
|
||||
- **Quick implementation** → Use QUICK_UI_IMPROVEMENTS.md
|
||||
- **Code examples** → See UI_BEFORE_AFTER_EXAMPLES.md
|
||||
- **Step-by-step guide** → Follow COMPONENT_IMPLEMENTATION_CHECKLIST.md
|
||||
- **Overview** → This file (UI_IMPROVEMENTS_SUMMARY.md)
|
||||
|
||||
---
|
||||
|
||||
## Summary Statistics
|
||||
|
||||
- **Components Analyzed:** 7
|
||||
- **Files Created:** 4 documentation files
|
||||
- **Improvement Categories:** 9
|
||||
- **Code Examples:** 30+
|
||||
- **Estimated Implementation Time:** 2.5 hours (standard)
|
||||
- **Expected Impact:** High (usability, accessibility, professionalism)
|
||||
|
||||
---
|
||||
|
||||
## Final Thoughts
|
||||
|
||||
The SKiTCH Controller has a strong technical foundation. These UI improvements will elevate the user experience to match the technical quality, creating a professional, accessible, and delightful interface for embroidery machine control.
|
||||
|
||||
The improvements are incremental and can be implemented in phases, allowing you to balance effort with impact. Even the quick-win approach (1.5 hours) will make a significant difference.
|
||||
|
||||
All changes maintain the compact, efficient design suitable for technical users while enhancing clarity, consistency, and accessibility.
|
||||
|
||||
---
|
||||
|
||||
**Documentation created by:** UI Designer Agent
|
||||
**Date:** 2025-12-06
|
||||
**Project:** SKiTCH Controller - Respira Web
|
||||
**Status:** Ready for implementation
|
||||
BIN
docs/main_screenshot.png
Normal file
BIN
docs/main_screenshot.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 259 KiB |
Loading…
Reference in a new issue