doormile_customer_app/design/DESIGN.md

# Doormile Customer App — Design Documentation

How every screen is designed, why it is designed that way, and where each
decision lives in the code.

Companion to `README.md` (which covers running and shipping the app).

---

## 1. Principles

Five rules decide almost every argument in this app.

1. **One decision per screen.** A screen asks one thing and offers one dominant
   action. Everything else is secondary or absent.
2. **Lift, don't outline.** Surfaces separate through soft shadow on a warm
   canvas, not through borders. Borders appear only where an outline is
   genuinely load-bearing.
3. **Optional must look optional.** Anything the customer can skip is labelled
   *Optional* and, when skipped, described calmly — never with warning styling.
4. **Say it in customer language.** No consignment, waybill, AWB, MPS or piece.
   The customer books a pickup and sends packages.
5. **Complexity appears only when asked for.** Multi-destination, multi-package
   and every advanced field stay folded away until someone reaches for them.

---

## 2. Foundations

All of this lives in `lib/ui/tokens.dart`. No screen hardcodes a value.

### 2.1 Colour

One accent. Warm neutrals. Semantic colour used sparingly and only with meaning.

| Token | Hex | Used for |
| --- | --- | --- |
| `brand` | `#960019` | Primary actions, selection, live status, links |
| `brandPress` | `#7A0015` | Pressed state of a primary surface |
| `brandSoft` | `#FDF2F4` | Selected tiles, tinted glyph circles, brand chips |
| `brandLine` | `#F3D9DF` | Pressed state of a soft brand surface |
| `ink` | `#14100F` | Primary text — a warm near-black, never `#000` |
| `ink2` | `#5A5350` | Secondary text, lede paragraphs |
| `ink3` | `#8B8480` | Tertiary text, eyebrows, captions |
| `ink4` | `#B5AEAA` | Placeholders, disabled labels, chevrons |
| `canvas` | `#F7F5F3` | Page background — warm off-white |
| `surface` | `#FFFFFF` | Cards, sheets, the tab bar |
| `surfaceAlt` | `#F2EFEC` | Filled inputs, quiet chips, skeleton base |
| `hairline` | `#EFEBE8` | Dividers inside a shared surface |
| `border` | `#E3DEDA` | The rare real outline |
| `ok` / `okSoft` | `#0E6B46` / `#E9F4EF` | Delivered, money settled, confirmations |
| `danger` | `#B3231F` | Cancel and other destructive labels |

**Rules.** Green means completed or paid — never decoration. Red is either the
brand or destruction, and context always disambiguates. Disabled states desaturate
rather than grey out to a different hue.

### 2.2 Typography

**Inter**, bundled as a real asset in four weights (400/500/600/700) so the app
renders identically on every device. Headings carry tight negative tracking;
body text stays open.

| Style | Size / Height / Weight | Tracking | Used for |
| --- | --- | --- | --- |
| `display` | 32 / 1.14 / 700 | −1.1 | The one dominant line on a screen (tracking status, "Pickup booked") |
| `pageTitle` | 28 / 1.18 / 700 | −0.9 | Tab-root titles (Orders, Account) and the Home question |
| `title` | 26 / 1.2 / 700 | −0.8 | Step headings inside the booking flow |
| `heading` | 21 / 1.25 / 600 | −0.5 | Card headings, amounts |
| `sheetTitle` | 21 / 1.25 / 700 | −0.6 | Bottom-sheet titles |
| `cardTitle` | 17 / 1.3 / 600 | −0.35 | Card and row titles |
| `body` | 16 / 1.5 / 400 | −0.1 | Input text, long copy |
| `bodyStrong` | 16 / 1.4 / 600 | −0.25 | Emphasised row titles |
| `lede` | 15 / 1.5 / 400 | −0.1 | The supporting line under a heading |
| `value` | 15 / 1.4 / 500 | −0.15 | Data values in summary rows |
| `label` | 13 / 1.3 / 600 | −0.05 | Buttons-in-text, chips, inline actions |
| `small` | 13 / 1.45 / 400 | −0.05 | Captions, secondary metadata |
| `eyebrow` | 11 / 1.3 / 600 | **+0.85**, uppercase | Micro-labels: `PICKUP`, `SENDING TO`, `STEP 2 OF 4` |
| `sectionHead` | 15 / 1.3 / 600 | −0.2 | Sentence-case section headings ("Recent orders") |

Two label systems on purpose: **uppercase eyebrows** name a *field*, **sentence-case
section heads** name a *group*. Mixing them was the fastest way to make the first
version look like a wireframe.

### 2.3 Shape

`xs 10 · sm 14 · md 18 · lg 22 · xl 28 · pill 999`

Tightest on inputs (14), mid on buttons and tiles (18), wider on cards (22),
widest on sheets and the hero CTA (28). Radius increases with the size of the
surface, which keeps corner curvature visually constant.

### 2.4 Elevation

Four shadows, each with one job.

- **`soft`** — resting elevation for every card. Two layers: a 2px contact
  shadow plus a 24px ambient one at −12 spread. The contact layer is what stops
  cards floating.
- **`lift`** — brand-tinted, for the single hero CTA on Home.
- **`float`** — controls hovering over content (map badges, toast, locate button).
- **`sheet`** — upward shadow under a bottom sheet.

### 2.5 Spacing

- Page padding **20**, used everywhere so every screen shares a left edge.
- Minimum touch target **48**; primary button height **54**.
- Vertical rhythm in 4s: 4 / 8 / 12 / 16 / 20 / 26 / 28.
- Section gap 26–28, intra-card gap 12–16, label-to-field 8.

### 2.6 Motion

`fast 140ms · base 220ms · slow 340ms`, all on `easeOutCubic`.

Press feedback is a scale to 0.98–0.985 at `fast`. Selection and expansion run
at `base`. Progress rails and route drawing run at `slow`. Continuous animations
(radar, live dot, map pulse, skeleton shimmer) run on their own loops and are
the reason tests pump fixed slices instead of settling.

---

## 3. Component library

`lib/ui/widgets/` — screens are thin because these carry the design.

| Component | File | Role |
| --- | --- | --- |
| `DmButton` | `buttons.dart` | primary / soft / ghost / outline, busy state, optional trailing icon |
| `DmChipButton`, `DmTextAction`, `DmIconButton` | `buttons.dart` | secondary affordances |
| `DmTopBar`, `DmStepHeader`, `DmFooter`, `DmPageTitle`, `DmScreenHeader` | `chrome.dart` | screen scaffolding |
| `DmOptionTile`, `DmActionRow` | `option_tile.dart` | selectable list card, tappable action row |
| `DmTextField`, `DmSegmented`, `DmRow`, `DmRowGroup`, `DmSwitch` | `inputs.dart` | form controls |
| `DmSummaryCard`, `DmSummaryRow`, `DmNote`, `DmConfirmedStrip` | `summary.dart` | fact display |
| `DmAsyncList`, `DmSkeleton`, `DmEmptyState` | `states.dart` | every remote-data state in one wrapper |
| `DmPill`, `DmLiveDot`, `DmAvatar`, `DoormileMark` | `misc.dart` | status and identity |
| `DmTag`, `DmChoiceChip`, `DmGridTile`, `DmStepper`, `DmInfoBanner`, `DmCopyRow` | `pieces.dart` | small primitives |
| `DmRouteMap`, `DmRadarPulse` | `route_map.dart` | painted map, matching animation |
| `DmRouteRail` | `route_rail.dart` | pickup → drop, vertical |
| `DmMilestones` | `milestones.dart` | the journey checklist |
| `DmToast`, `showDmSheet`, `DmSheetHeader` | `feedback.dart` | transient and modal |

Four of these do disproportionate work:

**`DmAsyncList`** wraps every backend-driven list. Loading skeleton, empty state,
error-with-retry and the success builder all live in one place, so a new endpoint
inherits four designed states for free. It is why the empty and error screens
look intentional rather than bolted on.

**`DmRouteRail`** — an origin ring, a hairline connector, a brand pin. The same
component anchors an order card, the tracking facts and the receipt, so a journey
reads identically wherever it appears.

**`DmRouteMap`** — a `CustomPainter`: rotated city blocks, white roads, a cubic
route stroked with a white casing then brand fill, an origin ring, a destination
pin with a blurred drop shadow, and a pulsing live marker positioned along the
path via `PathMetrics`. No map SDK, no API key. Swap it for a real map widget and
nothing around it changes.

**`DmOptionTile`** — white card at rest with `soft` shadow; selected becomes
`brandSoft` with a 1.5px brand border and a filled check; disabled drops to
`surfaceAlt` and shows the backend's reason. One component covers choose,
chosen, and cannot-choose.

---

## 4. Screens

### 4.1 Auth — Login, Sign up, OTP

`lib/ui/screens/auth/`

**Design.** A maroon brand panel at the top, a white sheet rounded 30px over it
holding the form. This is the only full-brand moment in the app: it establishes
the identity once, then the product stays quiet. `AuthScaffold` owns the panel,
the sheet, the pinned footer and the legal line, so all three screens are
identical in structure and differ only in fields.

- **Login** — Phone/Email segmented, `+91` prefix field with a clear button, a
  CTA that only enables on a valid input, and *New to Doormile? Create account*.
- **Sign up** — full name, phone, optional email. Validation is the same shape:
  the CTA enables, it never scolds.
- **OTP** — its own screen, not an inline step, because it has its own back
  semantics. The number is shown with a *Change* affordance, four large boxes
  auto-advance, a pasted code spreads itself across them, a resend countdown
  ticks from 0:30, and verification fires automatically on the fourth digit.

**Why a brand panel here and nowhere else:** auth is the one screen with no
content of its own, so it is the only place a large colour field costs nothing.

### 4.2 Shell and navigation

`shell_screen.dart` — Home · Orders · Account in an `IndexedStack`.

The bar **floats**: a white surface inset 16 from the edges, radius 28, lifted
by a two-layer shadow, so it sits on the canvas like every other surface rather
than sealing the bottom of the screen. The active tab is a `brandSoft` pill that
**slides** between destinations on `easeOutBack`, its icon switching from
outline to filled with a small upward nudge and its label easing to `w600` in
brand. Inactive icons and labels stay `ink3`.

Booking and tracking screens are **pushed over** the shell, so the tab bar never
appears where it would compete with a step flow.

### 4.3 Home

`home_screen.dart`

Three things, in priority order:

1. **Greeting + question** — "Good afternoon, Joe" in `lede`, then "Where should
   we pick up?" in `pageTitle`. The screen asks the question the CTA answers.
2. **Book a Pickup** — the only maroon block in the app, radius 28, `lift`
   shadow, title + one supporting line + an arrow in a translucent circle.
3. **What's happening** — an *Active* card (live dot, window tag, stage, who is
   coming, Track →) and recent orders as route cards.

Pull-to-refresh re-detects location and refreshes orders. The pickup-address row
was removed once the pin moved into booking step 1 — Home should not carry a
setting.

### 4.4 Booking

Four steps, a shared `DmStepHeader` (`STEP n OF 4` on the left, the step name on
the right, an inset rounded progress rail beneath).

**Step 1 — Pickup point** (`pickup_location_screen.dart`)
Map panel with a pulsing pin and a locate button, the detected address in a card
with *Change* (opens the place-search sheet), and **Next**. Location is detected
first; correcting it is one tap; nothing is typed unless the customer wants to.

**Step 2 — Destination** (`destination_screen.dart`)
The screen that carries the multi-destination model without exposing it.

- Opens on a **state chip row** (horizontal, scrollable). Only states we can
  actually serve appear — a state with nothing open is never offered. Choosing
  one reveals a **two-column district grid** of serviceable districts only.
  Unsupported places are never disabled tiles; they are named once, quietly:
  *"Coming soon: Madurai"*. The delivery promise moves to the settled card,
  where it informs a decision instead of decorating a picker.
- Choosing a district **collapses the block into a card**: the place, *How many
  packages?* with a `− 1 +` stepper defaulting to 1, and *Add exact delivery
  details · Optional*.
- Below it, a quiet **+ Send to another place**. That is the entire
  multi-destination affordance — one text action, absent until the first place
  is settled.
- Returning from Review shows settled cards, not the picker (`initState` opens
  the first incomplete block, or none).

Caps come from `BookingLimits` (backend-served, 20 packages / 5 destinations).
When a cap is reached the action is replaced by a plain sentence — *"Up to 5
places in one pickup. Book another pickup for more."* — never an error.

**Step 3 — Pickup time** (`slot_screen.dart`)
The pickup address restated in a compact card with *Change*, then windows
grouped by day. Each slot card can carry badges (*Fastest pickup*, *4 Milers
nearby*) and a caption; full windows are shown disabled with their reason. The
slot belongs to the whole pickup — one visit collects everything.

**Step 4 — Review** (`review_screen.dart`)
Compact by design and identical in shape for one destination or five.

- Route map with a badge that adapts: *Direct door-to-door transit* or *One
  pickup · 3 destinations*.
- Summary card: one **connected rail** — the pickup origin, then every
  destination hanging off it with its package count, exactly as an order card
  reads. `DmRouteRail` takes a list of stops for this. *Edit* sits on the
  pickup row, *Change destinations* under the stops, and **Pickup time** is the
  row beneath.
- Optional omissions are stated once, calmly: *"Not added — the Miler can
  confirm this at pickup."* With several places it becomes a single line rather
  than repeating.
- For multi: `6 packages · 3 destinations` · *One Miler visit*.
- Combined estimate with the honest caveat that the final amount settles after
  the Miler verifies.
- One dominant CTA: **Book Pickup**.

**Confirmation** (`confirmed_screen.dart`)
A green check that pops in on `easeOutBack`, "Pickup booked", the package
summary as a brand tag, a map with a *Searching for the nearest Miler* badge,
the reference with a copy action, the scheduled window and destinations, and two
quiet informational banners. Then **Track pickup** / **Back to home**.

### 4.5 Tracking

`tracking_screen.dart` — one screen that changes shape by stage.

- **Status header.** Eyebrow (`PICKUP STATUS` / `ORDER STATUS`) with a status
  pill, then the dominant line — personalised where it helps: *"Arun Kumar is on
  the way"*. Below it one or two fact chips (ETA, window).
- **Hero.** While a Miler is being matched: a **radar pulse** with three
  expanding rings. Once assigned: the **route map** with the live marker, badged
  *En route · 1.4 km away*.
- **Miler card.** Avatar, name, rating and completed pickups, vehicle and type,
  then **Call Miler** (soft) and **Message** (outline).
- **Milestones.** Seven customer stages, not nine backend ones: *Pickup booked
  → Miler assigned → Pickup in progress → Package collected → In transit → Out
  for delivery → Delivered*. Operational detail — "Miler on the way", "Miler
  arrived at your door", "Order created" — appears as one line of context under
  the milestone in progress, never as another permanent row. Completed
  milestones carry a filled check and a timestamp; the current one a ringed
  marker and a **LIVE** tag.

  Status pills everywhere use the same customer language
  (`JourneyStage.milestoneLabel`), so a pill never reads "Order created".
- **Your packages.** Appears **only** after `orderCreated` and only when the
  pickup carried several destinations — each with its own tracking ID, package
  count and status pill. Before collection the customer has one scheduled visit,
  not several shipments, and the UI says exactly that.
- **Facts.** Route rail plus pickup window and reference/tracking number.
- **Footer.** *Cancel pickup booking* while backend policy allows it, then
  *Need help with this order?*, then *Book another pickup* once finished.

### 4.6 Orders

`orders_screen.dart`, `order_row.dart`

Page title with a live subtitle ("3 bookings in progress"), an Active /
Completed / Cancelled segmented control, and **route cards**: a compact
`DmRouteRail`, a hairline, then the identifier and its facts on the left and a
status pill on the right.

**Ownership changes at collection.** Before the Miler arrives, a booking is one
row — *"Pickup DM-482913 · 3 packages · 2 destinations"* — because the customer
has one scheduled visit. Once verification creates the orders, each destination
stands on its own row with its own tracking number and journey, carrying a quiet
line back to the visit they shared: *"Collected together · Pickup DM-471200"*.
`AppState.entriesOf` produces these rows; the card renders either shape.

Opening a destination row follows **that order** — tracking takes a
`focusedDestination` and shows its own status, milestones and rail, with the
sibling packages listed beneath. Live rows open Tracking; finished ones open the
receipt.

### 4.7 Order details (receipt)

`order_details_screen.dart`

For a finished order: status and delivered date, the full route rail, then
**Collected at your door** — what the Miler actually recorded at pickup:
the photographs they took (one per package, captioned "1 of 3"), the **weighed
weight**, and who weighed it and when, tagged *Miler verified*. This is the
customer's evidence of what was handed over, and the weight the final price was
calculated from.

Then a **Packages** breakdown when there was more than one destination, and a
**Payment** block itemising parcel, base fare, distance, weight adjustment,
verified weight, **total paid** and method. Then the facts (reference, per-destination tracking,
window, recipient, collected by) and the journey milestones.

This screen answers "what did it cost and when did it land" without making
anyone hunt.

### 4.8 Account

`account_screen.dart` — a profile card, then grouped rows: preferences, then
**Prototype controls** (simulate empty service areas / network error / slow
network, reset data). Sign out is a ghost danger button, and the build version
sits quietly beneath.

The prototype controls are deliberately in the product rather than hidden: they
are how anyone reviewing the app reaches the states that are otherwise hard to
produce.

### 4.9 Sheets

`showDmSheet` gives every sheet the same grabber, 28px top radius and padding.

- **Place search** — search field, debounced results, skeletons while loading.
- **Delivery details** — the optional address and recipient fields for one
  destination. *Save details* / *Skip for now*.
- **Cancel booking** — the reference and window restated, optional reason chips,
  then *Keep my pickup* (primary) and *Yes, cancel pickup* (ghost, danger). The
  safe choice is the prominent one.

---

## 5. State design

Every remote list has four designed states, provided by `DmAsyncList`:

| State | Treatment |
| --- | --- |
| Loading | Shimmering skeleton rows at the real row height, so nothing jumps |
| Empty | 64px glyph circle, heading, calm explanation, optional soft action |
| Error | Wi-Fi-off glyph, *"Couldn't load this"*, the server's message, **Retry** |
| Unavailable item | Rendered, dimmed, with the backend's reason attached |

Disabled controls desaturate and stay in place. A capped action is replaced by an
explanatory sentence, never an alert.

---

## 6. Interaction and haptics

- Selection (option tile, chip, grid tile, stepper, segmented, tab) →
  `HapticFeedback.selectionClick()`.
- Booking confirmed and booking cancelled → `HapticFeedback.mediumImpact()`.
- Page transitions fade and slide 6% from the right on `easeOutCubic`.
- Pull-to-refresh on Home and Orders.
- Edge-to-edge, portrait-locked, dark status-bar icons — light over the auth
  brand panel.

---

## 7. Accessibility and resilience

- **No text-scale clamp.** Components adapt instead: rows grow vertically,
  buttons use a minimum height rather than a fixed one, the district grid drops
  to one column past 1.15×, and important text wraps. Ellipsis is reserved for
  secondary information — a delivery promise may truncate, a place name never
  does. Two widget tests drive the whole booking flow, Orders and the receipt at
  **1.8× text scale**; any overflow fails them.
- Every interactive surface carries `Semantics` with button/selected/enabled.
- Minimum 48px targets throughout.
- Every text row that can meet long data is `Flexible` with `ellipsis` — the
  widget tests run in a font where every glyph is full-width, which is how the
  remaining overflows were found and fixed.
- Contrast: `ink` on `surface` and white on `brand` both clear AA.

---

## 8. Voice

- Customer language only: *pickup*, *packages*, *destination*, *Miler*.
- Never: consignment, waybill, AWB, MPS, piece, manifest.
- Optional things are described, not warned about.
- Numbers are stated plainly — *"6 packages · 3 destinations"*, *"₹64 paid"*.
- Buttons are verbs: *Book Pickup*, *Track pickup*, *Cancel pickup booking*.

---

## 9. How design maps to code

```
lib/ui/tokens.dart      every colour, type style, radius, shadow, duration
lib/ui/widgets/         the component library — screens compose, never restyle
lib/ui/screens/         layout and copy only
lib/data/doormile_api.dart   the only place mock data lives
lib/state/app_state.dart     one source of truth; all stage side effects
```

Rules that keep it honest: a screen never hardcodes a colour or size; business
rules (serviceability, caps, slot availability, pricing) never live in a widget;
and anything the backend will own is already served through the API layer so the
swap is a body change, not a redesign.

---

## 10. What is real and what is mocked

**Real:** the whole UI, navigation, state machine, validation, caps enforcement,
optionality rules, and every loading/empty/error path.

**Mocked in `doormile_api.dart`:** serviceable states and districts, pickup
slots, geocoding and place search, fare estimates, booking creation and
cancellation, and booking limits. Each returns the shape a real endpoint would.

**Stand-ins:** `DmRouteMap` and `DmMapPanel` are painted, not a map SDK. Pickup
photos render as honest placeholders — `ParcelVerification.photos` holds the
references, so `Image.network(...)` drops straight in. The *Simulate update*
stepper on Tracking replaces backend push events — deleting that one widget is
the only change needed when real status events arrive.

**Not built yet:** session persistence, push notifications, in-app support chat,
per-destination cancellation (cancellation is whole-pickup, before collection
only).

---

*This document is the CX UI baseline. The visual system, screens and booking
structure are approved and settled.*