doormile_milderapp/DESIGN_SYSTEM.md

# Miler — Surface & Elevation System

Why the app looked flat, what replaced it, and the rules that keep it fixed.

**Scope.** `lib/` only. `lib/xpress` is the ported Xpress-rider lane and is not
part of this system.

---

## 1. The diagnosis, with numbers

The app did not look flat because it lacked decoration. It looked flat because
**the ground did nothing**, and every screen compensated privately.

Measured against the page ground:

| Token | Hex | Contrast vs canvas | Verdict |
|---|---|---|---|
| `neutralLight` | `#F2F4F8` | **1.021 : 1** | indistinguishable |
| `cardSurface` | `#EDEFF4` | **1.023 : 1** | indistinguishable |
| `surface` | `#FCF9F8` | **1.073 : 1** | invisible, and *warm* unlike everything else |
| `pureSurface` | `#FFFFFF` | **1.124 : 1** | the one that mattered — and too close |

A tonal difference does not begin to read as a *different surface* until roughly
**1.25 : 1**, and on the budget LCD this app ships to it needs the top of that
band. So a white card on a white page was not a card; it was a rectangle you had
to be told about. Every screen that wanted its content to separate therefore grew
its own border or its own shadow — and once one screen does that, they all do,
each in its own way. That is the mechanism that turns one product into a
collection of independently-built Flutter screens.

Five near-identical light tokens were also five names for about two decisions.

### The second half of the diagnosis

`MilerSheet` — the shared body under Home, Deliveries and Activity — painted
**white**. The `daylightSurface` canvas token existed but only two pages used it.
So the app's three main screens were a white page carrying white surfaces: a
1.0 : 1 step, which is not a step at all.

---

## 2. The fix: four layers

```
  0  canvas     the page itself. Never white.
  1  working    a region the rider reads or works in. White, no border.
  2  raised     something that acts. Same fill, plus lift.
  3  floating   over everything, with a scrim: sheets, dialogs.
```

Declared once in `lib/views/helpers/constants/miler_surface.dart` as
`MilerSurface`. Read that ladder when choosing a ground — not the raw colour
constants, which is what let five of them drift into meaning the same thing.

### Canvas — `#EEF2F7` → `#DEE3EA`

White now separates at **1.290 : 1** instead of 1.124. Surfaces separate on
their own, so the borders and shadows screens grew to compensate can come off
rather than being piled higher.

Nothing was traded for it: body text still clears **13.8 : 1**, and every
operational ink clears AA body on both grounds (see §4).

### Which screen stands on which rung

The rung is chosen by **what the screen actually draws**, not by preference:

| Screen | Ground | Because |
|---|---|---|
| Home | working (white) | rows on a spine — **no cards by design** |
| Activity | working (white) | same — a ruled record, not a stack of objects |
| Deliveries | **canvas** | its content genuinely *is* raised objects: the NOW card is a layer-2 command surface and needs a ground to sit on |
| Record / details | canvas | one white sheet plus folded groups |
| All modal sheets | floating | scrim + glass |

> **The trap, recorded because it was walked into.** Painting Home with the
> canvas produced a uniformly grey screen — it has nothing white on it to
> separate *from*, so the same flatness came back in a different colour. A
> darker ground only helps where something white actually stands on it.

---

## 3. Elevation

| Layer | Fill | Lift |
|---|---|---|
| working | `pureSurface` | none — the canvas step does the work |
| raised | `pureSurface` | `MilerSurface.raisedShadow` (`shadowSm`) |
| floating | `glassCard` | `MilerSurface.floatingShadow` + **scrim** |

`MilerSurface.scrim` (`0x66000000`) replaced Flutter's default `black54` on
every sheet. **The scrim is the separation; the shadow is not.** A sheet that
needs a heavier shadow to be legible is a sheet whose scrim is too weak — the
scrim is the knob.

### The one nesting the system allows

`MilerSurface.inset` — a quiet tonal block *inside* layer 1, for a fact grid or
a folded group. Only when the block is a different **kind** of thing from what
surrounds it. **Never for grouping**: grouping is whitespace, type and the
timeline, which is why a route reads as a route without a box around each stop.

---

## 4. Colour corrections that fell out of the canvas move

Two state inks landed in "AA large only" on the deeper ground and were darkened
by ~2% — the hue is indistinguishable at this distance, the arithmetic is not:

| Token | Was | Now | On canvas | On white |
|---|---|---|---|---|
| `acceptGreen` | `#047857` | `#047354` | 4.25 → **4.54** | 5.86 |
| `warning` | `#AE5008` | `#A44B08` | 4.12 → **4.54** | 5.85 |

Every operational ink now clears **AA body (4.5:1)** on both grounds. Pinned in
`test/surface_system_test.dart` — a contrast rule that lives only in a comment
is a rule the next hex nudge undoes.

### What the colours mean

| Colour | Means |
|---|---|
| Brand red `#960019` | identity, navigation, primary action — **not** error |
| Green | confirmed success, completion |
| Amber | genuine attention/exception only — **never** normal pending |
| Error red | failure, and semantically distinct from brand red |
| Neutral secondary | pending, waiting, metadata |

> Pending was amber once. On a fresh morning every kitchen is pending, so the
> screen opened in warning and left nothing to say with when a stop actually
> went wrong.

---

## 5. Rules

1. **Choose a ground from the ladder**, not from the colour constants.
2. **A container is justified when it is a layer** — a modal sheet, a floating
   command bar, a grouped operational workspace. Not because the content inside
   it is a group.
3. **No card inside a card**, and no white card on a white surface.
4. **If a surface needs a border to be seen, the ground is wrong** — fix the
   ground, not the surface.
5. **Never introduce a one-off colour, radius, shadow or spacing number in a
   page.** Five near-duplicate tokens is how this started.
6. **Measure.** Any new surface pair needs ≥1.25 : 1 to read as two surfaces,
   and any ink needs ≥4.5 : 1 on the darkest ground it can land on.

---

## 6. The second pass: the ladder made visible

The foundation pass fixed the ground; a device screenshot showed the result
still *read* flat — the silhouette of every page was unchanged. The second
pass gave the system its visible vocabulary, applied identically on Home,
Deliveries, Activity, Account and the sheets:

- **Hero heads.** A screen's key figure is a numeral (28sp w800, tabular),
  captioned small — never a sentence in body type. Home: `15 · stops left`
  with a 6pt determinate progress bar (canvas track, brand fill, green when
  done) and `9 of 24 done · ≈4h · 38.9 km` under it. Activity: `4 · delivered
  today`. Figures clamp at 1.3× text scale; captions ellipsise, numerals never.
- **Wells.** Anything that opens — Home's kitchens, Activity's trips — opens
  into a canvas-toned inset (`radiusLg`, small padding). The well is the
  ladder's one permitted nesting, and it is the *canvas* tone because that is
  the only grey that stands on white (1.290:1).
- **Tags.** A label a rider matches against the physical world (`Bag 3`) is a
  small filled tag: white on a well or tinted panel, canvas on white, brand
  10% when selected, error 8% for `Missing`. Same shape everywhere — Home
  rows, the pickup sheet, the confirm sheet, the Deliveries queue.
- **Placeholders recede.** An unassigned trip tab drops to `disabledFill` and
  w600 and says `None yet`; empty slots never compete with real work.
- **Account joined the ladder**: canvas ground, the identity + day-figures as
  one panel, each settings group a panel, labels on the canvas between them —
  scoped to the Account tab so the eight other `settings_ui` screens are
  untouched.
- **`neutralLight` is not a fill on white.** It measures 1.02:1 there; every
  such use found on these pages now takes the canvas tone. The token keeps
  its other jobs.

Pinned by: `home_gutter_test` (hero and route share an edge),
`stop_row_alignment_test` (the well's indent is bounded),
`home_structure_test` (one well, tags under 120pt, no borders or shadows in a
group), `activity_list_test` (a sheet is `working` or `canvas`, never the
warm off-white).

## 7. Known gaps

This was a foundation pass. It is not a completed product-wide redesign.

- **`GlassCard` still carries three separation mechanisms** — fill, border and
  shadow. Its rim is documented as a fix for shadows crushing on a budget LCD,
  reported twice from a device, so it was left alone rather than changed on a
  guess. It should be revisited *on a device* now that the ground works.
- **No typography or spacing consolidation.** Arbitrary `.sp` values still exist
  across pages; `MilerType` was not rationalised into a smaller scale.
- **Icon families are still mixed.** Lucide was adopted for Activity and the
  status vocabulary; Material rounded remains widespread elsewhere.
- **Account/Profile was not audited or migrated.**
- **No device or text-scale QA** of the new ground, and **no GPU profiling** of
  `milerGlassSheet`'s blur — so no blur change was made.