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

Mobile UI Refresh Design

Goal

Refresh the Flutter mobile app UI so it feels technological, fashionable, 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 layout structure, interaction flow, or 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, slightly premium, and intentionally designed

Design Direction

Use a precision-console aesthetic with a light editorial influence:

• Graphite-black surfaces with steel-tinted neutrals instead of pure blue-black panels
• Small, deliberate electric-blue accents reserved for focus, status, and primary actions
• Stronger typography rhythm so the product feels designed rather than merely themed
• Thin structural borders, restrained highlights, and minimal shadow so surfaces read like equipment modules
• Clear status signaling for connection state, live output, and input mode

This direction fits a remote terminal product better than either a generic dashboard or a decorative neon sci-fi treatment. The intended result is "high-end control surface" rather than "developer tool with a dark theme."

Problems In The Current UI

Visual

• The current dark theme already feels minimal, but not notably fashionable or technological.
• The app relies on repeated rounded panels with similar treatment, so every section carries the same visual weight.
• Accent color is present, but it behaves more like generic dashboard decoration than deliberate product branding.
• Status information, editable settings, and primary actions do not have a strong enough hierarchy.
• The terminal page has useful controls, but they are visually fragmented and do not read as one focused 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
• Surface, border, color, typography, and state-treatment updates only

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
• Reordering existing controls
• Adding or removing actions
• Changing page composition in a way that alters the current layout model

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: risks drifting into layout changes if not tightly constrained

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, but apply it in a layout-preserving way.

It reaches the real goal, which is a visible identity shift, without expanding into a broad refactor. The app needs a compact shared visual layer and better surface treatment, not new workflows or a broad design-system rewrite.

Visual System

Color

Build a dark-first palette with tinted neutrals:

• Background: deep graphite, not pure black
• Surface: steel-gray and smoke-blue neutrals with subtle tonal separation
• Accent: small-area electric blue for active controls, focus, and live states
• 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 and slightly tinted so the interface feels cohesive without looking loud.

Typography

Use the default Flutter font stack if introducing a custom font increases delivery risk, but tighten hierarchy through:

• larger, heavier page titles
• tighter letter spacing for major headings
• compact supporting metadata
• stronger small-label usage for state and section headers
• more intentional contrast between operational text and descriptive text

Typography should carry much of the visual identity because the target style is minimal. The interface should feel more editorial and deliberate without becoming decorative.

Shape

• Medium corner radius for primary panels and controls
• Straighter edges for the terminal work surface and dense control zones
• 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

The rhythm should feel engineered rather than spacious-for-its-own-sake.

Visual Texture

• Prefer dual-surface layering over heavy shadows
• Use restrained top-edge highlights or subtle inner separation to give panels more precision
• Avoid glow, blur, and decorative gradients
• Let the terminal viewport remain the quietest and darkest region on the screen

Screen Designs

Project List Page

Keep the existing page structure, but sharpen the 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
• recent session rows that read as subordinate operational history rather than equal peers to the project itself

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
• make the terminal viewport the dominant visual anchor without changing its placement or behavior
• make scrollback and mode indicators feel like system states rather than ordinary content blocks

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
• reusable surface styling helpers for primary modules versus subordinate modules

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
• Preserve current control locations and interaction sequences so visual polish does not become a behavior change

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
• Chasing fashion too literally could produce decorative noise that weakens the tool-like character
• 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
• Reserve accent color for action and state, not decoration
• Treat typography and edge treatment as the main source of sophistication
• 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, fashionable, and minimal rather than generic or decorative
• Primary actions are easier to scan than in the current design
• The terminal page reads as one deliberate workbench instead of separate stacked panels
• No layout structure or feature behavior changes are introduced
• Existing behavior remains unchanged