docs: add mobile ui refresh design spec

docs/superpowers/specs/2026-04-01-mobile-ui-refresh-design.md

@@ -0,0 +1,230 @@
+# Mobile UI Refresh Design
+
+## Goal
+
+Refresh the Flutter mobile app UI so it feels technological and minimal instead of default Material. The redesign should create one coherent visual system across the project list, session list, and terminal page without changing the underlying workflows.
+
+## Product Context
+
+- Audience: developers and operators using a phone to connect to a Windows terminal agent remotely
+- Primary jobs: review projects, open sessions quickly, manage active terminal work, and send terminal input reliably
+- Desired tone: technological, calm, precise, minimal, and slightly premium
+
+## Design Direction
+
+Use a restrained future-industrial aesthetic:
+
+- Dark graphite surfaces with cool blue-cyan accents
+- Strong typography hierarchy with compact, controlled spacing
+- Thin borders and subtle inner contrast instead of loud shadows
+- Minimal card usage, with sections reading more like instrument panels than consumer tiles
+- Clear status signaling for connection state, live output, and input mode
+
+This direction fits a remote terminal product better than a generic dashboard or decorative neon style.
+
+## Problems In The Current UI
+
+### Visual
+
+- The app still uses a near-default `ThemeData(colorSchemeSeed: Colors.blue)` theme.
+- Page structure is mostly standard `Card` plus `ListTile`, so the interface feels generic.
+- Status information, editable settings, and primary actions do not have a clear visual hierarchy.
+- The terminal page has useful controls, but they are visually fragmented and do not read as one work surface.
+
+### UX
+
+- The agent URL area consumes attention but does not feel integrated into the page.
+- Empty states communicate functionally but do not teach the user what to do next with enough clarity.
+- List item actions compete with each other visually.
+- Terminal state, history mode, quick keys, and direct input mode are understandable only after careful reading.
+
+## Scope
+
+### In Scope
+
+- Global Material theme refresh for the mobile app
+- Project list page visual redesign
+- Session list page visual redesign
+- Terminal page visual redesign
+- Shared visual primitives extracted where helpful
+- Improved empty, loading, and error presentation within the touched pages
+
+### Out Of Scope
+
+- Changes to network, repository, or terminal session behavior
+- New product flows or new backend capabilities
+- Rewriting page navigation structure
+- Major terminal rendering changes inside `xterm`
+
+## Approach Options
+
+### Option A: Theme-Only Refresh
+
+Change the app theme and lightly restyle existing widgets.
+
+- Pros: lowest implementation risk, fastest
+- Cons: will not be enough to make the product feel deliberately designed
+
+### Option B: Theme Plus Screen-Level Composition Refresh
+
+Introduce a custom visual system and recompose the three target pages while preserving behavior.
+
+- Pros: best balance of impact and risk
+- Cons: requires targeted widget restructuring
+
+### Option C: Full Design System Pass
+
+Create a broad component library and refactor all touched screens into new reusable building blocks.
+
+- Pros: strongest long-term consistency
+- Cons: too large for the immediate need and likely to delay visible results
+
+## Recommended Approach
+
+Choose Option B.
+
+It reaches the real goal, which is a visible identity shift, without expanding into a broad refactor. The app only needs a compact shared visual layer and deliberate page composition, not a large design-system project.
+
+## Visual System
+
+### Color
+
+Build a dark-first palette with tinted neutrals:
+
+- Background: deep graphite, not pure black
+- Surface: slightly elevated steel-gray panels
+- Accent: cool cyan-blue for active controls and highlights
+- Success: restrained mint-green
+- Warning: muted amber
+- Error: controlled red, not saturated orange-red
+
+Color should signal state, not decorate everything. Most surfaces should remain neutral.
+
+### Typography
+
+Use the default Flutter font stack if introducing a custom font increases delivery risk, but tighten hierarchy through:
+
+- larger, heavier page titles
+- compact supporting metadata
+- stronger small-label usage for state and section headers
+
+Typography should carry much of the visual identity because the target style is minimal.
+
+### Shape
+
+- Medium-large corner radius for panels and toolbars
+- Pill shapes for compact status chips
+- Thin borders for structure
+- Minimal drop shadows, mostly replaced by tonal contrast and outline separation
+
+### Spacing
+
+Use denser spacing than default Material while preserving touch comfort:
+
+- tighter vertical grouping inside panels
+- more deliberate separation between sections
+- minimum 44 logical pixels for tappable controls
+
+## Screen Designs
+
+### Project List Page
+
+Restructure the page into three visual layers:
+
+1. A compact top app bar with stronger title styling and clearer secondary actions
+2. A connection panel for the agent URL, styled as an integrated control surface instead of a basic card
+3. A project feed of elevated panels with clearer action hierarchy
+
+Each project row should include:
+
+- project name as the primary anchor
+- working directory as compressed secondary metadata
+- a high-priority terminal launch action
+- lower-visual-weight edit and delete actions
+
+Empty state should explain that projects define known working directories for new terminals.
+
+### Session List Page
+
+Align this page visually with the project list page so the app feels unified.
+
+The page should emphasize:
+
+- connection source
+- session identity
+- session status
+- open versus delete action hierarchy
+
+Session rows should feel lighter than project rows because they are operational records, not top-level entities.
+
+### Terminal Page
+
+This is the core screen and should feel like a focused remote workbench.
+
+Structure:
+
+1. Header with session identity, working directory, and compact live/scrollback state
+2. Optional scrollback context block when the user is not following live output
+3. Terminal viewport framed as the dominant surface
+4. Bottom command deck with quick keys, text input, send action, mode toggle, and tools
+
+Specific visual goals:
+
+- make connection status immediately visible
+- visually separate terminal viewport from surrounding controls
+- turn the input bar into a compact command console instead of a generic form field
+- reduce noisy button chrome while keeping primary actions obvious
+- keep diagnostics and auxiliary tools accessible but secondary
+
+## Component Strategy
+
+Introduce small shared presentation widgets only where they reduce duplication across the touched pages. Expected candidates:
+
+- section panel container
+- status pill
+- empty-state block
+- page header treatment
+
+Do not create abstractions for single-use layout fragments.
+
+## Accessibility And Interaction Requirements
+
+- Maintain readable contrast for all text and interactive states
+- Preserve minimum touch target sizes
+- Keep all existing actions discoverable
+- Make focused and disabled states visibly distinct
+- Avoid motion-heavy effects; use restrained transitions only if they reinforce state
+
+## Error, Loading, And Empty States
+
+- Loading should feel integrated with the visual system, not like a default spinner dropped into the page
+- Error blocks should clearly separate title, explanation, and recovery action
+- Empty states should explain the next useful action in one sentence
+
+## Testing Strategy
+
+Validate through:
+
+- existing widget and integration tests that touch these pages
+- targeted Flutter test runs if touched UI tests exist
+- manual verification for project list, session list, terminal page, empty states, and terminal controls
+
+## Risks
+
+- Over-styling the terminal page could reduce readability or control discoverability
+- Excessive custom components could increase maintenance cost without improving clarity
+- Theme changes may affect existing widget tests that assert text or widget structure
+
+## Mitigations
+
+- Keep the terminal viewport itself visually quiet
+- Limit new abstractions to repeated presentation patterns
+- Verify the touched tests after implementation
+
+## Acceptance Criteria
+
+- The app no longer looks like default Flutter Material
+- Project list, session list, and terminal page share one coherent visual language
+- The UI reads as technological and minimal rather than generic or decorative
+- Primary actions are easier to scan than in the current design
+- Existing behavior remains unchanged