fixed designs and flow
This commit is contained in:
R-Bharathraj
276
DESIGN.md
Normal file
276
DESIGN.md
Normal file
@@ -0,0 +1,276 @@
|
||||
# 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`).
|
||||
Reference in New Issue
Block a user