pi-pm3/UI_GUIDELINES.md

# Dangerous Pi - UI/UX Guidelines

## Design Philosophy

**Mobile-First, Resource-Constrained Excellence**: Build a beautiful, touch-optimized interface that works perfectly on smartphones while respecting the Pi Zero 2 W's limited resources.

### Core Principles

1. **Mobile-First** - PRIMARY target is smartphone users (📱 80% of usage)
2. **Touch-Optimized** - 44×44px minimum touch targets, gesture support
3. **Performance First** - Every byte counts, code splitting for charts
4. **Progressive Enhancement** - Works without JavaScript, better with it
5. **Cross-Platform** - Shared components for Web/Mobile/Desktop apps
6. **Instant Feedback** - Users should never wonder what's happening

---

## Technical Constraints

### Hardware Limitations
- **CPU**: Quad-core ARM Cortex-A53 @ 1GHz (limited)
- **RAM**: 512MB (shared with OS and backend)
- **Network**: WiFi only, potentially slow AP mode
- **Storage**: MicroSD (minimize writes)

### Performance Targets
- **First Contentful Paint**: < 1.5s
- **Time to Interactive**: < 3s
- **Base Bundle Size**: ~120KB (gzipped)
- **With Victory Charts**: ~170KB (via code splitting)
- **CSS**: < 20KB (gzipped)
- **Fonts**: System fonts only (no web fonts)

### Mobile-First Targets
- **Viewport**: 375px width (iPhone SE) as baseline
- **Touch Targets**: 44×44px minimum (iOS HIG)
- **Gesture Support**: Pan, zoom, swipe for charts
- **Orientation**: Portrait primary, landscape support

---

## Visual Design System

### Color Palette

```
Primary (Actions):
  - Blue: #2563eb (buttons, links, active states)
  - Blue Dark: #1e40af (hover states)

Status Colors:
  - Success: #059669 (connected, completed)
  - Warning: #d97706 (low battery, needs attention)
  - Error: #dc2626 (disconnected, failed)
  - Info: #0891b2 (notifications, tips)

Neutral (UI):
  - Background: #ffffff (light) / #1f2937 (dark)
  - Surface: #f9fafb (light) / #111827 (dark)
  - Border: #e5e7eb (light) / #374151 (dark)
  - Text Primary: #111827 (light) / #f9fafb (dark)
  - Text Secondary: #6b7280 (light) / #9ca3af (dark)
```

### Typography

```css
/* Use system font stack - zero download time */
font-family: -apple-system, BlinkMacSystemFont, "Segoe UI",
             Roboto, "Helvetica Neue", Arial, sans-serif;

/* Type Scale */
text-xs:   0.75rem  (12px)  - Labels, captions
text-sm:   0.875rem (14px)  - Body small, secondary text
text-base: 1rem     (16px)  - Body text, inputs
text-lg:   1.125rem (18px)  - Emphasized text
text-xl:   1.25rem  (20px)  - Page titles
text-2xl:  1.5rem   (24px)  - Section headers

/* Line Height */
leading-tight:  1.25  - Headings
leading-normal: 1.5   - Body text
leading-relaxed: 1.75 - Long-form content
```

### Spacing System

```css
/* 4px base unit */
0:  0
1:  0.25rem (4px)
2:  0.5rem  (8px)
3:  0.75rem (12px)
4:  1rem    (16px)
6:  1.5rem  (24px)
8:  2rem    (32px)
12: 3rem    (48px)
```

### Components

#### Buttons
```
Primary:   Bold background, white text, clear call-to-action
Secondary: Border only, transparent background
Danger:    Red background for destructive actions
Icon-only: 44x44px minimum touch target
```

#### Cards
```
Light elevation, subtle border
Padding: 1rem (mobile) / 1.5rem (desktop)
Border radius: 0.5rem (8px)
```

#### Forms
```
Inputs: 44px min height (touch-friendly)
Labels: Always visible (no floating labels)
Validation: Inline, immediate feedback
```

---

## Layout Structure

### Grid System
- **Mobile**: Single column, full-width
- **Tablet**: 2 columns where appropriate
- **Desktop**: 3-column max (sidebar + main + auxiliary)

### Navigation
- **Mobile**: Bottom navigation bar (thumb-friendly)
- **Desktop**: Left sidebar (collapsible)
- **Max 5 items**: Dashboard, Commands, Settings, Logs, Help

### Page Structure
```
┌─────────────────────────────────┐
│ Header (always visible)         │
│ - Logo / Title                  │
│ - Status indicators             │
│ - Session info                  │
├─────────────────────────────────┤
│                                 │
│ Main Content Area               │
│ (scrollable)                    │
│                                 │
│ - Clear hierarchy               │
│ - Generous whitespace           │
│ - Focused tasks                 │
│                                 │
├─────────────────────────────────┤
│ Bottom Nav (mobile)             │
│ or Footer (desktop)             │
└─────────────────────────────────┘
```

---

## Interaction Patterns

### Loading States
1. **Skeleton screens** for initial load (CSS only, no spinners)
2. **Inline progress** for actions (e.g., "Executing...")
3. **Toast notifications** for completion/errors (auto-dismiss)

### Error Handling
1. **Inline validation** - Show errors near the field
2. **Error boundaries** - Graceful degradation
3. **Retry options** - Always offer a way forward

---

## Data Visualization (Victory Charts)

### Mobile-First Chart Design

**Victory** is the official charting library for cross-platform support:
- Web (Remix.js)
- React Native (iOS/Android)
- Electron (Desktop)

### Chart Guidelines

#### Touch Interactions
```typescript
// Victory provides built-in mobile gestures
<VictoryChart
  containerComponent={
    <VictoryZoomContainer
      zoomDimension="x"        // Horizontal zoom
      allowPan={true}          // Swipe to pan
      allowZoom={true}         // Pinch to zoom
      minimumZoom={{ x: 1 }}
    />
  }
>
  <VictoryLine data={waveformData} />
</VictoryChart>
```

#### Responsive Sizing
- **Mobile**: Full-width charts (375px - 20px padding)
- **Tablet**: 60-80% width with legends
- **Desktop**: Max 800px width

#### Performance
- **Code Splitting**: Lazy load charts only when needed
- **Data Points**: Limit to 1000 points for smooth interaction
- **Downsampling**: For waveforms > 10k samples

### Color Scheme for Charts

```css
/* Match cyberpunk theme */
--chart-primary: #00ffff;     /* Cyan - main data line */
--chart-secondary: #ff00ff;   /* Magenta - comparison */
--chart-accent: #00ff88;      /* Green - success threshold */
--chart-warning: #ffaa00;     /* Orange - warning threshold */
--chart-grid: rgba(255, 255, 255, 0.1);  /* Subtle grid */
```

### Guided Workflow UI

Multi-step wizards for PM3 operations:

#### Progress Indicator
```
[✓] Tune Antenna → [●] Read Card → [ ] Write Target
```

#### Step Navigation
- **Mobile**: Full-screen steps, clear back/next buttons (bottom)
- **Desktop**: Sidebar with step list, main area for content
- **Validation**: Disable "Next" until step requirements met

#### Touch-Optimized Actions
```
┌─────────────────────────────────┐
│ Step 2: Read Source Card        │
├─────────────────────────────────┤
│                                 │
│ [Large icon: Card on reader]   │
│                                 │
│ Place card on Proxmark3         │
│ antenna and tap button below    │
│                                 │
│  ┌───────────────────────────┐ │
│  │    Read Card (44px)       │ │  ← Touch target
│  └───────────────────────────┘ │
│                                 │
│ [Progress: 0 of 64 blocks]     │
│                                 │
├─────────────────────────────────┤
│ [Back]              [Next →]   │  ← Navigation
└─────────────────────────────────┘
```
4. **Clear messages** - Explain what happened and why

### Real-Time Updates (SSE)
1. **Status badges** - Live connection indicator
2. **Notification dot** - New events available
3. **Auto-update** - Background refresh without disruption
4. **Rate limiting** - Debounce rapid updates

### Command Execution Flow
```
1. User enters command
2. Instant visual feedback (disable button, show "Executing...")
3. Command sent to backend
4. Progress indication (if long-running)
5. Result display (success/error with output)
6. Re-enable interface
```

---

## Page Specifications

### 1. Dashboard (`/`)
**Purpose**: Quick status overview, jump to common actions

**Content**:
- System status card (CPU temp, memory, disk)
- PM3 connection status
- UPS battery level (if present)
- Quick actions (Scan, Clone, Settings)
- Recent activity log (last 5 commands)
- Update notification (if available)

**Layout**: 2-3 cards on mobile (stacked), 3-4 cards on desktop (grid)

### 2. Commands (`/commands`)
**Purpose**: Execute PM3 commands with guided workflows

**Tabs**:
- **Quick Actions**: Buttons for common commands (hw status, hf search, lf search)
- **Custom**: Text input for advanced users
- **Wizards**: Step-by-step guides (Clone Card, Format T5577, etc.)

**Output**: Monospace terminal-style display with syntax highlighting

### 3. Settings (`/settings`)
**Purpose**: Configure system behavior

**Sections**:
- Wi-Fi (mode selection, credentials)
- Updates (auto-update toggle, check now)
- Session (timeout setting, current session info)
- Backup (schedule, restore)
- Security (auth enable, HTTPS)
- Advanced (PM3 device path, timeouts)

**Layout**: Accordion on mobile, tabs on desktop

### 4. Logs (`/logs`)
**Purpose**: View command history and system logs

**Features**:
- Filterable table (date, command, status)
- Export option (CSV)
- Clear history button (with confirmation)

### 5. Help (`/help`)
**Purpose**: Embedded documentation

**Content**:
- Quick start guide
- Common PM3 commands
- Troubleshooting
- Link to full documentation

---

## Accessibility (a11y)

### WCAG 2.1 AA Compliance
- **Color contrast**: 4.5:1 minimum for text
- **Keyboard navigation**: All interactive elements reachable
- **Focus indicators**: Clear, visible focus styles
- **ARIA labels**: Meaningful labels for screen readers
- **Alt text**: All images/icons have descriptions

### Touch Targets
- **Minimum size**: 44x44px
- **Spacing**: 8px minimum between targets
- **Feedback**: Visual response to all interactions

---

## Performance Optimization

### CSS Strategy
```
✅ DO:
- Use vanilla CSS (no framework overhead)
- CSS Grid & Flexbox for layouts
- CSS variables for theming
- Minimal animations (transform/opacity only)
- Mobile-first media queries

❌ DON'T:
- Heavy CSS frameworks (Bootstrap, Material UI)
- Web fonts (use system fonts)
- Complex animations (drains CPU)
- Excessive shadows/gradients
- Unused CSS
```

### JavaScript Strategy
```
✅ DO:
- Remix SSR (minimal client JS)
- Progressive enhancement
- Code splitting by route
- Debounce user input
- Use native APIs where possible

❌ DON'T:
- Heavy libraries (moment.js, lodash)
- Polyfills for modern browsers only
- Unnecessary dependencies
- Client-side rendering (use SSR)
- Global state (use URL/forms)
```

### Image Strategy
```
✅ DO:
- Inline SVG icons (<2KB each)
- System emoji for decorative elements
- Lazy loading for below-fold images
- Serve WebP with fallbacks

❌ DON'T:
- Icon fonts (Flash of Unstyled Text)
- Large images (compress heavily)
- Unoptimized assets
- Background images (use CSS colors)
```

---

## Dark Mode

### Implementation
- **System preference detection**: `prefers-color-scheme`
- **Manual toggle**: Persisted in localStorage
- **CSS variables**: Single source of truth for colors
- **No flash**: SSR with cookie-based preference

### Colors
```css
:root {
  /* Light mode (default) */
  --color-bg: #ffffff;
  --color-surface: #f9fafb;
  --color-text: #111827;
}

@media (prefers-color-scheme: dark) {
  :root {
    --color-bg: #1f2937;
    --color-surface: #111827;
    --color-text: #f9fafb;
  }
}
```

---

## Mobile Considerations

### Touch-First Design
- Large buttons (44x44px minimum)
- Bottom navigation (thumb zone)
- Swipe gestures (optional, enhance)
- Avoid hover-only interactions

### Viewport
```html
<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=5">
```

### PWA Support
- Add to home screen
- Offline fallback page
- Service worker for caching
- App manifest

---

## Development Checklist

### Before Committing
- [ ] Lighthouse score > 90 (Performance, A11y, Best Practices)
- [ ] Works without JavaScript
- [ ] Mobile responsive (320px - 1920px)
- [ ] Dark mode tested
- [ ] Keyboard navigation works
- [ ] Screen reader tested
- [ ] Bundle size < 150KB gzipped

### Testing Devices
- iPhone SE (375px width)
- iPad Mini (768px width)
- Desktop (1280px+ width)

---

## Quick Reference

### Breakpoints
```css
sm: 640px   /* Tablets */
md: 768px   /* Small laptops */
lg: 1024px  /* Desktop */
```

### Animation Durations
```css
fast:   150ms /* Hovers, simple transitions */
normal: 250ms /* Most UI animations */
slow:   350ms /* Page transitions */
```

### Z-Index Scale
```css
base:    0   /* Normal content */
dropdown: 10  /* Dropdowns, tooltips */
modal:   100  /* Modals, dialogs */
toast:   200  /* Notifications */
```

---

## Resources

- **Remix Docs**: https://remix.run/docs
- **CSS Grid**: https://css-tricks.com/snippets/css/complete-guide-grid/
- **A11y Checklist**: https://www.a11yproject.com/checklist/
- **Performance Budget**: https://web.dev/performance-budgets-101/

---

## Example Component: Status Badge

```css
/* Lightweight, semantic, accessible */
.status-badge {
  display: inline-flex;
  align-items: center;
  gap: 0.5rem;
  padding: 0.25rem 0.75rem;
  border-radius: 9999px;
  font-size: 0.875rem;
  font-weight: 500;
}

.status-badge--success {
  background: #d1fae5;
  color: #065f46;
}

.status-badge--error {
  background: #fee2e2;
  color: #991b1b;
}
```

```jsx
<span className="status-badge status-badge--success" role="status">
  <span aria-hidden="true">●</span>
  Connected
</span>
```

**Why it's good**:
- Semantic HTML
- CSS-only styling (no JS)
- Accessible (role="status")
- Visual and text indicator
- Small footprint (~100 bytes)