headquarter/openspec/changes/mobile-app-usability/design.md

Context

The Headquarter web app is built as a desktop-first React application. While the terminal component has been fully mobile-optimized through the mobile-terminal-ux change, the rest of the application remains largely unusable on mobile devices. Key pages like Sessions, Dashboard, and Project Workspace use desktop-oriented layouts (sidebars, multi-column forms, fixed-width panels) that break on small viewports.

Current mobile state:

• AppShell has horizontal scroll navigation (functional but awkward)
• Session cards have action buttons that wrap and overlap
• CreateSessionForm uses multi-column grids that become cramped
• Repo Workspace has 3 fixed sidebars that stack poorly
• Tool Workshop and Config Profiles use fixed 280px sidebars with no mobile adaptation
• Many touch targets are below 44px
• Dialogs may overflow 320px viewports

User behavior on mobile:

• Primary use: start/stop sessions, check status, terminal access
• Secondary use: small config adjustments, quick file edits
• Not used for: complex tool configuration, heavy code editing, git merge operations

Goals / Non-Goals

Goals:

• Make session start/stop/restart fully usable on mobile
• Provide clear navigation and wayfinding on small screens
• Ensure all interactive elements have minimum 44px touch targets
• Make Dashboard and Sessions pages comfortable to use on phones
• Add consistent mobile page headers with back buttons
• Ensure dialogs and modals work within 320px viewport
• Provide read-first, edit-second pattern for complex admin pages

Non-Goals:

• Full feature parity with desktop (complex editing remains desktop-optimized)
• Native app feel (no swipe gestures, pull-to-refresh, or bottom sheets beyond existing terminal special keys)
• Redesigning the terminal (already complete)
• Tablet-specific optimizations (focus is on 320-768px phones)
• Changing any backend APIs or data models

Decisions

1. Bottom Tab Bar for Primary Navigation

Decision: Replace AppShell's horizontal scroll nav with a bottom tab bar on mobile (< 768px).

Rationale:

• Bottom tab bars are the standard mobile navigation pattern
• Thumb-reachable, always visible, supports muscle memory
• Horizontal scroll nav requires two-handed use and hides items

Implementation:

• Create MobileNav component with 5 tabs: Home, Projects, Sessions, Tools, Settings
• Show badges for active sessions
• Use CSS position: fixed; bottom: 0 with safe-area-inset padding
• Desktop keeps existing sidebar navigation

2. Session Cards: Action Sheet Pattern

Decision: Replace inline action buttons with a single "Actions" button that opens a dropdown/sheet.

Rationale:

• Current session cards show 4-5 action buttons (Open, Terminal, Stop, Restart, Delete) that wrap awkwardly
• Action sheet reduces visual clutter while keeping all actions accessible
• Follows native mobile pattern

Implementation:

• Add ... or "Actions" button to each session card
• On tap, show action sheet with: Open, Terminal, Stop/Start, Restart, Delete
• Primary action (Open/Terminal) remains as prominent button
• Keep swipe actions for power users (optional enhancement)

3. Forms: Vertical Stacking with Progressive Disclosure

Decision: All multi-column forms stack vertically on mobile. Complex forms use stepper or accordion pattern.

Rationale:

• Multi-column forms become unreadable on 320px screens
• Vertical stacking is the native mobile form pattern
• Steppers reduce cognitive load by showing one section at a time

Implementation:

• Update CSS: @media (max-width: 767px) set grid-template-columns: 1fr on all form grids
• For CreateSessionForm: consider stepper (Project → Repo → Tool → Config) or keep as single long form with clear sections
• Ensure all inputs have min-height: 44px and adequate spacing

4. Complex Admin Pages: Read-First Pattern

Decision: Tool Workshop and Config Profiles show summary/list view by default on mobile, with edit flowing into full-screen mode.

Rationale:

• These pages have complex forms with sidebars that don't fit mobile
• Users rarely need to edit these on mobile, but may need to view or make small changes
• Read-first pattern matches user behavior

Implementation:

• Tool Workshop: show tool type cards with key info, tap to view details, "Edit" enters full-screen edit mode
• Config Profiles: show profile list, tap to view summary (tools, mounts, env), "Edit" enters multi-step form
• Keep desktop split-pane layout unchanged

5. Touch Targets and Feedback

Decision: Enforce 44px minimum touch targets everywhere. Add active states for all interactive elements.

Rationale:

• iOS Human Interface Guidelines and Android Material Design both recommend 44-48px
• Missing active states make the app feel unresponsive on touch

Implementation:

• Audit all buttons, links, and clickable areas
• Add :active states with subtle background changes
• Add loading/spinner states for async operations
• Ensure adequate spacing between adjacent touch targets (minimum 8px)

Risks / Trade-offs

[Risk] Increased CSS complexity from dual layouts → Mitigation: Use CSS custom properties and utility classes. Mobile styles live in @media (max-width: 767px) blocks alongside desktop styles, not in separate files.

[Risk] Bottom tab bar reduces vertical screen real estate → Mitigation: Tab bar is only ~56px + safe area. On modern phones, this is acceptable. Content areas must account for tab bar height with padding-bottom.

[Risk] Hiding actions behind menus increases tap count → Mitigation: Keep the most common action (Open/Terminal) as a primary visible button. Only secondary actions (Restart, Delete) move to the menu.

[Risk] Stepper forms may annoy desktop users if not implemented carefully → Mitigation: Stepper only activates on mobile breakpoints. Desktop keeps existing layouts.

[Risk] Maintaining two navigation patterns (desktop sidebar + mobile tab bar) → Mitigation: Both use the same route definitions. Navigation state is URL-driven. MobileNav is just a different UI for the same router.

Migration Plan

This is a pure frontend change with no backend or database impact.

1. Implement mobile navigation (AppShell changes)
2. Update session pages (Dashboard, Sessions)
3. Update form components (CreateSessionForm, dialogs)
4. Update complex pages (Repo Workspace, Tool Workshop, Config Profiles)
5. Polish: touch targets, active states, dialog sizing
6. Test on actual devices (iOS Safari, Android Chrome)

Rollback: Revert CSS/JS changes. No data migration needed.

Open Questions

1. Should we add a "Quick Actions" FAB (Floating Action Button) on mobile for common operations like "Start Session"?
2. Should the bottom tab bar hide when scrolling down to maximize content area (like Safari's bottom bar)?
3. Do we need a "Desktop Site" toggle for users who prefer the desktop layout on tablets?