Timmy-time-dashboard/docs/ui-ux-audit-gemma4.md

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.