headquarter/openspec/changes/archive/2026-05-25-mobile-app-usability/proposal.md at c754984df8b6067f641db339898f44e30d027fd2

Files

T

Alex Blank ab79080f0b refactor: consolidate loading/error states and extract instance actions hook

Frontend:
- Create reusable DataStates components (LoadingState, ErrorState, EmptyState)
- Refactor 12 pages to use shared state components instead of inline JSX
- Extract useInstanceActions hook to eliminate session action duplication
- Update dashboard and sessions pages to use shared hook

OpenSpec:
- Archive completed mobile-app-usability change (44/44 tasks)
- Archive completed add-config-profiles change (15/15 tasks)

Quality: TypeScript check passes, production build succeeds

2026-05-25 22:50:18 +02:00

2.3 KiB

Raw Blame History

Why

The Headquarter web app is currently unusable on mobile devices. Critical workflows—starting and stopping sessions, viewing instance status, and making small configuration adjustments—are blocked by desktop-oriented layouts, missing touch targets, and broken responsive behavior. Since users perform real work through terminal sessions (already mobile-optimized) and session management, the core app shell and key pages must be at least functional on phones.

What Changes

Mobile navigation: Replace horizontal scroll nav with bottom tab bar on mobile breakpoints
Session management mobile layout: Redesign session cards for touch, add swipe actions, ensure all controls are reachable
Dashboard mobile view: Simplify summary cards, optimize quick actions for touch
Responsive forms: Stack multi-column forms vertically on mobile, ensure touch targets ≥ 44px
Mobile-optimized dialogs: Ensure all dialogs fit within 320px viewport, add scroll when needed
Page headers: Add consistent back buttons and contextual action bars on mobile
Touch feedback: Add active states and loading indicators for all interactive elements
Graceful degradation: Complex admin pages (Tool Workshop, Config Profiles) get read-first mobile views with edit capability

Capabilities

New Capabilities

mobile-navigation: Bottom tab bar, page transitions, and mobile-specific navigation patterns
mobile-session-management: Touch-optimized session cards, swipe actions, and mobile session controls
mobile-responsive-layouts: Breakpoint system, touch targets, and form stacking for mobile viewports

Modified Capabilities

frontend-foundation: Add mobile breakpoint system and responsive grid utilities
session-lifecycle-ux: Extend session management UX with mobile-specific interactions
tool-instances: Ensure instance controls (start/stop/restart) are usable on mobile

Impact

Frontend: Major CSS changes to AppShell, page layouts, form components, and card patterns
Components: New MobileNav component, updates to SessionCard, CreateSessionForm, and all page components
User Experience: Significantly improved mobile usability without reducing desktop functionality
No API changes: Purely frontend/CSS work

2.3 KiB Raw Blame History

Why