Epic: UX/UI Revamp

[olucasandrade]

Epic: UX/UI Revamp

Overview

Transform Trevo from a functional API testing tool into an immersive, developer-focused experience. This epic spans the full monorepo — the web app (apps/web, Next.js 15), the desktop app (apps/desktop, Vite + Tauri), and the landing page (apps/landing, Vite). The shared UI package (packages/ui) serves as the central theme system for web and desktop, while the landing page uses independent Tailwind styling.

This epic leverages the existing Mantine v7 + Tailwind + Framer Motion stack, adding animations, theming, terminal mode, and keyboard navigation to create a polished, memorable interface inspired by Insomnia.

Architecture Decisions

Monorepo Scope

App/Package	Stack	Theme Integration	Scope
apps/web	Next.js 15 + Mantine v7	Uses @trevo/ui theme	Full UX/UI revamp
apps/desktop	Vite + Tauri + Mantine v7	Uses @trevo/ui theme	Full UX/UI revamp (shared with web)
apps/landing	Vite + Tailwind (no Mantine)	Independent Tailwind themes	Visual polish, animations, consistent branding
packages/ui	Mantine v7 + Framer Motion	IS the theme system	Central theme provider, shared components
packages/core	Pure TypeScript	N/A	No UI changes
packages/i18n	i18next	N/A	New UI strings (en/pt)
packages/api-client	Axios + Tauri API	N/A	No UI changes

Technology Choices

Decision	Choice	Rationale
Animation	Framer Motion (existing)	Already in web, desktop, and @trevo/ui
UI Components	Mantine v7 (existing)	Shared via packages/ui, used by web + desktop
Keyboard Shortcuts	react-hotkeys-hook	Lightweight, React-native, declarative
Terminal Syntax	Prism.js or Shiki	Fast, themeable syntax highlighting
Theme Storage	localStorage + CSS Variables	No backend needed, instant switching
Custom Cursor	CSS + React state	Pure CSS for performance, state for context
Landing Theming	Tailwind CSS Variables	Independent from Mantine, consistent branding

Design Patterns

• Theme Provider Pattern: Centralized theme context with CSS variables
• Compound Components: Keyboard shortcuts as composable hooks
• Lazy Loading: Terminal mode loaded on-demand to reduce initial bundle
• Motion Variants: Shared Framer Motion variants for consistent animations

Key Simplifications

1. No custom theme builder initially - Ship with 4-5 pre-built themes (Dark Pro, Nord, Dracula, Monokai)
2. Terminal mode as overlay - Reuse existing request/response logic, just different UI
3. Keyboard shortcuts via hook - Single useKeyboardShortcuts hook, not per-component
4. Custom cursor via CSS - No complex tracking, just cursor property changes

Technical Approach

Frontend Components

Shared (packages/ui) — consumed by web + desktop:

• ThemeProvider - CSS variable injection + theme context
• KeyboardShortcutProvider - Global keyboard handler
• AnimatedPanel - Wrapper for consistent panel animations
• CustomCursor - Cursor style manager
• Extended Mantine theme with custom dark palettes

Web + Desktop (apps/web, apps/desktop):

• TerminalMode - Full-screen terminal interface overlay
• HowToUse - Interactive onboarding page/modal
• All existing panels get Framer Motion motion wrappers
• Loading states replaced with skeleton animations

Landing (apps/landing):

• Tailwind-based theme variables for consistent branding
• Animation enhancements with CSS/Tailwind utilities
• Visual polish matching the main app's design language

State Management

• Theme preference: localStorage + React Context
• Keyboard shortcuts: React Context with reducer
• Terminal mode: URL state (?terminal=true) for shareability
• First-visit flag: localStorage for how-to-use trigger

Animation Architecture

packages/ui/src/
├── animations/
│   ├── variants.ts        # Shared motion variants (web + desktop)
│   ├── transitions.ts     # Timing presets
│   └── hooks/
│       └── useReducedMotion.ts
├── components/
│   ├── motion/
│   │   ├── AnimatedPanel.tsx
│   │   ├── FadeIn.tsx
│   │   └── SlideIn.tsx
├── theme/
│   ├── themes.ts          # Theme definitions (Dark Pro, Nord, etc.)
│   ├── ThemeProvider.tsx   # Context + CSS variable injection
│   └── theme.ts           # Extended Mantine theme config (existing)

Infrastructure

• Bundle impact: Estimated +15KB gzipped (Framer Motion already in web/desktop/ui)
• Performance: Respect prefers-reduced-motion, lazy-load terminal
• i18n: Extend packages/i18n/src/locales/*.json with new UI strings (en/pt)
• Shared theme: Changes in packages/ui automatically propagate to web + desktop
• Landing: Independent CSS variables, no Mantine dependency added

Implementation Strategy

Development Phases

Phase 1: Foundation

• Theme system with CSS variables
• Animation utilities and variants
• Keyboard navigation framework

Phase 2: Core Features

• Terminal mode implementation
• Custom cursor
• Complete dark mode polish

Phase 3: Polish & Onboarding

• How-to-use page
• Micro-interactions
• Pre-built themes

Risk Mitigation

Risk	Mitigation
Animation performance	Use will-change, test on low-end devices
Bundle size creep	Lazy load terminal mode, monitor with bundleanalyzer
Keyboard conflicts	Audit existing shortcuts, use modifier keys
Theme inconsistencies	Single source of truth via CSS variables

Testing Approach

• Visual regression tests for theme changes
• Keyboard navigation E2E tests
• Animation performance profiling
• Accessibility audit (keyboard + screen reader)

Task Breakdown Preview

High-level tasks (will be decomposed into issues):

• Task 1: Theme System - CSS variables, theme context, 4-5 pre-built themes, dark mode polish
• Task 2: Animation Foundation - Motion variants, animated components, page transitions, micro-interactions
• Task 3: Keyboard Navigation - Global shortcuts, focus management, shortcut cheat sheet (Cmd+?)
• Task 4: Terminal Mode - CLI-style interface, syntax highlighting, command history, toggle UI
• Task 5: Custom Cursor - Cursor styles, context-aware states, disable option
• Task 6: How-To-Use Page - Interactive guide, keyboard reference, first-visit trigger
• Task 7: Visual Polish - Glassmorphism panels, loading skeletons, success/error animations
• Task 8: Accessibility & Performance - Reduced motion support, focus indicators, bundle optimization

Dependencies

External Libraries (to add)

• react-hotkeys-hook - Keyboard shortcuts (~2KB)
• prism-react-renderer or shiki - Terminal syntax highlighting (~10KB)

Existing Stack (leverage)

• Framer Motion - Already installed
• Mantine v7 - Already installed (extend theme)
• Tailwind CSS - Already installed
• next-intl - Already installed (add strings)

Content Needed

• Theme color palettes (Dark Pro, Nord, Dracula, Monokai)
• How-to-use copy (en/pt translations)
• Keyboard shortcut definitions
• Custom cursor SVG/design

Success Criteria (Technical)

Performance Benchmarks

• Page transitions complete in <300ms
• 60fps animations on M1 MacBook and equivalent
• Initial bundle stays <500KB gzipped
• Terminal mode lazy loads in <200ms

Quality Gates

• All components keyboard navigable
• Zero Mantine theme overrides leak light colors in dark mode
• prefers-reduced-motion disables all animations
• All new strings translated (en/pt)

Acceptance Criteria

• 4+ pre-built themes available
• Terminal mode fully functional (all request types)
• Keyboard shortcuts discoverable via Cmd+?
• How-to-use triggers on first visit, accessible from menu
• Custom cursor works across all interactive elements

Estimated Effort

Task Complexity

Task	Complexity	Notes
Theme System	Medium	CSS variables + context
Animation Foundation	Medium	Leverage Framer Motion
Keyboard Navigation	Medium	react-hotkeys-hook
Terminal Mode	High	New interface, command parsing
Custom Cursor	Low	CSS-only solution
How-To-Use Page	Medium	New page + i18n
Visual Polish	Medium	Incremental enhancements
Accessibility & Perf	Low	Audit and optimize

Critical Path

1. Theme System (enables all visual work)
2. Animation Foundation (enables polish)
3. Terminal Mode (biggest new feature)
4. Everything else can parallel

Resource Requirements

• 1 developer for core implementation
• Design input for color palettes and cursor design
• Copy for how-to-use guide (en/pt)

Tasks Created

• Interactive How-To-Use Page #10 - Interactive How-To-Use Page (parallel: true)
• Visual Polish and Immersive Elements #11 - Visual Polish and Immersive Elements (parallel: true)
• Accessibility and Performance Optimization #12 - Accessibility and Performance Optimization (parallel: false)
• Theme System with CSS Variables and Pre-built Themes #5 - Theme System with CSS Variables and Pre-built Themes (parallel: true)
• Animation Foundation with Framer Motion #6 - Animation Foundation with Framer Motion (parallel: false)
• Keyboard Navigation and Shortcuts #7 - Keyboard Navigation and Shortcuts (parallel: true)
• Terminal Mode Interface #8 - Terminal Mode Interface (parallel: false)
• Custom Cursor Implementation #9 - Custom Cursor Implementation (parallel: true)

Total tasks: 8
Parallel tasks: 5
Sequential tasks: 3

---

Next Steps: Run /pm:epic-start ux-ui-revamp to begin parallel execution.