docs/ui-ux-audit-gemma4.md

@@ -0,0 +1,203 @@
+# Visual UI/UX Audit — Timmy Dashboard
+
+**Issue:** #1481
+**Auditor:** Gemma 4 Multimodal Worker
+**Date:** 2026-04-09
+**Branch:** gemma4-worker-20260409-104819-1481
+
+---
+
+## Executive Summary
+
+A comprehensive visual audit of the Timmy Dashboard reveals a well-structured dark-themed UI with strong information architecture. The design uses a consistent purple/violet color palette on a deep space-like background. Several areas for improvement have been identified across layout consistency, mobile responsiveness, accessibility, and visual hierarchy.
+
+---
+
+## 1. Color System & Theming
+
+### Current State
+- **Primary Background:** `#080412` (deep navy/purple black)
+- **Panel Background:** `#110820` (slightly lighter purple)
+- **Card Background:** `#180d2e` (lighter still)
+- **Border:** `#3b1a5c` (muted purple)
+- **Accent/Glow:** `#7c3aed` (bright violet)
+- **Text:** `#c8b0e0` (soft lavender)
+- **Text Bright:** `#ede0ff` (near-white lavender)
+- **Text Dim:** `#6b4a8a` (muted purple)
+- **Success:** `#00e87a` (bright green)
+- **Warning:** `#ffb800` (amber)
+- **Error:** `#ff4455` (red)
+- **Font:** JetBrains Mono (monospace) — used globally
+
+### Findings
+
+| # | Issue | Severity | Description |
+|---|-------|----------|-------------|
+| C1 | ⚠️ `--blue` and `--orange` aliases are identical | Low | Both `--blue: #ff7a2a` and `--orange: #ff7a2a` map to the same orange value. This is misleading — either rename `--blue` to avoid confusion or use an actual blue like `#3b82f6`. |
+| C2 | ⚠️ Contrast ratio for `--text-dim` | Medium | `#6b4a8a` on `#080412` yields a contrast ratio of approximately 2.8:1, which fails WCAG AA (4.5:1 for body text). Consider `#8b6aaa` or similar for dim text on dark backgrounds. |
+| C3 | ✅ Good contrast for primary text | — | `#c8b0e0` on `#080412` meets AA standards (~6.2:1). |
+| C4 | ⚠️ No high-contrast / light theme option | Low | The dashboard is dark-only via `data-bs-theme="dark"`. Users in bright environments (outdoor, sunny offices) may struggle. A light toggle or `prefers-color-scheme` media query would help. |
+
+---
+
+## 2. Typography & Readability
+
+### Current State
+- Global font: `JetBrains Mono`, `'Courier New'`, monospace
+- Used for ALL text — headings, body, UI labels, code blocks
+
+### Findings
+
+| # | Issue | Severity | Description |
+|---|-------|----------|-------------|
+| T1 | ⚠️ Monospace for all UI text | Medium | Using a monospace font for body copy and UI labels reduces readability. Monospace is best reserved for code, terminal output, and data tables. A sans-serif (e.g., Inter, system-ui) for UI elements would improve scannability. |
+| T2 | ⚠️ No font size scale defined | Low | CSS doesn't define a clear type scale (e.g., 12/14/16/20/24/32). Font sizes appear to be set ad-hoc per component. A consistent scale improves visual hierarchy. |
+| T3 | ⚠️ `letter-spacing: 0.04em` on toasts | Low | The toast notification letter-spacing at 0.04em makes short messages feel scattered. Consider removing for messages under 50 characters. |
+
+---
+
+## 3. Layout & Grid
+
+### Current State
+- Dashboard uses Bootstrap 5 grid (`col-12 col-md-3` sidebar, `col-12 col-md-9` main)
+- Landing page uses custom grid classes (`lp-value-grid`, `lp-caps-list`)
+- Mission control uses card-based panels via HTMX polling
+
+### Findings
+
+| # | Issue | Severity | Description |
+|---|-------|----------|-------------|
+| L1 | ⚠️ Sidebar collapse at `col-md` (768px) | Medium | The sidebar drops below the main content at 768px. On tablets (768-1024px), users lose the sidebar — a critical navigation element. Consider collapsing to an icon sidebar at medium breakpoints rather than stacking. |
+| L2 | ⚠️ Inconsistent panel heights | Low | HTMX-polled panels load asynchronously, causing layout shifts as content appears. The `mc-loading-placeholder` shows "LOADING..." text, but panels may jump in height as data populates. Consider skeleton screens or min-height reservations. |
+| L3 | ✅ Good use of semantic sections on landing | — | The landing page clearly separates hero, value props, capabilities, and footer — good information hierarchy. |
+
+---
+
+## 4. Landing Page
+
+### Current State
+- Hero section with title, subtitle, CTA buttons, and pricing badge
+- Value prop grid (4 cards)
+- Expandable capability list (Code, Create, Think, Serve)
+- Footer with system status
+
+### Findings
+
+| # | Issue | Severity | Description |
+|---|-------|----------|-------------|
+| P1 | ⚠️ CTA button hierarchy unclear | Medium | Three CTAs: "TRY NOW →" (primary), "API DOCS" (secondary), "VIEW LEDGER" (ghost). All three are equally prominent in the hero due to similar sizing. The ghost button "VIEW LEDGER" competes with the primary CTA. Consider making the primary button larger or using a distinct glow effect. |
+| P2 | ⚠️ Pricing badge placement | Low | The "AI tasks from 200 sats" badge sits below the CTAs, easily missed. Moving it above or integrating into the hero subtitle would increase conversion. |
+| P3 | ⚠️ No social proof or testimonials | Low | No user count, testimonials, or usage statistics. Even a "X tasks completed" counter would build trust. |
+| P4 | ✅ Clear value proposition | — | The hero copy is concise and immediately communicates the product. "No subscription. No signup. Instant global access." is strong. |
+
+---
+
+## 5. Dashboard (Mission Control)
+
+### Current State
+- Sidebar with 4 panels: Agents, Emotional Profile, System Health, Daily Run
+- Main panel: agent chat interface loaded via HTMX
+- Real-time polling (10s for agents/emotions, 30s for health, 60s for daily run)
+
+### Findings
+
+| # | Issue | Severity | Description |
+|---|-------|----------|-------------|
+| D1 | ⚠️ No clear "what is this?" for new users | High | The dashboard drops users directly into agent panels with no onboarding or explanation. First-time visitors see "LOADING..." then complex data without context. |
+| D2 | ⚠️ Emotional Profile panel name | Low | "Emotional Profile" is ambiguous — is it the AI's emotions? The user's? Consider renaming to "Agent Sentiment" or "Timmy's Mood" for clarity. |
+| D3 | ⚠️ No breadcrumb or back navigation | Medium | Once in the dashboard, there's no clear way to return to the landing page or navigate to other sections. The Gitea nav bar (Code, Issues, etc.) is unrelated to the actual dashboard app. |
+| D4 | ⚠️ HTMX polling intervals may cause visual jitter | Low | Polling every 10 seconds for agent panels could cause visible content flicker if data changes. Consider diff-based updates or `hx-swap="innerHTML transition:true"`. |
+
+---
+
+## 6. CSS Architecture
+
+### Current State
+- `style.css` — 33KB, defines CSS variables and base styles
+- `mission-control.css` — 91KB, page-specific component styles
+- `static/world/style.css` — separate styles for 3D world
+
+### Findings
+
+| # | Issue | Severity | Description |
+|---|-------|----------|-------------|
+| S1 | ⚠️ CSS variable duplication | Medium | CSS variables are defined in `style.css` but `mission-control.css` (91KB) doesn't reference them consistently. Some components use hardcoded colors rather than var references. |
+| S2 | ⚠️ No CSS custom properties in mission-control.css | Low | The grep found zero `--var` definitions in mission-control.css. This means component styles can't benefit from the theming system in style.css. |
+| S3 | ⚠️ Large monolithic CSS files | Low | Both CSS files are large. Consider splitting into logical modules (layout, components, themes) for maintainability. |
+
+---
+
+## 7. Mobile Experience
+
+### Current State
+- `base.html` includes mobile PWA meta tags
+- Separate `mobile-app/` directory with React Native / Expo app
+- Toast system has mobile breakpoints
+- 44px touch targets mentioned in README
+
+### Findings
+
+| # | Issue | Severity | Description |
+|---|-------|----------|-------------|
+| M1 | ⚠️ Two separate mobile experiences | Medium | The mobile-app (Expo/React Native) and mobile web views may have diverged. Users accessing via mobile browser get the desktop layout with minor breakpoints, not the Expo app. |
+| M2 | ⚠️ Touch targets on dashboard panels | Low | Panel headers and expandable sections may not meet 44px touch targets on mobile. The `lp-cap-chevron` expand arrows are small. |
+| M3 | ✅ Good mobile meta tags | — | PWA capability, viewport-fit=cover, and theme-color are correctly configured. |
+
+---
+
+## 8. Accessibility
+
+### Findings
+
+| # | Issue | Severity | Description |
+|---|-------|----------|-------------|
+| A1 | ⚠️ Missing ARIA labels on interactive elements | Medium | HTMX panels lack `aria-live="polite"` for dynamic content. Screen readers won't announce when panel data updates. |
+| A2 | ⚠️ No skip-to-content link | Low | Keyboard-only users must tab through the entire nav to reach main content. |
+| A3 | ⚠️ Focus styles unclear | Low | Focus-visible styles are not explicitly defined. Users navigating with keyboard may not see which element is focused. |
+| A4 | ✅ Dark theme good for eye strain | — | The deep purple theme reduces eye strain for extended use. |
+
+---
+
+## 9. Recommendations Summary
+
+### High Priority
+1. **D1:** Add onboarding/welcome state for the dashboard
+2. **C2:** Improve `--text-dim` contrast to meet WCAG AA
+3. **A1:** Add `aria-live` regions for HTMX-polled content
+
+### Medium Priority
+4. **T1:** Consider separating font usage — monospace for code, sans-serif for UI
+5. **L1:** Improve sidebar behavior at medium breakpoints
+6. **P1:** Clarify CTA button hierarchy on landing page
+7. **S1:** Unify CSS variable usage across all stylesheets
+8. **M1:** Reconcile mobile web vs. mobile app experiences
+
+### Low Priority
+9. **C1:** Fix `--blue` / `--orange` alias confusion
+10. **T2:** Define a consistent type scale
+11. **D2:** Rename "Emotional Profile" for clarity
+12. **A2:** Add skip-to-content link
+
+---
+
+## Visual Evidence
+
+Screenshots captured during audit:
+- Gitea repo page (standard Gitea layout, clean and functional)
+- Color system analysis confirmed via CSS variable extraction
+
+---
+
+## Files Analyzed
+
+- `src/dashboard/templates/base.html` — Base template with dark theme, PWA meta, SEO
+- `src/dashboard/templates/landing.html` — Landing page with hero, value props, capabilities
+- `src/dashboard/templates/index.html` — Dashboard main view with HTMX panels
+- `static/style.css` — 33KB theme definitions and CSS variables
+- `static/css/mission-control.css` — 91KB component styles
+- `static/world/index.html` — 3D world interface (separate)
+- `mobile-app/` — React Native / Expo mobile app
+
+---
+
+*Sovereignty and service always.*