supersam/docs/superpowers/specs/2026-03-15-mobile-wave-1-design.md

# Mobile Wave 1 Design

**Date:** 2026-03-15

**Goal:** Make the product usable for full day-to-day work on phones across wave 1 scope: app shell, login, and the full orders workspace.

## Context

- The product currently uses desktop-first layouts with dense grids, side navigation, wide tables, and multi-column work areas.
- Recent orders work added a richer kanban, role-aware filters, and responsibility coloring, but many of those interactions still assume desktop space.
- Phone usage is now a first-class requirement, not a reduced read-only mode.
- Wave 1 is intentionally limited to:
  - app shell and navigation
  - login
  - orders workspace: registry, kanban, calendar, order detail, order editor, and filtering

## Decision

Implement a dual-presentation responsive architecture:

- keep existing business logic, routing, and data hooks
- preserve desktop-oriented layouts on larger breakpoints
- introduce mobile-specific representations for wave 1 screens where the workflow materially differs on phones

This avoids rewriting the app while still allowing a truly workable mobile UX.

## Architecture

### Responsive shell

`AppShell` becomes two navigation systems:

- desktop/tablet sidebar from `xl`
- mobile shell below `xl` with:
  - compact top header
  - section title and context
  - bottom navigation for primary sections

The mobile shell must keep sign-out and theme switching reachable without consuming permanent sidebar space.

### Orders workspace as mobile-first operations surface

The orders area becomes the center of wave 1 mobile work:

- registry turns into a stacked card list on phones
- kanban keeps column logic but becomes horizontally scrollable with fixed-width columns
- calendar uses a mobile agenda/list view instead of defaulting to a seven-column grid
- order detail opens as a full-screen mobile workspace
- order editing becomes a single-column form with sticky actions

The data model stays shared; only presentation changes by breakpoint.

### Modal strategy

Phone interaction must not rely on floating desktop dialogs. For wave 1:

- modals used for order detail or order creation should become full-screen overlays on mobile
- filter-heavy interfaces should use bottom sheets or mobile overlays rather than showing all controls inline

### Status management on mobile

Phone UX must not depend on drag-and-drop as the only operational path.

- kanban may still support drag on devices where it works
- status changes must always be available through explicit controls inside order detail
- dense tables or hover-only affordances are out of scope for phone UX

## UX Behavior

### Login

- single-column, narrow max width
- large controls and clear primary CTA
- no wasted side padding on small screens
- OTP step remains inside the same focused mobile card

### App shell

- top area shows current section, user role, and quick utility actions
- bottom nav surfaces primary destinations
- content padding is reduced on phones to maximize usable area

### Orders registry

- desktop table stays for larger screens
- mobile list cards show:
  - order number
  - customer
  - exact status
  - responsibility/department hint
  - updated time
  - short summary
- tapping a card opens the order workspace

### Orders filters

- phones show a compact search bar and a dedicated `Фильтры` entry point
- advanced filters open in a mobile overlay/sheet
- active filters are shown as removable chips under search

### Orders kanban

- horizontal scroll is mandatory on phones
- columns have fixed minimum width
- controls stack vertically above the board
- department filter and view-mode switch remain available on mobile
- completed column stays available as a valid target in stage mode

### Orders calendar

- mobile default is an agenda/day-grouped list
- desktop calendar grid remains for larger breakpoints
- month navigation stays, but the actual content favors readable daily lists on phones

### Order detail

- mobile uses a single-column full-screen view
- sections become stacked and optionally collapsible
- status action area is placed near the top
- notes/history/chat remain accessible without crowding the initial viewport

### Order editor

- single-column form
- grouped logical sections
- sticky footer action bar for save/create
- no two-column field layout on phones

## File Responsibilities

- `src/layouts/AppShell.jsx` — responsive shell split between desktop sidebar and mobile header/bottom nav
- `src/pages/LoginPage.jsx` and auth components — mobile-focused login spacing and flow
- `src/pages/DashboardPage.jsx` — mobile orchestration across orders views and modal/full-screen behavior
- `src/components/orders/OrdersTable.jsx` — desktop table + mobile card list
- `src/components/orders/OrdersCalendarView.jsx` — desktop month grid + mobile agenda view
- `src/components/orders/OrdersKanbanBoard.jsx` — horizontal mobile board and stacked toolbar
- `src/components/orders/OrderFilters.jsx` — compact mobile filters and active filter chips
- `src/components/orders/OrderDetailPanel.jsx` — mobile single-column detail layout
- `src/components/orders/OrderEditorPanel.jsx` — mobile form and sticky action bar
- `src/components/UI/Modal.jsx` — responsive behavior for full-screen mobile overlays if needed

## Testing Strategy

- add focused component tests for new mobile-specific render paths where practical
- verify responsive branch rendering with server-side markup tests for compact layouts
- run existing order-related tests to catch workflow regressions
- manually verify at narrow viewport widths:
  - login
  - mobile shell navigation
  - registry card list
  - kanban horizontal scroll
  - calendar agenda view
  - order detail usability
  - order editor sticky action area

## Out Of Scope

- wave 2 mobile work for driver/logistics/production dedicated screens
- wave 3 mobile work for admin and reference-heavy screens
- offline-first mobile behavior changes beyond current app capabilities