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