pi-pm3/UI_GUIDELINES.md

Dangerous Pi - UI/UX Guidelines

Design Philosophy

Resource-Constrained Excellence: Build a beautiful, functional interface that respects the Pi Zero 2 W's limited resources while providing an excellent user experience.

Core Principles

1. Performance First - Every byte counts
2. Progressive Enhancement - Works without JavaScript, better with it
3. Mobile-First - Optimize for small screens (most users access via phone)
4. Single-Purpose Focus - One task at a time, clear hierarchy
5. 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
• Total Bundle Size: < 150KB (gzipped)
• CSS: < 20KB (gzipped)
• Fonts: System fonts only (no web fonts)

---

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

/* 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

/* 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
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

: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

<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

sm: 640px   /* Tablets */
md: 768px   /* Small laptops */
lg: 1024px  /* Desktop */

Animation Durations

fast:   150ms /* Hovers, simple transitions */
normal: 250ms /* Most UI animations */
slow:   350ms /* Page transitions */

Z-Index Scale

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

/* 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;
}

<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)