# Schaeffler Automat — UX & Quality Audit Report
**Date**: 2026-03-08
**Overall Score**: 6.5/10

---

## Executive Summary

Schaeffler Automat is a functionally complete internal tool with a solid design system foundation (semantic CSS variables, Tailwind tokens, dark/light theming, role-aware navigation). The core workflows — Excel import → STEP upload → render dispatch — are implemented end-to-end. However, the UI suffers from **information density without hierarchy**: the Admin page is an undifferentiated ~3000px scroll, the Upload wizard has no progress indicator, and the Activity page mixes live queue data with historical records without clear separation. The most impactful improvements are a redesigned Admin hub with tab navigation, an Upload wizard progress bar, and standardized interaction patterns (replacing `window.confirm()`, adding debounce to search, and skeleton loading states).

---

## Critical Issues 🔴

### 1. Admin Page — No Section Navigation
The `/admin` page contains 10+ distinct sections (Pricing, Users, Blender Settings, GPU Probe, 3D Viewer, Tessellation, SMTP, Render Templates, Output Types, Pricing Tiers, Asset Libraries, Admin Actions) in a single vertical scroll. On a 1080p screen, users must scroll ~3000px to reach lower sections. Sections below the fold are effectively invisible to new users.

**Fix**: Tab-based navigation grouping: **Settings** / **Users** / **Render** / **Templates** / **Pricing** / **Actions**

### 2. Upload Wizard — No Step Progress Indicator
The 4-step Excel import flow (Drop → Match Report → Output Type Selection → STEP Upload) has no visible step counter or breadcrumb. Users don't know which step they're on, how many remain, or whether they can go back. This is the primary workflow for adding work to the system.

**Fix**: Add `<StepIndicator step={n} total={4} labels={['Upload', 'Review', 'Configure', 'STEP Files']} />` above the wizard content.

### 3. Login Page — Hardcoded `bg-white` Card Breaks Dark Mode
The login card uses `bg-white` instead of `bg-surface`, appearing as a jarring white box on the dark theme.

**Fix**: Replace `bg-white` with `bg-surface` in `Login.tsx`.

### 4. Badge/Category Colors Not Dark-Mode Safe
Color-coded category badges use hardcoded Tailwind light-mode classes (`bg-blue-100 text-blue-700`) with no dark mode adaptation. In dark mode these create incorrect contrast ratios.

**Fix**: Create semantic `.badge-category` variants in `index.css` using CSS variables, or use the existing `.badge-blue`, `.badge-green` etc. that already reference design tokens.

---

## Major Improvements 🟠

### 5. Floating Action Bars Use Hardcoded Sidebar Offset
Both `Orders.tsx` and `ProductLibrary.tsx` use `ml-[120px]` (half of 240px sidebar) to center bulk-delete action bars. This breaks if the sidebar width changes or on split-screen views.

**Fix**:
```tsx
// Replace ml-[120px] with proper centering:
style={{ left: 'calc(240px + (100vw - 240px) / 2)', transform: 'translateX(-50%)' }}
```

### 6. Product Library — Immediate Search, 200-Item Hard Cap
Search fires on every keystroke without debounce, potentially triggering 10+ API calls per typed word. A hard limit of 200 products means large libraries are silently truncated with no indication.

**Fix**: Add 300ms debounce to the search `onChange`. Add cursor-based pagination (24/48/96 per page) with prev/next buttons.

### 7. `window.confirm()` vs. `ConfirmModal` Inconsistency
The Activity page's "Purge All Queue" action uses native `window.confirm()`, breaking visual consistency with the custom `ConfirmModal` component used everywhere else for destructive actions.

**Fix**: Replace all `window.confirm()` calls with `<ConfirmModal>`.

### 8. German "Anpassen" Label in English UI
The Dashboard customize button reads "Anpassen" — the only German string in an otherwise English interface.

**Fix**: Rename to "Customize" or "Edit Widgets".

### 9. Submitted Orders Deletable Without Extra Warning
Bulk delete allows selecting `submitted` status orders. Deleting submitted orders (potentially being processed) shows the same confirmation as deleting drafts.

**Fix**: Show a stronger warning: *"⚠️ N orders have been submitted and may be processing. Delete anyway?"*

### 10. Admin — Multiple Section-Level Save Buttons with Unclear Scope
Four independent draft objects (`blenderDraft`, `viewerDraft`, `tessellationDraft`, `smtpDraft`) each have a save button that only appears when changes exist. Users may save one section without realizing another has unsaved changes.

**Fix**: Add a persistent "Unsaved changes in: Blender Settings, SMTP" notification banner at the top with a "Save All" option.

### 11. Kanban View — No Horizontal Scroll Affordance on Mobile
The 5-column kanban (each 280px+ wide = 1400px+ total) silently overflows on narrow screens. Mobile users see a cut-off view with no hint to scroll horizontally.

**Fix**: Auto-switch to list view when `window.innerWidth < 768`. Add a horizontal scroll hint (fade gradient at edges) on small desktops.

### 12. Dashboard Widgets — 15 Independent API Calls on Load
Each dashboard widget fetches data independently on mount, creating 15 simultaneous API requests and a cascade of skeleton → content transitions.

**Fix**: Batch widget data into a single `/api/dashboard/data?widgets=...` endpoint. Or stagger widget loading with short delays to avoid request flood.

---

## Minor Refinements 🟡

### 13. Login — No Password Visibility Toggle, No Return URL Redirect
No eye icon to show/hide password. After login, always redirects to `/` instead of the originally requested URL.

**Fix**: Add `<Eye>/<EyeOff>` icon button. Capture `location.state.from` and redirect post-login.

### 14. Activity Page — Blender Log Fixed Max Height
The Blender stdout log panel has `max-h-64` (256px), creating a scroll-within-a-scroll for long logs.

**Fix**: Add "Expand log" toggle that removes the max-height constraint.

### 15. Sidebar — Admin-Only Links Not Visually Separated
Admin-only items (Notification Settings, Tenants) are visually mixed with project_manager-accessible items, making role distinction unclear.

**Fix**: Add a small "Admin Only" section label above the admin-exclusive links.

### 16. Upload Wizard — Step 3 JSX Appears After Step 4 in Source
`Upload.tsx` renders Step 3 (Output Type Selection) JSX after Step 4 (STEP Upload) in the source file, creating a maintenance hazard.

**Fix**: Reorder JSX blocks to match display order: Step 1 → 2 → 3 → 4.

### 17. Upload — "Gew. Produkt" Column Has No Tooltip
The abbreviated German column header is not explained. New operators won't know this means "Gewähltes Produkt" (Selected Product).

**Fix**: Add `<HelpTooltip text="Gewähltes Produkt — the specific product variant selected in the Excel file" />` next to the column header.

### 18. Media Browser — Fragmented Filter UI
Two separate filter areas exist: "Media type" segmented tabs and "Technical types" checkboxes. Their relationship is visually unclear.

**Fix**: Group all filters under a unified collapsible "Filters" panel with labeled sub-groups.

### 19. Product Library — No Sort Controls
Products can be filtered but not sorted (by name, PIM-ID, date, or render status).

**Fix**: Add sort dropdown: "Sort: Newest / A–Z / Status".

### 20. No Skeleton Loading States on Key Pages
Orders list, Product library, and Activity page show empty state or nothing briefly before data arrives, causing layout shift.

**Fix**: Add skeleton rows/cards matching the expected content shape on first load.

---

## Wins ✅

- **Theme system is production-grade**: CSS variable tokens + Tailwind semantic classes + `localStorage` persistence + system preference detection + flash prevention in `main.tsx` before React hydration.
- **Role-aware navigation**: Privileged links correctly hidden from clients; admin sections conditionally rendered.
- **Order kanban progress bars**: Color-coded segments (green/blue/red/orange/gray) give instant visual feedback on render completion state.
- **Notification Center**: Bell dropdown with badge, portal rendering, unread count, relative timestamps, and 15s polling — complete and polished.
- **Hover-to-play video thumbnails**: Both `OrderDetail` and `ProductDetail` have smooth hover-to-play with play icon overlay — good progressive disclosure.
- **Upload validation dialog**: Traffic-light summary with per-row issues and "Save as alias" is a sophisticated, context-aware feature.
- **Activity expand rows**: Full timing breakdown, renderer settings, part count, and syntax-colored Blender log are invaluable for debugging.
- **Excel import wizard**: Header-driven column detection handles format variance gracefully.
- **Render template system**: Lighting-only mode, shadow catcher, material replacement — powerful and well-integrated.
- **STL cache convention**: Prevents repeated STEP→STL conversions on re-renders.

---

## Prioritized Recommendation List

| Priority | Area | Issue | Suggestion | Effort |
|----------|------|--------|------------|--------|
| 1 | Admin | 3000px undifferentiated scroll | Tab navigation: Settings / Users / Render / Templates / Pricing / Actions | Medium |
| 2 | Upload | No step progress indicator | Add `<StepIndicator>` component above wizard | Low |
| 3 | Login | `bg-white` breaks dark mode | Replace with `bg-surface` CSS token | Low |
| 4 | Global | Category badges not dark-mode safe | Use semantic badge classes with CSS variables | Low |
| 5 | Orders | Submitted orders deletable without warning | Split confirmation messages by status | Low |
| 6 | Products | Search fires on every keystroke | Add 300ms debounce | Low |
| 7 | Products | 200-item hard cap with no pagination | Add cursor-based pagination | Medium |
| 8 | Activity | `window.confirm()` in queue purge | Replace with `ConfirmModal` | Low |
| 9 | Global | Floating bars use hardcoded `ml-[120px]` | Fix with CSS calc centering | Low |
| 10 | Dashboard | "Anpassen" German label | Rename to "Customize" | Low |
| 11 | Orders | Kanban unusable on mobile | Auto-switch to list view < 768px | Low |
| 12 | Login | No password toggle, no return URL | Add Eye icon + capture return URL | Low |
| 13 | Admin | Multiple save buttons unclear scope | Add "Unsaved changes" banner | Low |
| 14 | Products | No sort controls | Add sort dropdown | Low |
| 15 | Global | No skeleton loading on key pages | Add skeletons to Orders, Products, Activity | Medium |
| 16 | Activity | Blender log 256px fixed height | Add "Expand log" toggle | Low |
| 17 | Sidebar | Admin-only links not separated | Add "Admin Only" section label | Low |
| 18 | Media | Fragmented filter UI | Unified collapsible filters panel | Medium |
| 19 | Dashboard | 15 independent API calls on load | Batch widget data endpoint | High |
| 20 | Upload | Step 3 JSX after Step 4 in source | Reorder JSX blocks | Low |

---

## Theme & Visual Consistency Report

**Overall**: Strong foundation with CSS custom properties driving all surfaces, text, borders, and status colors.

### Light Theme ✅
Surfaces differentiated in 4 levels (`bg-app` → `bg-surface` → `bg-surface-alt` → `bg-muted`). Text in 3 weights. Status colors (success green, warning amber, error red, info blue) correctly use bg+text pairs.

### Dark Theme ✅ (with caveat)
Dark mode applies slate palette correctly. CSS variables swap on `<html class="dark">`. Flash prevention in `main.tsx` synchronously reads localStorage before React hydration.

**Issues in dark mode**:
- Login card: `bg-white` hardcoded — white box on dark background (**fix: `bg-surface`**)
- Category badges: `bg-blue-100 text-blue-700` etc. — wrong contrast in dark mode (**fix: semantic badge classes**)
- Some inline Tailwind classes in pages bypass the design token system

### Component Consistency
- **Buttons**: `.btn-primary/.btn-secondary/.btn-danger` defined in `index.css` — consistent ✅
- **Cards**: `.card` class used consistently ✅
- **Badges**: Mixed — `.badge-green/.badge-blue` semantic classes exist but not always used; raw Tailwind color classes appear throughout pages
- **Inputs**: `.input-base` defined but pages sometimes use inline `border border-border-default rounded-md px-3 py-2` directly — minor inconsistency
- **Modals**: Single `Modal.tsx` component used consistently ✅

### Accent Color System
5 presets (green/blue/purple/amber/teal) applied via `data-accent` on `<html>`. Applied to: active nav links, primary buttons, checkboxes, focus rings, status indicators. Consistent ✅.

---

## Functional QA Report

### Modal & Dialog Behavior
- `Modal.tsx`: Escape to close ✅, backdrop click to close ✅, size variants ✅, focus handling ✅
- `ConfirmModal.tsx`: Focus trapping ✅, Tab/Shift-Tab cycling ✅, Escape to cancel ✅
- `window.confirm()` in queue purge: Inconsistent ❌ — replace with ConfirmModal

### Form Validation
- Excel upload: File type validated pre-submit ✅
- User creation: No password strength indicator ❌
- Output type checkboxes in Upload Step 3: No indeterminate state for partially-checked columns ❌

### Loading & Error States
| Page | Loading State | Error State |
|------|--------------|-------------|
| Dashboard | Skeleton ✅ | Toast ✅ |
| Orders | None ❌ | Toast ✅ |
| Products | None ❌ | Empty state ✅ |
| Activity | None ❌ | Toast ✅ |
| Upload | Spinner on file parse ✅ | Inline validation ✅ |
| Admin | None ❌ | Toast ✅ |

### Keyboard Navigation
- Sidebar: Tab-navigable, Enter activates ✅
- Modals: Focus trapped ✅
- Kanban cards: Click-only, no keyboard activation ❌
- Data tables: Tab through rows not supported ❌

### 404 Handling
No custom 404 page — unknown routes redirect to `/` silently. **Fix**: Add a `*` catch-all route with a friendly "Page not found" component.

---

## Mobile Report

### Responsive Layout
- Sidebar: Correctly collapses to drawer on mobile ✅
- Fixed mobile header: `h-12` with hamburger + app name + notification bell ✅
- Breakpoint: Tailwind `md` (768px)

### Issues
| Issue | Severity | Location |
|-------|----------|----------|
| Kanban 5 columns = 1400px+ wide, no mobile adaptation | High | Orders.tsx |
| Table checkboxes 16×16px (min 44×44px touch target) | High | Orders, Products table views |
| Upload Step 3 output type table requires horizontal scroll on mobile | Medium | Upload.tsx |
| Search placeholder text clipped on 320px screens | Low | Multiple pages |
| Admin page is ~5000px scroll on mobile with no section navigation | High | Admin.tsx |

### Touch Target Audit
- NavLink items: Full-width ~40px height — ✅ adequate
- "New Order" CTA button: Full-width 48px — ✅ correct
- Table checkboxes: 16×16px — ❌ too small
- Filter chips: ~32px height — ⚠️ borderline (minimum 44px recommended)
- Kanban "Open →" text link: Small — ❌ too small for touch

---

## User Flow Efficiency Report

### Flow 1: Excel Import → Dispatch Renders (Primary Workflow)
| Step | Action |
|------|--------|
| 1 | Sidebar → Upload |
| 2 | Drop Excel file |
| 3 | Review product matches |
| 4 | Select output types |
| 5 | "Create Order" button |
| 6 | Upload STEP files (or skip) |
| 7 | Navigate to created order |
| 8 | Click "Dispatch Renders" |

**Total**: 8 steps across 2 page transitions. **Verdict**: Reasonable. Biggest friction = no step indicator (users don't know where they are in Step 3).

### Flow 2: Re-render Failed Job
| Step | Action |
|------|--------|
| 1 | Notice failure in Activity or Dashboard |
| 2 | Click order link in Activity row |
| 3 | Find failed render line |
| 4 | Click retry button |

**Total**: 4 steps. **Verdict**: Good — direct links from Activity to orders work well. Could add "Retry All Failed" bulk action.

### Flow 3: Change Renderer Settings
| Step | Action |
|------|--------|
| 1 | Sidebar → Admin |
| 2 | Scroll to "Blender Render Settings" (~400px) |
| 3 | Change setting |
| 4 | Wait for save button to appear |
| 5 | Click Save |

**Total**: 5 steps. **Friction**: Step 2 scroll discovery. With tab navigation, this becomes 4 steps with zero scroll.

### Flow 4: Find Product by PIM-ID
| Step | Action |
|------|--------|
| 1 | Sidebar → Products |
| 2 | Type PIM-ID in search |
| 3 | Click product card |

**Total**: 3 steps. **Verdict**: Efficient ✅.

### Flow 5: Add Material Alias After Render Failure
| Step | Action |
|------|--------|
| 1 | Notice wrong material in Activity |
| 2 | Sidebar → Materials |
| 3 | Find material by name |
| 4 | Expand material row |
| 5 | Click "+" / type alias / Enter |

**Total**: 5 steps. **Improvement**: "Add alias for: [part_name]" shortcut directly from Activity row detail would save 3 steps.

---

## Performance Observations

### API Call Pattern
- Dashboard: 15 independent widget API calls on mount — waterfall of loaders
- Activity: Every 5s polling — appropriate for live monitoring
- Notifications: Every 15s polling — appropriate
- Products: Immediate search (no debounce) — excessive API calls while typing

### Image Loading
- Thumbnails: `Cache-Control: max-age=3600` ✅
- Product grid: No `loading="lazy"` on 200 simultaneous thumbnail requests ❌ — **Fix**: Add `loading="lazy"` to all thumbnail `<img>` tags
- Videos: `preload="metadata"` correctly loads only first frame ✅

### Layout Shift
- Dashboard: Widget skeleton height → actual content causes shift
- Products: Empty state → full grid shift (no skeleton)
- Activity: Stats cards appear before timeline rows

### Optimistic UI Opportunities
| Action | Current | Optimistic |
|--------|---------|------------|
| Mark notification read | Wait for API | Decrement badge immediately |
| Bulk delete orders | Wait for all deletes | Remove from list immediately |
| Submit order | Wait for response | Show "submitted" badge immediately |

### Blocking Interactions
- "Dispatch Renders" button: Correctly disabled during dispatch with loading spinner ✅
- "Save Settings" button: No loading state during save — button disappears on success (draft resets) which feels abrupt. **Fix**: Show spinner in button during save, then confirm with a brief checkmark before disappearing.

---

*Report generated 2026-03-08 via codebase analysis.*
*Next: Implement Priority 1 (Admin tabs) and Priority 2 (Upload step indicator) first for maximum UX impact.*
