diff --git a/README.md b/README.md new file mode 100644 index 0000000..3b23317 --- /dev/null +++ b/README.md @@ -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. + +![](./docs/main_screenshot.png) + +## 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. \ No newline at end of file diff --git a/build/.gitkeep b/build/.gitkeep deleted file mode 100644 index d0756ba..0000000 --- a/build/.gitkeep +++ /dev/null @@ -1,5 +0,0 @@ -# Placeholder for build resources -# Add your icon files here: -# - icon.ico (Windows, 256x256) -# - icon.icns (macOS) -# - icon.png (Linux, 512x512) diff --git a/docs/QUICK_UI_IMPROVEMENTS.md b/docs/QUICK_UI_IMPROVEMENTS.md deleted file mode 100644 index 7adaf07..0000000 --- a/docs/QUICK_UI_IMPROVEMENTS.md +++ /dev/null @@ -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 -
{/* was text-xs */} -``` - -**ProgressMonitor.tsx:** -```tsx -// Line 169: Larger thread labels - {/* was unlabeled size */} - -// Line 179: More readable stitch counts - {/* was text-xs */} -``` - -**PatternCanvas.tsx:** -```tsx -// Line 278: Clearer thread legend text -Thread {index + 1} {/* was text-xs */} -``` - ---- - -## Priority 4: Spacing Consistency (15 minutes) - -### Standard Card Padding - -**Apply to all card components:** - -```tsx -// Standard card -
- -// Compact card (ProgressMonitor) -
-``` - -### Standard Section Spacing - -```tsx -// Between major sections -
- -// Within sections -
- -// Within subsections -
- -// Tight grouping -
-``` - -### Quick Fixes - -**App.tsx:** -```tsx -// Line 126: Increase main grid gap -
{/* was gap-6 */} - -// Line 128: Standard spacing in left column -
-``` - -**ProgressMonitor.tsx:** -```tsx -// Line 116: Better grid gap -
{/* was gap-4 */} - -// Line 143: Better color block spacing -
{/* was gap-2 */} -``` - ---- - -## Priority 5: Visual Hierarchy (20 minutes) - -### Section Headers - -**Replace all section headers:** - -```tsx -// OLD -

- -// NEW -
-

Pattern Preview

-
-``` - -### Color Block Enhancement - -**ProgressMonitor.tsx - Lines 157-191:** - -```tsx -
-
-
- - Thread {block.colorIndex + 1} - - {/* Status icons */} - {isCompleted && } - {isCurrent && } - {!isCompleted && !isCurrent && } - - {block.stitchCount.toLocaleString()} - -
- {/* Progress bar */} - {isCurrent && ( -
-
-
- )} -
-``` - ---- - -## Priority 6: Accessibility Quick Wins (15 minutes) - -### Add ARIA Labels to Icon Buttons - -**PatternCanvas.tsx - Zoom controls:** - -```tsx - - - - - -``` - -### Increase Touch Targets - -**All icon buttons:** - -```tsx -// Change from w-8 h-8 to w-10 h-10 - -``` - -**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 - -``` - -**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 -
-
-
- - Thread {block.colorIndex + 1} - - {isCompleted ? : null} - {isCurrent ? : null} - {!isCompleted && !isCurrent ? : null} - - {block.stitchCount.toLocaleString()} - -
- {isCurrent && ( -
-
-
- )} -
-``` - -**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 -
-
-
- - Thread {block.colorIndex + 1} - - {isCompleted && } - {isCurrent && } - {!isCompleted && !isCurrent && } - - {block.stitchCount.toLocaleString()} - -
- {isCurrent && ( -
-
-
- )} -
-``` - -**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 -

- Pattern Preview -

-``` - -**Issues:** -- Heavy bottom border (2px) but weak separation -- Border too dark (gray-300) -- Font weight only semibold (not bold) -- No container grouping - -### AFTER -```tsx -
-

Pattern Preview

-
-``` - -**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 */} -
-
- -{/* Step circles */} -
- {isComplete ? : step.id} -
- -{/* Labels */} -
- {step.label} -
-``` - -**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 */} -
-
- -{/* Step circles - larger */} -
- {isComplete ? : step.id} -
- -{/* Labels - larger, better contrast */} -
- {step.label} -
-``` - -**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 - - {stateVisual.icon} - {machineStatusName} - -``` - -**Issues:** -- No border (looks flat) -- Minimal padding -- No explicit inline-flex - -### AFTER -```tsx - - {stateVisual.icon} - {machineStatusName} - -``` - -**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 */} -
-

- Threads -

- {/* ... */} -
- -{/* Zoom Controls */} -
- - {/* ... */} -
-``` - -**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 */} -
-

Threads

- {pesData.threads.map((thread, index) => ( -
-
- Thread {index + 1} -
- ))} -
- -{/* Zoom Controls - larger touch targets */} -
- -
- {zoom}% -
- - -
-``` - -**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 -
-
- File Name: - {displayFileName} -
-
- Pattern Size: - {size} -
- {/* ... */} -
-``` - -**Issues:** -- All in one gray box (low hierarchy) -- Labels and values on same line (can overflow) -- Tight spacing - -### AFTER -```tsx -
-
-
File Name
-
- {displayFileName} -
-
-
-
Size
-
{size} mm
-
-
-
Colors
-
{pesData.colorCount}
-
-
-
Stitches
-
{pesData.stitchCount.toLocaleString()}
-
-
-``` - -**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 -
-
-
-``` - -**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 */} -
-
-
-
-
-``` - -**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 diff --git a/docs/UI_DESIGN_ANALYSIS.md b/docs/UI_DESIGN_ANALYSIS.md deleted file mode 100644 index 9773cb8..0000000 --- a/docs/UI_DESIGN_ANALYSIS.md +++ /dev/null @@ -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 -
- -// Recommended: Larger, more readable -
-``` - -**ProgressMonitor - Color Blocks:** -```tsx -// Current: text-xs for thread labels - - -// Recommended: Slightly larger for better scannability - -``` - -**PatternCanvas - Overlays:** -```tsx -// Current: Mixed sizes (10px, 11px, 13px) -
-
- -// Recommended: Use consistent scale -
// 12px -
// 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) -

- -// Recommended (stronger presence) -
-

Pattern Preview

-
-``` - -**ProgressMonitor Layout Enhancement:** -```tsx -// Current: Grid with generic gaps -
- -// Recommended: Better defined sections -
-
...
{/* Left column */} -
...
{/* Right column */} -
-``` - ---- - -### 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 - -``` - ---- - -### 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 -
{/* was w-8 h-8 */} - -// Stronger progress line -
{/* was h-0.5 */} -
{/* was h-0.5 */} - -// Better color contrast for text -
-``` - -#### 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 - - -// Clearer machine info layout -
-
- Model: - {machineInfo.modelNumber} -
- ... -
- -// More prominent auto-refresh indicator - - - Auto-refreshing - -``` - -#### 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 -
- -// Stronger current block highlighting -
- -// More prominent block progress bar -
{/* was h-1 */} -
-
-``` - -#### 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 - {/* was w-8 h-8 */} - -// Add subtle shadow for depth -
- -// Enhance list item styling -
    -
  • Press the button...
    • -
-``` - -#### 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 -
- -// Grouped zoom controls with better spacing -
- -
{/* Separator */} - {zoom}% -
- - -
- -// Cleaner pattern offset display -
-
Position
-
- X: {x}mm Y: {y}mm -
-
-``` - ---- - -### 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 - -``` - ---- - -### 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 -
- -// Recommended: Use grid for better scannability -
-
-
File Name
-
{fileName}
-
-
-
Size
-
{size} mm
-
-
-
Colors
-
{colors}
-
-
-
Stitches
-
{stitches}
-
-
-``` - -**Consistent Card Padding:** -```tsx -// Standard card wrapper -
-``` - ---- - -### 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 -
-
- {/* Shimmer effect */} -
-
-
-``` - -**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 ( -
- ); -} - -// Use in FileUpload -{isLoading && ( -
- - Loading pattern... -
-)} -``` - ---- - -### 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 -
{step.label}
-
{step.id}
-``` - -**ProgressMonitor Responsive Grid:** -```tsx -// Better mobile stacking -
- {/* Color blocks: scrollable on mobile */} -
- {/* Color blocks */} -
-
-``` - ---- - -## 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 - -``` - -**After:** -```tsx - -``` - -### Example 2: Updated Color Block Design - -**Before:** -```tsx -
-``` - -**After:** -```tsx -
-
{/* increased gap */} -
- Thread {block.colorIndex + 1} - {isCompleted && } - {isCurrent && } - {!isCompleted && !isCurrent && } - {block.stitchCount.toLocaleString()} -
- {isCurrent && ( -
-
-
- )} -
-``` - ---- - -## 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. diff --git a/docs/UI_IMPROVEMENTS.md b/docs/UI_IMPROVEMENTS.md deleted file mode 100644 index 50fae5f..0000000 --- a/docs/UI_IMPROVEMENTS.md +++ /dev/null @@ -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 diff --git a/docs/UI_IMPROVEMENTS_IMPLEMENTED.md b/docs/UI_IMPROVEMENTS_IMPLEMENTED.md deleted file mode 100644 index 85fd822..0000000 --- a/docs/UI_IMPROVEMENTS_IMPLEMENTED.md +++ /dev/null @@ -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 diff --git a/docs/UI_IMPROVEMENTS_SUMMARY.md b/docs/UI_IMPROVEMENTS_SUMMARY.md deleted file mode 100644 index 52d8b02..0000000 --- a/docs/UI_IMPROVEMENTS_SUMMARY.md +++ /dev/null @@ -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 diff --git a/docs/main_screenshot.png b/docs/main_screenshot.png new file mode 100644 index 0000000..7087206 Binary files /dev/null and b/docs/main_screenshot.png differ