krow-worker-app/DESIGN.md

# Design

How the KROW worker app is put together, and why. [README.md](README.md)
covers what the app *does*; this covers how it looks, moves and is wired.

The HTML prototype was the reference for screens and flow, not a pixel spec.
Where this document and the prototype disagree, this document is what shipped.

## Who it is for

A shift worker, standing up, one hand on the phone, often about to start or
just finishing a shift. Every decision below follows from that:

- **One thumb.** Primary actions sit at the bottom of the screen. Buttons are
  52px tall and full width by default.
- **Glanceable.** A worker checking whether they are late should not have to
  read. Status is carried by colour and position before it is carried by text.
- **Nothing blocks the run.** A refused permission, a failed lookup or a
  missing document narrows what the app can do; it never dead-ends the worker
  on a step they cannot pass.

## Brand

Three colours do the work, defined once in `KrowPalette`
([theme.dart](lib/core/theme.dart)):

| Token | Value | Role |
|---|---|---|
| `blue` | `#3752A8` | 286CP. Every primary action, every header ground. |
| `blueDeep` | `#22366F` | The darker end of header gradients. |
| `blueTint` | `#E1E6F4` | Icon tiles and quiet blue fills. |
| `yellow` | `#F5C842` | 106CP. **Money, and anything waiting on the worker.** |
| `yellowSoft` | `#F7E4AE` | Yellow backgrounds that text sits on. |
| `sage` | `#E9F3EC` | 621CP. A tint for quiet inset blocks, not the canvas. |
| `ink` | `#26353E` | Body text, and the backdrop behind the phone frame. |
| `line` | `#CFDDD3` | Hairline borders. Carries every card edge. |
| `mute` | `#65727A` | Secondary text. |

The yellow rule is the one worth protecting. Yellow means *this is money* or
*this needs you* - pay figures, a timecard awaiting review, a missing
document. Using it decoratively costs the app its only urgency signal.

**Type** is Poppins throughout, pulled by `google_fonts` and applied as a whole
text theme so no screen picks its own family. Weights in use: 500 for body,
600 for emphasis and buttons, 700 for headings.

## Surfaces

The canvas is white. Every scaffold, app bar and content sheet is
`Colors.white`; sage survives only as a tint inside white cards, where an
inset block needs to read as recessed.

Material elevation is off. `AppBarTheme` and `CardThemeData` both set
`elevation: 0`, and separation comes from a 1px `line` border instead of a
shadow. That border is doing all the work now that cards are white on white -
removing it would dissolve every card into the page.

Shadow is kept for things that genuinely float above the surface rather than
sit on it - the travelling nav pill, the selected day in the week strip, the
frosted segmented control, the onboarding art. Reaching for a shadow to
separate a static block is the wrong move; use the hairline.

Corner radii cluster deliberately: **16** for cards and blocks, **14** for
buttons and inputs, **10-12** for chips and small pills, **7-11** for icon
tiles, **28** for the phone frame. Anything outside that set should have a
reason.

## Layout patterns

Three header treatments, and a screen picks one:

- **`KrowSliverHeader`** ([collapsing_header.dart](lib/widgets/collapsing_header.dart))
  - the main tabs. Pinned, shrinks from expanded to collapsed as content
  scrolls under it. A tall header pinned at full size would cost a quarter of
  the screen for the whole session; collapsing keeps the context and gives the
  space back.
- **`BrandHeader`** - pushed detail screens. Fixed, scrolls away.
- **`BrandSurface`** - the blue ground both sit on: brand colour, rounded
  bottom, and two soft radial glows. The glows are quiet alone, but they give
  the frosted controls on top something to refract.

`GlassSegments` ([glass_segments.dart](lib/widgets/glass_segments.dart)) is the
segmented control that rides on those headers - a real `BackdropFilter` blur
with a bright top edge and darker bottom edge, so it reads as glass rather
than a flat tint.

## Component inventory

Everything shared lives in [widgets/](lib/widgets). The rule is that a screen
composes these and does not restyle them.

| Component | Job |
|---|---|
| `SectionLabel` | Small uppercase heading above every group |
| `KrowCard` | The white rounded container for grouped content |
| `ShiftCard` | The one card shape: identity, hairline split, money band, status bar welded to the bottom |
| `NavTile` / `TileGroup` | Icon tile, title, subtitle, optional badge, chevron - grouped with hairline dividers |
| `StatusChip` | Status pill. `ChipTone.yellow` marks anything waiting on the worker |
| `InfoBanner` | Soft informational panel; `warning: true` switches it to yellow |
| `DetailRow` | Dotted-leader row, label left, value right |
| `StatSlab` / `StatSlabRow` | Three-up figure blocks, fixed height, text scales down rather than wrapping |
| `StatRail` | Horizontal rail of small stats divided by hairlines |
| `KrowProgressBar` | Progress that grows into place, so a change is something you see happen |
| `MiniBarChart` / `LegendDot` | Earnings charts |
| `WeekStrip` | Seven-day selector; a dot marks a day with something on it |
| `BusinessBadge` / `MetaPill` | Business identity and shift metadata |
| `EmptyState` | Every empty list |
| `HeaderIconButton` | Round icon button, works on light or dark ground |
| `KrowWordmark` | The brand mark, an alpha mask tinted to any colour |
| `KrowNavBar` | Bottom navigation |
| `SwipeAction` | Slide-to-confirm, for actions a stray tap must not trigger |
| `Entrance` | Staggered fade-and-lift for the rows of a list screen |
| `PressScale` | The give-under-the-thumb press state, inside the shared cards |
| `PhoneFrame` | Holds the app to phone proportions on wide viewports |

`SwipeAction` is the one control shaped as a pill rather than at the 14px
button radius, and that is the point: it is the only thing in the app you drag
instead of tap, and looking slightly unlike a button is what says so before
you touch it. Its hint animation - a sheen crossing the track, chevrons
lighting in sequence - runs three cycles and stops rather than looping
forever, because a control that never stops animating never lets the widget
tree settle, which hangs `pumpAndSettle` in any test that reaches a screen
holding one. It re-arms when the control becomes enabled or a swipe falls
short.

`StatSlab` is worth calling out as the house pattern for text that must not
reflow: both lines are pinned to a fixed height and scale down instead of
wrapping, because a wrapping caption - "CLOCK OUT", "11:50 PM" - makes one
card taller than the two beside it and leaves the row ragged.

## Motion

Motion is used to explain structure, never for decoration. Durations sit
between 260ms and 360ms; anything slower is felt as lag by someone in a hurry.

**Two page transitions only** ([transitions.dart](lib/core/transitions.dart)):

- `Transitions.push` - going *deeper* (a shift, a document, a timecard). The
  incoming screen slides in from the right over 320ms; the outgoing screen
  eases back 12% and fades, which is what gives the push its depth. Reverse
  runs at 260ms.
- `Transitions.fade` - going *sideways*: splash, onboarding, sign-in steps,
  anything that replaces the screen rather than stacking on it. Cross-fade
  with a few pixels of rise, because a flat cross-fade reads as inert.

**The nav bar indicator travels.** Material's `NavigationBar` fades its
indicator out at the origin and in at the destination, so the selection
appears to teleport. `KrowNavBar` animates the selected index as a *double*,
so one value drives both the pill's position and every icon's colour, and the
icons hand the pill over as it passes. It stretches slightly mid-flight and
settles with `easeOutQuint` over 360ms.

**Tabs fade and lift** rather than cut, over 260ms. Deliberately not an
`AnimatedSwitcher`: that holds two copies of the shell at once, and the branch
navigators are keyed by `GlobalKey`, so duplicating them throws.
`_TabTransition` animates a single subtree in place, which also keeps each
branch's scroll position. Opacity floors at 0.35 - a tab that blinks fully out
reads as a glitch.

**Rows land in reading order.** Every list screen wraps its children in
`Entrance.stagger`, which fades and lifts each row into place 55ms after the
one above it. A screen that arrives fully drawn says nothing about how it is
put together; letting the rows land in order shows the reading order before
the worker has to find it. The stagger stops counting after six rows, so a
long list never has a row waiting a second and a half to appear.

The delay is folded into each `Entrance`'s controller as a leading `Interval`,
never run as a `Future.delayed`. A standalone timer outlives the widget it was
armed for - a `mounted` guard protects the callback but not the timer, which
then surfaces as a pending timer at teardown and keeps a disposed screen's
work alive.

**Cards give under the thumb.** `PressScale` shrinks a card to 97.5% while a
finger is down on it. Material's ink ripple answers after the fact, and on a
white card on a white page it is nearly invisible; a card that moves during
the press answers in the half-second that otherwise feels unresponsive. It
lives inside `KrowCard`, `NavTile` and `ShiftCard` rather than in any screen,
so every screen gets it without being touched. It listens with a `Listener`
rather than a `GestureDetector`, so it never competes for the gesture: the
InkWell underneath still gets its tap, and a scroll that starts on a card
still scrolls.

Scroll physics is left to the platform. Forcing `BouncingScrollPhysics`
everywhere looked smoother on long lists and broke every short one: content
that already fit could be dragged away from the header, leaving a gap.

## Navigation

[router.dart](lib/core/router.dart), go_router.

Sign-in lives outside the shell. The five tabs are a
`StatefulShellRoute.indexedStack`, so **each tab keeps its own stack and scroll
position**. Detail screens push over the whole shell - the nav bar goes with
them - so a pushed screen is unambiguously "deeper" rather than "elsewhere".

Tab order is **Shifts | Pay | Today | Clock | Profile**. Today sits in the
middle because it is the screen a worker opens the app for; the two browsing
tabs sit left of it and the two personal ones right. The branch order in the
router and the item order in `HomeShell` must stay in step - there is no
mechanism enforcing that, only a comment in both files.

The splash route reads persisted session state and sends the worker to
whichever step they last finished: onboarding, phone entry, the permission
run, or straight into Today.

## State

Riverpod, with a consistent split:

- **`Notifier` controllers own writable state** - `shiftsProvider`,
  `timecardsProvider`, `complianceProvider`, `availabilityProvider`,
  `profileProvider`, `sessionProvider`.
- **Plain `Provider`s derive everything else**, and screens read the derived
  value rather than recomputing it. `nextShiftProvider`,
  `completedEarningsProvider`, `hoursLoggedProvider`,
  `timecardsNeedingReviewProvider`, `complianceProgressProvider`,
  `isCompliantProvider`, `daysSetProvider` and friends all live beside the
  controller they derive from.

This is why the Clock tab can show a dot when a timecard needs review without
the shell knowing anything about timecards: it watches
`timecardsNeedingReviewProvider` and nothing else.

**What persists** (`shared_preferences`, injected in `main()` via
`prefsProvider`): sign-in and phone number, the three permission grants,
availability, and profile edits including skills. **What does not**: shifts,
timecards and compliance, which live in memory for the session and reset on
relaunch. [seed.dart](lib/state/seed.dart) anchors all demo content to *now*,
so the next shift always starts 20 minutes out - inside the clock-in window -
whenever the app is opened.

## Wide screens

Every screen is laid out for a thumb. Stretched across a laptop the same
screens read as a broken website rather than an app, so
[phone_frame.dart](lib/widgets/phone_frame.dart) wraps the router output:
below 600px it passes through untouched, and at 600px and up the app is pinned
to a 420x900 panel centred on an `ink` backdrop.

The panel overrides its own `MediaQuery` so the app measures itself against
the panel rather than the window - screens that size themselves as a fraction
of screen height (the permission sheets are `0.86`) would otherwise measure a
laptop window while drawing inside a phone-width panel. Window padding is
zeroed with it, since the browser's safe areas belong to page edges the panel
no longer touches.

## Accessibility and robustness

- **No fixed heights where text lives.** `KrowNavBar` takes its height from
  the item row rather than a constant, because a hard number has to be retuned
  every time the label grows - a bigger text scale, a longer word, a different
  font - and overflows the moment it is not.
- **Scale down, don't wrap**, in any row that must stay aligned (`StatSlab`).
- **Deferring is a real target.** Secondary actions like "not now" get a
  full-width 44px text button, not a small link.
- **Permissions never block.** Whatever the OS answers is recorded and the run
  continues. Once the OS stops showing its dialog, the app says so and offers
  system settings instead of re-asking into the void.

## Adding a screen

1. Route it in [router.dart](lib/core/router.dart) - `_fadeRoute` if it
   replaces what came before, `_detailRoute` if it goes deeper.
2. Pick a header: `KrowSliverHeader` for a tab, `BrandHeader` for a detail.
3. Compose from [widgets/](lib/widgets). If you need a new shared component,
   add it there rather than styling in place.
4. Read derived providers, don't recompute. If the value you want does not
   exist, add a `Provider` next to the controller that owns the source.
5. Use the palette tokens. No new hex literals for anything that has a token.

## Tests

[test/](test) covers the parts that break quietly: transition end states
(`transitions_test`), scroll physics per platform (`scroll_behaviour_test`),
layout invariants like equal-height slabs and nav labels (`widgets_test`,
`screen_layout_test`), and pay/timecard arithmetic (`shift_logic_test`).