M3 Phase 0+1: seed-generated tonal theme (light+dark) + MUI M3 re-skin foundation

Build-time M3 tonal generator from seed #6750A4 (@material /material-color-utilities) -> roles.ts + tokens.css (--md-sys-color-* CSS vars, light + html[data-theme=dark], zero runtime cost). MUI re-themed onto M3 roles with all existing token names aliased (theme.custom.*/accent/e1-e3/typography variants) so NO component/page edits needed. Roboto Flex self-hosted; M3 shape scale (+28 xl), 15-role type metrics, 6 motion springs, M3 state layers; ThemeModeProvider flips html[data-theme] (var flip, not re-render). Theme-only diff; tsc+build green. Foundation only — expressive components + per-screen restyle are later phases.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

AUDIT_REPORT.md

@@ -0,0 +1,239 @@
+# MilkWay ERP — Audit Report
+
+**Date:** 2026-06-11
+**Scope:** Go backend (`backend/`) + React PWA (`frontend/PWA/`) on a single Hugging Face FREE Docker Space (:7860), Aiven FREE Postgres (schema-per-profile staging/live).
+**Method:** Read-only multi-lens audit. Findings below are deduplicated and merged from the auditor lenses, with key claims spot-verified against source (`main.tsx`, `ErrorBoundary.tsx`, `useDateRange.ts`, `billing.go`).
+**Hard constraints enforced:** (1) FREE-ONLY — must run entirely on free tiers; (2) META PENDING — WhatsApp/Meta is NOT integrated, only `wa.me` deep links exist.
+
+> **Input note:** The supplied findings JSON was truncated mid-stream inside the `be-data` (LENS 5) auditor, and lenses 6–10 were not delivered to the synthesizer. This report consolidates lenses 1–5 in full plus the partial be-data set. Sections flagged "INCOMPLETE INPUT" indicate where auditor coverage was cut off and a re-run is advised.
+
+---
+
+## 1. Executive Summary
+
+The product is a functional, well-structured milk-dairy ERP, but it is **not yet production-honest**. It has a small number of true crash/blanking defects on the frontend and several **money-correctness bugs on the backend** that will quietly mis-bill customers — the most dangerous class for an ERP, because nothing visibly fails. The unit-travel feature (recently added) is the source of multiple defects: snapshots exist in the schema but billing/analytics still collapse mixed units, and the historical backfill hardcodes `'litre'`, actively corrupting any pre-existing kg/piece rows.
+
+On infrastructure, the product **can** stay 100% free, but only with discipline: do not run staging and live processes simultaneously against the same Aiven free instance (connection-cap risk), and shrink the eager JS bundle to survive cold starts of a sleeping ephemeral Space. The schema-change rule the project set for itself (versioned migrations before any column alter) has already been violated.
+
+### Top 5 things to fix first
+
+1. **Frontend crash containment** — a single root `ErrorBoundary` with no reset-on-navigation means *any* render throw on *any* screen blanks the entire app and stays wedged until a full reload. This is the root cause of the "a few screens crashed" report. (HIGH, FE)
+2. **Carry-forward double-counts prepayments / back-dated receipts** — verified in `billing.go:317-346`; customers are over- or under-billed silently. (HIGH/BLOCKER-class, BE)
+3. **Outstanding-aging double-counts debt across months** — the aging report sums the same balance in both the old bill's `remaining` and the new bill's `carry_forward`. Reported receivables are inflated. (HIGH, BE)
+4. **Unit-travel data corruption** — historical backfill hardcodes `'litre'` (mislabels kg/piece rows) and billing/analytics `GROUP BY product_id` with `MAX(unit_snapshot)`, merging physically different units into one line/number. (HIGH, DB/BE)
+5. **Delivered item with no configured price is silently billed at rate 0** — `prepareDelivery` discards `ResolveRate`'s `found` flag; missing/future-dated prices yield free milk. (HIGH, BE)
+
+---
+
+## 2. CRASHES (read this first — the user explicitly saw crashes)
+
+The reported "a few screens crashed" maps to **one architectural root cause** plus several render-throw triggers that hit it:
+
+### Root cause — single root ErrorBoundary, no reset
+- **Where:** `frontend/PWA/src/main.tsx:28` (only boundary, wraps the whole `<AppRoutes/>`) + `frontend/PWA/src/components/feedback/ErrorBoundary.tsx:15-43`.
+- **Mechanism (verified):** The boundary lives *above* the router. Feature routes each render their own `<AppShell>` with nothing between them and the root boundary. So a render-time exception **anywhere in any page body** replaces the **entire UI** (header, nav, everything) with the in-card "Couldn't render this" fallback. Worse, the boundary has no `location` key and no `componentDidUpdate`, so once `hasError=true` it stays errored across client-side navigation. The only escape is the fallback's "retry" button, which calls `reset()` and re-renders the **same crashing tree** — it immediately re-throws. **Net effect: one bad render = whole app dead until a hard reload.**
+- **Fix:** Wrap each lazy route element in its own `<ErrorBoundary>` *inside* `AppShell`, and key it by `location.pathname` (or call `reset()` on path change) so a crash degrades to an in-shell error and navigation recovers.
+
+### Things that can throw and therefore blank the app
+1. **`unitName()` returns `undefined` for unknown unit strings** — `features/catalog/unit.ts:29-31`. A truthy-but-unknown unit (future backend unit, wrong casing, legacy `'L'`/`'u'`) yields `undefined`; if used as a React `key` or rendered in a sensitive path it can throw/mis-render. Route through `normalizeUnit()` first. (LOW on its own, but feeds the crash boundary.)
+2. **`Money`/`Qty` render `'₹NaN'` / `'NaN L'`** — `components/format/Money.tsx:23-28`, `format/Qty.tsx:18-30`. No internal NaN guard; any API shape drift that drops `amount`/`qty` (e.g. a `by_product` row) on an unguarded call site prints NaN. Not a hard crash but a visible corruption that can cascade. Coerce non-finite → 0 internally.
+3. **Map over an undefined API field** — multiple pages read `c.by_product`, `unit`, `unit_snapshot` etc. that are tolerantly typed; a missing field that a `.map()`/`.length` doesn't guard throws into the single root boundary.
+
+### Hard-error (server-side) "blank screen" — not a JS throw, but a screen that won't load
+4. **Staff screen 400 for superadmin** — `features/admin/StaffPage.tsx:105` calls `usersApi.list({limit,offset,q})` with **no `org_id`**; `listUsers` → `requireOrg` returns **400 "org_id is required"** for a superadmin (token `org_id = NULL`). The Staff screen renders blank/error for superadmins. (HIGH, FE/contract.) Thread `org_id` (org picker) or make `listUsers` tolerate superadmin.
+
+---
+
+## 3. Findings by Severity
+
+> Deduplicated across lenses. Where multiple auditors reported the same defect (e.g. the ErrorBoundary, the IST date off-by-one, the unit-merge, `by_product` dead field, `SettingsInput` upsert, refresh-token user), they are merged into a single entry citing all locations.
+
+### BLOCKER
+*No findings were classified BLOCKER by the delivered auditors.* The money-correctness bugs below (carry-forward double-count, aging double-count, rate-0 billing) are HIGH but are BLOCKER-class in business impact for an ERP — treat them as ship-blockers.
+
+### HIGH
+
+| # | Title | Layer | Location | Detail | Fix hint |
+|---|-------|-------|----------|--------|----------|
+| H1 | Single root ErrorBoundary + no reset-on-nav blanks the whole app on any render throw | FE | `main.tsx:28`; `components/feedback/ErrorBoundary.tsx:15-43`; protected routes in `AppRoutes.tsx` have no boundary | See §2. One throw kills the entire UI and wedges it across navigation; retry re-throws. **Root cause of reported crashes.** | Per-route `<ErrorBoundary>` inside `AppShell`, keyed by `location.pathname`. |
+| H2 | Carry-forward double-counts a prepayment / back-dated receipt linked to its own bill | BE | `store/billing.go:317-346` (verified) | `earlierPayments = SUM(payments WHERE paid_on < period_start)` does NOT exclude payments with `bill_id = thisBill`; `paidAmount = SUM(payments WHERE bill_id = thisBill)`. A prepayment dated before the period but linked to this bill is subtracted in carry-forward **and** counted as paid → bill total drifts silently. | Scope carry-forward payments to `paid_on < start AND (bill_id IS NULL OR bill_id <> thisBill)`. |
+| H3 | Outstanding-aging report double-counts the same debt across consecutive months | BE | `store/analytics.go:309-374` | Each month's `carry_forward` already rolls the prior month's net forward, but the prior unpaid/partial bill still has its own positive `remaining`. `SUM(remaining)` counts the rolled balance twice. Receivables inflated. | Age only the latest bill per customer, or subtract net already embedded in a later bill's carry-forward. |
+| H4 | GenerateBill merges different `unit_snapshot`s into one line via `MAX(unit)` + `GROUP BY product_id` | BE | `store/billing.go:220-282` | Groups delivered rows by `product_id` only, labels the line with `MAX(unit_snapshot)`. If a product's unit changed mid-period, 10 (litre) + 5 (kg) collapse to qty=15 under one arbitrary unit. Bill is physically meaningless. | `GROUP BY product_id, unit_snapshot` — one line per (product, unit). Never `MAX()` the unit. |
+| H5 | Delivered item with no configured price is silently billed at rate 0 (`found` flag discarded) | BE | `api/deliveries.go:111-116`; `ResolveRate` in `store/prices.go:126-142` | `prepareDelivery` does `rate, _, err := ResolveRate(...)`, dropping `found=false`. Missing default price, or all prices effective *after* the delivery date (incl. back-dated deliveries), → rate 0, amount 0, delivered free. | If `!found` and status `delivered`, reject 400 "no rate configured for product on this date". |
+| H6 | Unit-snapshot/bill-line historical backfill hardcodes `'litre'` — mislabels all pre-existing kg/piece rows | DB | `db/migrate.go:266-267` (`ADD COLUMN ... DEFAULT 'litre'`) | Prior live schema allowed `unit IN ('litre','kg','piece')` (SCENARIOS_UNITS.md:186), so historical rows could be kg/piece. Backfill stamps every existing row `'litre'`; and because `'litre'` sorts after `'kg'`/`'piece'`, `MAX(unit_snapshot)` then mislabels merged lines too. Active data corruption. | Backfill from `products.unit`: `UPDATE ... FROM products WHERE id = product_id`. |
+| H7 | No versioned migration path — schema change via ad-hoc DO-block/ALTER, violating the project's own rule | DB | `db/migrate.go:218-267`; PLAN.md:244-245 | PLAN.md mandates a versioned migration tool before the first existing-column change. The unit-travel change (DROP+ADD `products.unit` CHECK, ADD `unit_snapshot`) is exactly that, done by hand-rolled idempotent DDL that re-runs every boot. | Introduce `schema_migrations` (or golang-migrate/goose); gate DDL on version. |
+| H8 | Staff list never sends `?org_id=` → superadmin gets a hard 400 and a blank Staff screen | FE | `features/admin/StaffPage.tsx:105`; `listUsers`→`requireOrg` (`customers.go:13-23`) | See §2 #4. `GET /api/users` requires `org_id` for superadmin; the list call never threads it. | Thread `org_id` (org picker) on StaffPage for superadmin, or relax `listUsers`. |
+| H9 | Bill generation is a fragile client-side per-customer loop with no resume | FE/INFRA | `features/billing/hooks/useGenerateBills.ts:46-91`; `BillingPage.tsx:63-72` | One `POST /bills/generate` per active customer, 4-way concurrency, in-component React state only. Navigate away / reload / background the PWA = loop lost, partially-billed month, no record of which customers ran. On a cold-starting free Space, transient 503s surface as false failures. | Server-side batch endpoint, or persist queue+progress to localStorage with cold-start-aware retry/backoff. |
+
+### MEDIUM
+
+| # | Title | Layer | Location | Detail | Fix hint |
+|---|-------|-------|----------|--------|----------|
+| M1 | Analytics date presets off-by-one for IST users (`toISOString` on local-midnight Date) — **verified** | FE | `features/analytics/useDateRange.ts:15,22-37` | `rangeForPreset` builds `new Date(y,m,d)` (local midnight) then `iso()` calls `toISOString()` → UTC. For IST (UTC+5:30), local midnight = 18:30 the previous day in UTC, so every preset (7d/30d/thisMonth/lastMonth) and aging `as_of` shifts back one day. | Format from local components: `` `${y}-${pad(m)}-${pad(d)}` ``. |
+| M2 | Backend analytics "now" uses server UTC, so IST dairy sees the window ending a day early near midnight | BE | `api/analytics.go:34-41`, `:152-154` | HF Space runs UTC; dairy is IST. When FE omits `from/to`/`as_of`, server defaults to its own date; 18:30 IST–midnight the UTC date is still "yesterday". Pairs with M1 — both ends drift. | Compute analytics "now" in `Asia/Kolkata` (configurable TZ). |
+| M3 | Dashboard/Reports per-customer per-unit qty is permanently dead — backend `TopCustomers` never populates `by_product` | BE | `store/analytics.go:265-300` vs `DashboardPage.tsx:338-344`, `ReportsPage.tsx:245-246` | `TopCustomers` scans only id/name/qty/amount/days, never sets `cs.ByProduct` (json `omitempty`), so `c.by_product` is always undefined; FE per-unit cells collapse to `''`/`—`. UI implies data that never arrives. | Populate `CustomerSales.ByProduct` (with `Unit`) via per-product `GROUP BY` carrying `p.unit`, mirroring `CustomerAnalytics`; or drop the per-unit UI. |
+| M4 | `useCustomers()` with no limit silently truncates to 50 → route filter & name maps incomplete for orgs >50 | FE | backend default `limit=50` (`api.go:192`); `RoutePage.tsx:63`, CustomerDetail products, Dashboard | Lookup-style consumers build dropdowns/maps from the first 50 rows with no pagination follow-up. Routes/customers beyond row 50 vanish from filters. | Page through items, or fetch with a large/`all` limit for lookup consumers (as billing preview already does). |
+| M5 | BottomNav highlights wrong tab (falls back to index 0) when a role lands on a screen with no matching tab | FE | `app/BottomNav.tsx:14`; `PaymentsListPage.tsx:41-44,109` (`current:'payments'`); `app/navConfig.tsx:33-44` | Admin/superadmin nav has no `'payments'` key, but admins reach `/payments` (CustomerDetail "Record payment →") and the page hard-codes `current:'payments'`. `findIndex` → -1 → highlights Dashboard. Disorienting dead nav state. | Render no active highlight when `current` ∉ items; or only pass keys present in the role's `NAV_TABS`; redirect superadmin away from `/payments`. |
+| M6 | Bill-line blended rate (`amount/qty`) drifts from line amount under rounding | BE | `store/billing.go:257-281` | Per-delivery `amount = qty*rate` is rounded to 2dp by the column; the line stores `rate = round2(SUM(amount)/SUM(qty))` and `amount = round2(SUM(amount))` independently. `qty*displayed_rate ≠ displayed amount` (paise mismatch). | Show the line rate as an explicit blended/derived value, or store rate NULL and display only qty + amount. |
+| M7 | `SalesSummary.total_qty` / `Bill.total_qty` sum quantities across heterogeneous units | BE | `store/analytics.go:115-126`; `billing.go:282,300` | Sums litres + kg + pieces + dozens into one scalar (100 L + 20 pc + 5 kg = "125"). Physically meaningless; printed on bills. | Drop cross-unit `total_qty` from bill/summary display in favor of per-unit totals. |
+| M8 | Analytics `SalesByProduct`/`CustomerAnalytics` emit a single `unit` via `MAX`/`GROUP`, mislabeling mixed-unit products | BE | `store/analytics.go:219-259`, `:414-447` (`COALESCE(p.unit, MAX(d.unit_snapshot), '')`) | Uses product's CURRENT unit; once a product's unit is edited, historical qty recorded under the old unit is summed and relabeled with the new — the "history re-interpreted" defect snapshots were meant to prevent. | Group analytics by `(product_id, unit_snapshot)`; report qty per unit. |
+| M9 | `products.unit` edit is unguarded despite snapshots — desyncs current vs historical semantics | BE | `store/products.go:107-119` | `UpdateProduct` mutates `products.unit` in place even when deliveries/bill_lines reference it; route projection & analytics fall back to the CURRENT unit for snapshot-less (backfilled-`litre`) rows. | Forbid changing `products.unit` once any delivery references it, or require a unit-migration flow. |
+| M10 | `AddAdjustment` then `GenerateBill` is non-atomic across two store calls/transactions | BE | `api/billing.go:184-197` | Adjustment inserted in one tx, bill recomputed in a separate one. On a sleeping Space a request cut between them leaves the adjustment row persisted but excluded from net/remaining/UPI. | Insert adjustment + recompute totals in ONE transaction. |
+| M11 | `DeleteAdjustment` does NOT re-generate the bill — totals keep the removed adjustment | BE | `api/billing.go:205-220` | Add path re-runs `GenerateBill`; delete path only deletes the row + busts analytics cache. Bill's deductions/additions/net/remaining/status/UPI still reflect the deleted adjustment. | After delete, look up the bill's period and call `GenerateBill(org, customer, year, month)`. |
+| M12 | `deletePayment`/`setBillStatus` don't re-derive carry-forward of LATER months | BE | `store/payments.go:183-208`; `billing.go` carry-forward | These refresh only the directly-linked bill. But a payment dated in an earlier month changes carry-forward of all later already-generated bills, which are never recomputed → stale running balances. | On payment/adjustment change, regenerate the customer's bills from the affected month forward (or compute carry-forward live from a ledger). |
+| M13 | Future-effective-only price → `ResolveRate` returns rate 0; with discarded `found`, mis-bills back-dated deliveries | BE | `store/prices.go:126-142`; `deliveries.go:111` | `ResolveRate` only considers `effective_from <= date`. A back-dated delivery whose product's only price is future-dated matches nothing → rate 0. Compounds H5. | Fall back to earliest price row when none is effective on/before the date, or reject; never return 0 as usable. |
+| M14 | Route projection loads the holiday flag but still projects every subscription slot on a holiday | BE | `api/route.go:57-88`, `mergeRouteRows:149-156` | `holiday` is loaded and returned but `mergeRouteRows` ignores it; the route shows a full delivery list on a declared holiday. Bulk-confirm then bills a non-delivery day. | When `holiday`, suppress projected (`recorded=false`) rows or mark `status='holiday'` (excluded from bulk-confirm by default). |
+| M15 | `products.unit` CHECK is DROPed then re-ADDed on every boot — concurrency race + transient-invalid window | DB | `db/migrate.go:228-261` | Each boot drops and re-adds `products_unit_check`. Concurrent boots (HF redeploy overlap, or staging+live both pointed at the DB) can drop the constraint while the other inserts. | Guard the block on "does the constraint already allow the 5 values" and skip; or one-shot versioned migration. |
+| M16 | Missing indexes on hot `bill_id` FK lookups (`bill_lines`, `payments`, `bill_adjustments`) | DB | `db/migrate.go:182-216` | Every `GenerateBill`/`GetBill`/`SetBillStatus`/`refreshBillPayment`/`AddAdjustment` filters child tables by `bill_id` with no index → seq scans that grow with data. | `CREATE INDEX IF NOT EXISTS` on `bill_lines(bill_id)`, `payments(bill_id)`, `bill_adjustments(bill_id)`. |
+| M17 | Money computed/round2'd in float64 despite NUMERIC storage — silent precision drift | BE/DB | `store/billing.go:23-27,55-57,96-134`; all `::float8` casts | Columns are NUMERIC(12,2) for exactness, but every read casts `::float8` and `round2 = math.Round(v*100)/100` runs in IEEE-754. Errors accumulate across many bills/lines (esp. carry-forward chains). | Do money math in the DB with NUMERIC (or a Go decimal type); use float8 only for final JSON projection. |
+| M18 | `payments.bill_id ON DELETE SET NULL` orphans receipts and breaks carry-forward accounting | DB | `db/migrate.go:203` | Deleting a bill NULLs the payment's `bill_id`. The payment still counts in carry-forward's `paid_on < start` subtraction (which ignores `bill_id`) but no longer toward any bill's `paid_amount` → same receipt double-applied. | Block bill deletion when linked payments exist, or re-point orphaned payments to an on-account ledger. |
+| M19 | Eager `vendor` chunk is 603 KB (188 KB gzip) — re-downloaded on every cold start of the sleeping/ephemeral Space | INFRA | `vite.config.ts:59-64`; `dist/assets/vendor-*.js` 603 KB, `vendor-charts` 578 KB, `vendor-motion` 110 KB | `manualChunks` lumps React+MUI+everything into one eager chunk on first paint for every role. The free Space sleeps with ephemeral FS; each wake serves assets fresh from the Go binary; evicted SW caches re-pull ~190 KB gzip before interactive. | Split MUI/react-query out of core vendor; lazy-load framer-motion. Shrink eager payload. |
+
+### LOW
+
+| # | Title | Layer | Location | Detail | Fix hint |
+|---|-------|-------|----------|--------|----------|
+| L1 | `unitName()` returns `undefined` for unknown unit strings | FE | `features/catalog/unit.ts:29-31` | Guard only checks falsy; a truthy-unknown unit yields `undefined`, rendering "Sold by " blank (and risks a throw if used as a key). | `return UNIT_NAMES[normalizeUnit(unit)]`. |
+| L2 | `Money`/`Qty` render `'₹NaN'`/`'NaN L'` on undefined/null numeric fields | FE | `components/format/Money.tsx:23-28`; `format/Qty.tsx:18-30` | No internal NaN guard; an unguarded call site after API shape drift prints NaN. | Coerce non-finite → 0 inside the components. |
+| L3 | `PaymentsListPage` passes `current:'payments'` for superadmin where no such tab exists | FE | `features/payments/pages/PaymentsListPage.tsx:41-44,109`; `navConfig.tsx:40-44` | Dead/disorienting nav state for superadmin on `/payments` (no crash). | Redirect superadmin away, or fall back `current` to a valid key. |
+| L4 | `RouteRow.unit` / `Delivery.unit_snapshot` sent by backend but absent from shared `api/types.ts` | FE | `api/types.ts:278-290,191-206`; `route.go:17`, `models.go:127` | Features only read them via narrow local casts; the canonical contract is out of sync. | Add `unit`/`unit_snapshot` to the shared types; remove cast shims. |
+| L5 | `PUT /api/settings` is a full-object upsert but `SettingsInput` is all-optional → partial PUT zero-wipes tax/UPI/currency | BE/FE | `api/settings.go:27-47`; `api/types.ts:454-463`; `SettingsPage.tsx:89-102` | Safe today (page sends all 8 fields) but a latent footgun: any future partial PUT zeroes absent fields. Also `default_tax_rate` is coerced to 0 on tax-off, losing the stored rate. | Make the PUT a partial merge (load + overlay non-nil), or make `SettingsInput` a required full object; stop zeroing the rate. |
+| L6 | Dead/duplicate ledger contract: backend `CustomerLedger`/`LedgerEntry` shipped but unused; FE rebuilds from two list calls | FE/BE | `models.go:218-233`; `useCustomerLedger.ts:69-82` | No endpoint wired; FE fetches bills+payments (`limit:200` each) and recomputes balance client-side (caps + double round-trip). | Expose & consume `/customers/{id}/ledger`, or delete the unused model. |
+| L7 | Stored auth user never refreshed after token rotation; refresh-failure UX is silent | FE/BE | `auth.go:112-117` (refresh response omits `User`); `client.ts:68-75`; `authStore.ts:115-142` | Refresh persists only rotated tokens; cached `AuthUser` (role + permissions) is stale until manual logout. A server-side permission/deactivation change won't take effect. Refresh failure clears session with no toast. | Include + persist user on refresh (or refetch `/users/me`); toast "Session expired" on failure. |
+| L8 | Dead hamburger/menu buttons render a focusable, labeled control that does nothing | FE | `RoutePage.tsx:144`, `LoginPage.tsx:84` (`onMenu={()=>{}}`); `StickyHeader.tsx:54-62` | A11y defect: keyboard/SR users tab to an actionable "Menu" button that opens nothing. | Omit `onMenu` / hide the leading slot when no drawer exists. |
+| L9 | Bill QR PNG is fetched even when no UPI VPA is configured (UPI/Meta pending) | FE | `BillDetailPage.tsx:78,229`; `useBills.ts:38-71` | `useBillQrUrl` fetches `/bills/{id}/qr` on mount regardless of `upi_vpa`; orgs without a VPA waste a request to the free Space then render the empty state. | Gate the fetch on `settings.upi_vpa` present. |
+| L10 | Money count-up re-animates from stale value on every cache invalidation | FE | `components/format/Money.tsx:38-61` | Totals visibly re-roll after every write (payment/adjustment/generate) even when unchanged — distracting on Dashboard/bill totals. | Count-up only on first mount / when delta exceeds a threshold. |
+| L11 | Subscription writes don't invalidate customer analytics → CustomerDetail stays stale | FE | `useSubscriptions.ts:22-25`; `CustomerDetailPage.tsx:111-130` | Sub create/update/delete bust only subscriptions + route, not `qk.analytics.root`; "Spend/Products/What they buy" projections go stale (arguably correct since analytics is delivery-derived, but undocumented). | Also invalidate `qk.analytics.customer`, or document analytics as delivery-only. |
+| L12 | `applyDeliveryAmount` computes amount as raw float (`qty*rate`) with no `round2` before persisting | BE | `api/deliveries.go:32-41` | Storage rounds via NUMERIC(12,2), but the 201 response carries the unrounded float (9.1575), so the immediate FE echo differs from the stored value. | `round2(d.ActualQty*rate)` in `applyDeliveryAmount`. |
+| L13 | Bill status `paid` on a zero-activity month with NEGATIVE carry hides customer credit | BE | `store/billing.go:119-124` | `remaining <= 0.001 → 'paid'` conflates "nothing owed" with "in credit/advance". | Distinguish `remaining < 0` as a `credit`/`advance` state. |
+| L14 | Subscription projection is TZ-safe but the delivery future-date guard uses server UTC | BE | `store/subscriptions.go:200-214`; `deliveries.go:78` | `ListActiveForDate` correctly uses date-only `EXTRACT(DOW)`, but `prepareDelivery`'s future-date guard uses `time.Now()` (UTC). Near IST midnight a valid same-day delivery can be wrongly rejected/accepted. | Use IST for the future-date comparison; document route `date` as an IST calendar date. |
+| L15 | `qr_token` globally unique per schema, no org scope; regenerated every call but discarded on conflict | DB | `db/migrate.go:171,177`; `billing.go:197-208` | UNIQUE across all orgs; `GenerateBill` mints a new token every call but `ON CONFLICT DO UPDATE` never writes it, so it's silently discarded — and a cross-org collision aborts the whole bill transaction. | Generate token only on first insert; scope uniqueness per org or retry-on-conflict. |
+| L16 | `audit_log` has no FK to orgs/users and no retention bound — unbounded growth on ephemeral free tier | DB | `db/migrate.go:47-57` | Append-only table for every record/delete/login, no cascade, no retention; risks Aiven free storage cap. | Add a `created_at` index + scheduled retention delete (e.g. 90 days). |
+| L17 | Single connection pool (`MaxConns=8`) shared across tenants; no `statement_timeout` for Aiven free | INFRA | `db/db.go:32-33` | One process is survivable, but staging+live simultaneously plus Aiven's own connections can exhaust the free connection cap; no `statement_timeout` means a runaway query can hold a connection indefinitely. | Set `statement_timeout` (e.g. 20s) in RuntimeParams; right-size `MaxConns` under the free cap. |
+| L18 | Redundant `DROP INDEX IF EXISTS idx_payments_paid_on` runs on every boot | DB | `db/migrate.go:212-216` | Harmless dead DDL forever — symptom of no versioned migration ledger. | Move one-shot cleanups into a versioned migration that records completion. |
+| L19 | `bill_lines.product_id ON DELETE SET NULL` loses product attribution (truncated in input) | DB | `db/migrate.go` (line cut off in source JSON) | Deleting a product NULLs historical bill-line attribution; line loses which product it was. **Detail truncated in auditor input — re-confirm.** | Restrict product deletion when bill_lines reference it, or keep a denormalized name/unit snapshot. |
+
+---
+
+## 4. FREE-TIER & COST
+
+**Verdict: the product CAN remain 100% free on HF free Docker Space + Aiven FREE Postgres, but only under explicit discipline. It is not automatically safe — several patterns push toward free-tier limits.**
+
+| Risk | Where | Limit / ceiling | Status |
+|------|-------|-----------------|--------|
+| Aiven connection cap | `db/db.go:32-33` (`MaxConns=8`) | Aiven free ≈ ~20 total connections incl. console/background | **SAFE for ONE process. NOT safe if staging + live run simultaneously** (2×8 + Aiven overhead can exhaust the cap; new boots fail at Ping/Connect). Do not run both profiles against the same instance at once. |
+| Aiven storage | `audit_log` (L16), no retention | Aiven free storage is small | **AT RISK over time** — unbounded append-only audit table + bill/delivery growth. Add retention. |
+| No `statement_timeout` | `db/db.go` (L17) | — | **RISK** — a runaway query can pin a scarce connection indefinitely. Set a 20s timeout. |
+| Cold-start asset re-pull | `vite.config.ts` (M19) | HF free Space sleeps + ephemeral FS | **COST-FREE but UX cost** — 603 KB eager vendor (188 KB gzip) re-served on each wake / SW-eviction. Not a money risk; shrink for usability. |
+| Client-side bill loop on cold start | `useGenerateBills.ts` (H9) | — | Sleeping Space → first request is a slow cold start; the 4-way loop surfaces transient 503s as false failures. No cost, but data-integrity risk (partial month). |
+| Ephemeral FS | HF free Docker | No persistent disk | All state MUST live in Aiven Postgres (it does). QR blobs etc. must not be written to local disk expecting persistence. **OK as designed.** |
+
+**Safe ceiling to operate within free tiers:**
+- Run **exactly one** backend process per Aiven instance at a time (never staging + live concurrently against the same DB), OR give staging its own free instance. Keep `MaxConns` so that `processes × MaxConns + Aiven_overhead < ~20`.
+- Add `statement_timeout` and an `audit_log` retention job to stay under storage/connection limits.
+- Nothing in the audited code requires a paid HF GPU/persistent disk or a paid Aiven tier. **No finding forces a paid upgrade.** The free path is viable.
+
+---
+
+## 5. META / WHATSAPP PENDING
+
+**State today (honest):** Only `wa.me` deep links exist. The full Meta/WhatsApp integration (Business API + the `whatsapp-web.js` service described in PLAN1.md) is **NOT integrated**. Nothing in the audited code assumes Meta is done.
+
+**What's pending:**
+- WhatsApp Business API / `whatsapp-web.js` service from PLAN1.md — not present.
+- Server-initiated message sending, delivery receipts, templated bill/payment notifications — none exist; the app can only open a `wa.me` link in the user's WhatsApp client.
+
+**What is honest vs. what overreaches:**
+- The `wa.me` deep-link approach is honest and free — it does not claim automated messaging.
+- **Overreach risk:** UPI/QR rails are presented as if provisioned, but L9 shows `useBillQrUrl` fetches a QR even with **no `upi_vpa`** configured, then renders an empty state. The QR/UPI payment path is effectively not-yet-real for orgs without a VPA and should be gated. Do not present UPI collection as live until a VPA + reconciliation exist.
+
+**Is a free Meta path viable?**
+- `wa.me` deep links: **yes, free and already shipped** — this is the correct free baseline and should remain the default.
+- WhatsApp Cloud API: has a free conversation tier but requires a Meta Business account, a verified number, and a hosted webhook endpoint. On a **sleeping** HF free Space, inbound webhooks and message-status callbacks are unreliable (the Space may be asleep when Meta calls). A self-hosted `whatsapp-web.js` service needs a persistent long-running process with a stable session/disk — **not viable on the ephemeral, sleeping free Space.**
+- **Recommendation:** keep `wa.me` deep links as the free, honest mechanism. Treat true Meta automation as a paid/always-on-infra feature and do not promise it on the free tier. Flag any UI copy that implies automated WhatsApp sending today.
+
+---
+
+## 6. Prioritized Remediation Plan
+
+**Fix first (ship-blockers — crashes + money correctness):**
+1. **H1** — per-route ErrorBoundary keyed by pathname (stops the whole-app blanking; directly addresses the reported crashes).
+2. **H2, H3, M12** — carry-forward / aging double-count and later-month carry recompute (money correctness; verified). Treat as a single accounting-integrity workstream with M10/M11 (atomic adjustments).
+3. **H5, M13** — reject deliveries with no resolvable rate instead of billing at 0.
+4. **H4, H6, H8** — unit-travel correctness: `GROUP BY (product_id, unit_snapshot)`, fix the `'litre'` backfill from `products.unit`, and thread `org_id` on the Staff screen.
+
+**Fix next (high-value, lower blast radius):**
+5. **H7 + M15 + L18** — adopt a versioned migration tool; collapse the boot-time DDL churn.
+6. **M1 + M2** — IST date handling end-to-end (FE format + BE TZ).
+7. **H9** — server-side batch bill generation (resumable) — also reduces cold-start false failures.
+8. **M16** — add the `bill_id` indexes (cheap, broad perf win).
+9. **M3, M8, M9** — analytics per-unit + guard `products.unit` edits.
+10. **M19** — bundle split for cold-start UX.
+11. **Free-tier guardrails** — `statement_timeout`, right-size `MaxConns`, `audit_log` retention (§4), never co-run staging+live on one Aiven instance.
+
+**Fix opportunistically (LOW):** L1–L18 — group L1/L2/L4 (unit + NaN + contract types) and L5/L7 (settings merge + auth refresh) as small cleanups.
+
+## Do NOT fix / accept (these are fine as-is)
+- **Subscription projection TZ handling** (`subscriptions.go:200-214`) — correctly date-only; only the *caller's* future-date guard (L14) needs the IST fix. The projection itself is fine.
+- **Ephemeral FS reliance on Postgres for all state** — correct architecture for HF free; do not try to add local persistence.
+- **`wa.me` deep links as the WhatsApp mechanism** — the honest, free baseline; keep it. Do not block on Meta.
+- **Bill status `paid` for a true zero-balance month** — fine; only the *negative-carry credit* case (L13) is a cosmetic refinement, not a bug.
+- **Analytics being delivery-derived (not subscription-derived)** — defensible; L11 is a documentation/invalidation nicety, not a correctness bug.
+- **`MaxConns=8` for a single process** — adequate; only the *concurrent staging+live* scenario (L17) is the real risk.
+
+---
+
+## Appendix — Input completeness
+
+The findings JSON delivered to the synthesizer was **truncated** inside LENS 5 (`be-data`), with the final entry (`bill_lines.product_id ON DELETE SET NULL`, captured here as L19) cut mid-sentence, and **lenses 6–10 were not included**. Auditor coverage represented above: LENS 1 (fe-crash), LENS 2 (fe-contract), LENS 3 (fe-ux), LENS 4 (be-logic), LENS 5 (be-data, partial). **Recommend re-running the audit fan-out to recover the missing lenses 6–10** (likely security/auth, infra/Docker/HF, docs/PLAN consistency, etc.) before treating this catalog as exhaustive.
+
+---
+
+## 7. Recovered lenses 6, 8, 9, 10 (were truncated from the synthesis above)
+
+### Security (lens 6)
+| Sev | Title | Location |
+|-----|-------|----------|
+| HIGH | Login rate-limiter trivially bypassed by spoofing `X-Forwarded-For` → credential brute-force wide open | router.go:129-141 clientIP |
+| HIGH | Refresh token in localStorage relies on a "strict CSP" that **does not exist** (no CSP/security headers) | authStore.ts:11-16 |
+| HIGH | Refresh tokens not rotated/revocable: a stolen/old refresh token stays valid 30 days (no jti) | auth.go:82-117, jwt.go:12 |
+| MED | No password policy + silent bcrypt 72-byte truncation on user creation | users.go:80-83, password.go:12-18 |
+| MED | `POST /deliveries/bulk` has no array-length cap + N+1 DB lookups per row (authed low-priv DoS on free pool) | deliveries.go:149-179 |
+| MED | `updateSettings` skips struct validation + full-object upsert (stores unvalidated/zeroing values) | settings.go:27-47 |
+| LOW | No anti-clickjacking / `X-Content-Type-Options` headers on SPA+API | router.go:270-281 |
+| LOW | `users.manage`/`settings.manage` grantable to employees but inert (masks true privilege model) | permissions.go:31-32 |
+| LOW | Superadmin seed has no password-strength floor; root creds only in env, no rotation/audit | main.go:103-142 |
+
+### Reliability / ops (lens 8)
+| Sev | Title | Location |
+|-----|-------|----------|
+| HIGH | Boot does a single DB connect with **no retry/backoff** → an Aiven free cold-start/blip crash-loops the Space | main.go:29-34 |
+| HIGH | **No client-side request timeout** → first call after the Space sleeps hangs the UI indefinitely (a real "screen crashed" trigger) | client.ts:92-137, queryClient.ts |
+| HIGH | **Zero request/access logging** → production is undebuggable when the Space misbehaves | router.go:270-281 |
+| MED | No Postgres `statement_timeout` → a runaway query pins a scarce Aiven free connection | db.go:23-38 |
+| MED | In-memory rate-limiter resets on every Space sleep → brute-force throttle effectively defeated | api.go:45-54 |
+| MED | Cache cold after every wake → first dashboard load post-sleep pays full DB cost (FIFO not LRU) | api.go:26,45 |
+| MED | Route projection loads FULL unpaginated customer+product lists per request | route.go:53,63,67 |
+
+### Meta / WhatsApp (lens 9, details)
+| Sev | Title | Location |
+|-----|-------|----------|
+| HIGH | Backend never returns an empty `whatsapp_link` → the "No phone on file" fallback is unreachable; app can open a broken `wa.me` link | links.go:36-48, qr.go:105-111 |
+| HIGH | PLAN1 whatsapp-web.js (always-on Chromium + ephemeral FS + sleep) is **NOT viable on the free tier** as written | PLAN1.md:15,61-71,105 |
+| MED | Confirmed: no Meta Business API / no whatsapp-web.js code exists; nothing in the running product assumes either | repo-wide (only wa.me) |
+| MED | whatsapp-web.js carries unmitigated ToS/ban risk → unsafe as the primary channel even if hosting worked | PLAN1.md:21-25 |
+| LOW | Honest free Meta path = Cloud API free tier (user-initiated/service convos), not whatsapp-web.js | — |
+
+### Test quality (lens 10)
+| Sev | Title | Location |
+|-----|-------|----------|
+| BLOCKER | All DB-backed tests SKIP by default + **no CI** → the critical SQL (billing/analytics) is effectively untested in automation | e2e_test.go:208-211; no .github/workflows |
+| HIGH | Carry-forward + aging double-counts live entirely in untested SQL | billing.go, analytics.go |
+| HIGH | Frontend has **zero test infrastructure** (no vitest/RTL/playwright) → crash-prone render logic untested | package.json |
+| HIGH | Superadmin role has zero integration coverage (the crash surface) | e2e_test.go |
+| MED | Cross-org isolation test covers only ~4 of ~10 resources → IDOR gaps on writes | e2e_test.go:1085-1212 |
+| MED | `npm run lint` is a dead script (eslint not installed) | package.json |
+| MED | `-race` can never run here (no C compiler) → concurrency tests' value unrealized | ratelimit/cache tests |
+| LOW | Flaky wall-clock timing in cache TTL tests (no injectable clock) | cache_test.go:29-48 |
+
+> Note: §4 (Free-tier) and §5 (Meta) above already incorporate lens 7's conclusions. With these recovered lenses the catalog is now complete.

M3_THEME_PLAN.md

@@ -0,0 +1,221 @@
+# MilkWay ERP — Material 3 Expressive Re-Skin Plan
+
+> **For owner approval.** Analysis-only deliverable. No app code changed, no builds run. This plan consolidates four audits (`frontend/PWA/design/m3/m3-spec.md`, `current-theme.md`, `current-components.md`, `feasibility.md`) into one decision document.
+>
+> **One-line recommendation:** Re-theme MUI v6 to a seed-generated M3 tonal token system and hand-build ~7 expressive components on MUI primitives + Framer Motion springs — keep the data layer 100% untouched.
+
+---
+
+## 1. Executive summary — the honest verdict
+
+**The current theme is not worth keeping, and that is the correct call.** It is a competent, internally-consistent *generic SaaS / Material-2-era* theme — and that is exactly the problem. It is built on the wrong primitives for Material 3 Expressive (M3E), so this is a **token-model rebuild, not a palette tweak.** Concretely, the current `src/theme/`:
+
+- **Has a flat hand-picked hex palette** (`primary #1E6FE0`, `secondary #2E9E5B`, … — most are literally Tailwind defaults). No tonal ramp, **no `*-container` roles, no `on-*` roles, no tertiary, no surface-container ladder, no dark theme** despite the "dark-swap ready" comment. The codebase already *fakes* tonal fills by string-concatenating opacity onto hex (`` `${primary.main}14` ``) — the tell that the token model can't express what the design needs.
+- **Uses shadow-based elevation** (`e1/e2/e3` smeared across all 25 MUI slots) + 1px borders on every card. M3E is **tonal-elevation-first** (raise = swap surface-container tier, not add a shadow).
+- **Has a too-small, static shape scale** (`8/12/16/pill`) — missing `4` and the expressive `28`+ radii, and no concept of shape-morph on press/select.
+- **Has a bespoke 12-role MUI type scale** (`h1..button`), not the M3 15-role scale; no `display` tier (no hero typography), no `label` family, no emphasized weights.
+- **Has duration+cubic-bezier motion with exactly one (unused) spring.** M3E's signature is broad **spring physics + shape-shift**; the current vocabulary gives the opposite feel.
+
+**What is genuinely good and will be kept:** the *plumbing* — `createTheme` + `theme.d.ts` module augmentation, the token-discipline (only ~5 files contain raw hex; components read from theme), the 8px spacing grid (M3-compatible), the `prefers-reduced-motion` discipline, and `AppButton`'s state-machine engineering. We keep the mechanism and the file structure; we regenerate every value inside.
+
+**The target look (per the owner's reference screenshot):** soft **pastel tonal container** cards (surface-container / secondary- / tertiary-container fills) with **large 16–28px radii** and little-to-no border; **expressive typography** with hero display sizes; **springy shape-shift motion** (corners morph on press, FAB blooms into a menu); **state layers** instead of hover-hacks; and the new expressive components — **split buttons, button groups, docked/floating toolbars, FAB menus, M3 segmented buttons, and waveform progress.** None of these exist today.
+
+---
+
+## 2. Recommended approach
+
+### Chosen: **Approach A — Re-theme MUI v6 to M3 + ~7 custom expressive components on MUI primitives + Framer Motion.**
+
+**Justification (crisp):** The app is 102 of 114 `.tsx` files deep in MUI, with the data/TanStack-Query layer fully decoupled from the view layer. A re-theme is centralized (token generator + `components.*` overrides), incremental, and revertible per component, at **near-zero bundle cost** (`@material/material-color-utilities` runs at build time). It is the only path that reaches the screenshot while keeping the backend untouched. The expressive components MUI lacks are presentational and built on existing deps — no new runtime.
+
+**Rejected alternatives (from feasibility):**
+- **Approach B — `@material/web` (Lit):** disqualified. It is in **maintenance mode** ("pending new maintainers", last release v2.4.1, 2025-10-27), ships **no Card, Toolbar, Split button, Button group, or FAB menu**, and **never mentions M3 Expressive**. We'd hand-build the expressive components anyway, on top of an abandoned base, with React↔Lit interop tax, dual theming, and a *bigger* bundle. Rejected.
+- **Approach C — Hybrid MUI + a few MWC elements:** all of B's downsides for a subset of components that doesn't include any of the expressive ones we actually need. Buys nothing. Rejected.
+
+### What this approach will explicitly NOT do
+- **Will not** adopt `@material/web` / Lit web components.
+- **Will not** touch the backend, API contracts, TanStack Query hooks, or any data/business logic — this is a skin.
+- **Will not** rewrite forms or swap out `react-hook-form`.
+- **Will not** deliver pixel-perfect Google M3 fidelity — hand-built fidelity = effort invested, not free.
+- **Will not** ship full adaptive/desktop layouts (nav rail/drawer, multi-pane) in the core re-skin. M3 window-size-class adaptivity is flagged as a **follow-on phase**, not part of the baseline re-skin. (Optional MUI v6→v7 codemod is also out of scope / optional.)
+- **Will not** introduce dynamic (wallpaper-extracted) color — a fixed brand seed is used.
+
+---
+
+## 3. M3 design tokens to adopt (concrete values)
+
+All values below are the shipping M3 token set (material-web `tokens/versions/v0_192`) unless noted. Light theme is primary (app is light); a dark tonal set is an owner decision (§7).
+
+### 3.1 Color — seed → tonal palette → roles
+Generate from **one brand seed** via HCT (`@material/material-color-utilities`). Each of 5 source palettes (primary, secondary, tertiary, neutral, neutral-variant) + fixed error is sampled at tones `0,10,20,30,40,50,60,70,80,90,95,99,100` (+ neutral extras `4,6,12,17,22,24,87,92,94,96,98` — these feed the surface ladder).
+
+**Role → tone mapping (light / dark):**
+
+| Role | Light | Dark |
+|---|---|---|
+| primary | P40 | P80 |
+| on-primary | P100 | P20 |
+| primary-container | P90 | P30 |
+| on-primary-container | P30 | P90 |
+| secondary / tertiary | same 40/100/90/30 pattern on own palette | 80/20/30/90 |
+| error / on / container / on-container | E40 / E100 / E90 / E30 | E80 / E20 / E30 / E90 |
+| outline / outline-variant | NV50 / NV80 | NV60 / NV30 |
+| on-surface / on-surface-variant | N10 / NV30 | N90 / NV80 |
+
+> **Tertiary is the expressive accent** — used for delight (FAB-menu items, highlights, hero numbers). Use **container roles far more than raw primary** (softer pastel = the M3E feel).
+
+**Surface-container ladder (the pastel heart — tonal, not shadow):**
+
+| Role | Light tone | Use |
+|---|---|---|
+| surface-dim | N87 | dimmest bg |
+| surface | N98 | default page bg |
+| surface-bright | N98 | brightest bg |
+| surface-container-lowest | N100 (white) | lowest cards |
+| surface-container-low | N96 | |
+| surface-container | N94 | default card/sheet |
+| surface-container-high | N92 | raised (FAB rests here) |
+| surface-container-highest | N90 | menus, highest |
+
+Plus full inventory to emit: `*-fixed`/`*-fixed-dim`/`on-*-fixed(-variant)`, `inverse-surface`, `inverse-on-surface`, `inverse-primary`, `surface-tint` (=primary), `scrim`, `shadow`. **Status colors** (success/warning) re-derive from semantic container roles (success→tertiary/green-container, warning→amber-container, error→error-container) so they re-tone with the palette — kill the flat `customTokens.status` hexes.
+
+### 3.2 Shape scale (`md.sys.shape.corner.*`)
+
+| Token | Value | Typical use |
+|---|---|---|
+| none | 0 | — |
+| extra-small | 4 dp | small chips, snackbar |
+| small | 8 dp | text fields, small chips |
+| medium | 12 dp | small cards |
+| large | 16 dp | **default card** |
+| extra-large | 28 dp | **sheets, dialogs, large FAB, hero cards** |
+| full | 9999px (pill/stadium) | **buttons, chips, segmented** |
+
+Directional variants for sheets/rails (`extra-large-top = 28 28 0 0`, `large-start/end`). **Shape is animatable:** components shape-shift (button corners round→squarer on press; toggle round↔squircle; FAB→menu morph; split-button trailing button spins + reshapes on open). Defaults are **larger and more generous** than the current 16-max.
+
+### 3.3 Typography scale (15 roles; rem @16px base, px in parens)
+
+| Role | Size | Line | Weight | Tracking |
+|---|---|---|---|---|
+| display-large | 3.5625r (57) | 64 | 400 | -0.25 |
+| display-medium | 2.8125r (45) | 52 | 400 | 0 |
+| display-small | 2.25r (36) | 44 | 400 | 0 |
+| headline-large / medium / small | 32 / 28 / 24 | 40/36/32 | 400 | 0 |
+| title-large | 22 | 28 | 400 | 0 |
+| title-medium / small | 16 / 14 | 24/20 | 500 | 0.15 / 0.1 |
+| body-large / medium / small | 16 / 14 / 12 | 24/20/16 | 400 | 0.5/0.25/0.4 |
+| **label-large** (buttons) | 14 | 20 | **500** | 0.1 |
+| label-medium / small | 12 / 11 | 16/16 | 500 | 0.5 |
+
+Reference face **Roboto / Roboto Flex** (variable axes for emphasized headings). **Emphasized companion** = bump titles/labels to **600–700** on hero moments; keep body 400. Note: the app currently uses Inter — acceptable to keep brand-wise, but it must be re-mapped to these M3 metrics, not MUI's.
+
+### 3.4 Motion — spring physics (the biggest shift)
+Two spring families × 3 speeds. **Spatial** = position/size/rotation/**corner radius**, bounce allowed. **Effects** = color/opacity/elevation, **no overshoot**.
+
+| Spec | Damping | Stiffness | Use |
+|---|---|---|---|
+| spatial-fast | 0.6 | 800 | chips, small toggles, press bump |
+| spatial-default | 0.8 | 380 | most spatial moves |
+| spatial-slow | ~0.8 | ~200 | large/hero transitions |
+| effects-fast/default/slow | ~1.0 (no bounce) | ~3800 / 1600 / 800 | color/opacity/elevation |
+
+Two schemes: **Expressive** (bouncier — hero/key interactions) and **Standard** (utilitarian flows). Framer port: `type:'spring'`, spatial `damping .6–.8` (bouncy), effects `damping ~1` (crisp). Legacy easings retained for CSS-only cases: **emphasized** `cubic-bezier(0.2,0,0,1)` over ~500ms (long2). **Keep the existing `prefers-reduced-motion` short-circuit** (collapse springs to instant/short cross-fade).
+
+### 3.5 State layers, density, spacing
+- **State layers** (translucent overlay of the *content* color, not a new bg): hover **8%**, focus **10–12%**, pressed **10%** (ripple origin), dragged **16%**. Disabled: content **38%** / container **12%**. (MUI defaults differ — must be retuned.)
+- **Density / touch targets:** minimum **48×48 dp** (current uses 44 — bump up). M3E ships size ramps XS–XL for buttons/split-buttons/FAB.
+- **Spacing:** keep the **8px (4/8) grid** — already M3-compatible (the one genuine win). Containers grow to **16–24px** internal padding for M3E rhythm.
+
+---
+
+## 4. Component transformation table
+
+Distance: **Near** (token swap) · **Medium** (restyle) · **Far** (rebuild/conceptual gap).
+
+| Current component | M3E target | Shape | Color role | State layer | Motion | Padding / Resp. | Dist. |
+|---|---|---|---|---|---|---|---|
+| `AppButton` | 5 M3 variants (filled/tonal/elevated/outlined/text), XS–XL sizes | `full` pill, **morph on press** | real `secondary-container`/`on-` (kill alpha hack) | hover8/focus10/press10 | spatial-fast press bump; keep loading/success machine | 48dp min, M3 size specs | Far |
+| `IconAction` | M3 icon-button (filled/tonal/outlined/standard), width variants, toggle | morph on select | container pairs | full layers + selected | spatial-fast | 48dp | Far |
+| `app/Fab` | FAB sizes (40/56/96) + **FAB menu**, branded/extended | large/xl | surface(default)/primary/tertiary, rests `surface-container-high` | layers | container-transform bloom | — | Far |
+| `TextField` family | M3 outlined/filled field (active indicator, supporting text, icon slots) | small→M3 | error/focus tokens | container state layers | — | keep 16px font | Medium-near |
+| `QtyStepper` | connected **Button group** styling | connected, morph | container | layers | spatial press | 48dp | Far (styling) |
+| `SearchBar` | M3 search bar + expand-to-fullscreen search view | `full` pill, no border | `surface-container-high` fill | layers | expand transition | — | Far |
+| `StatusToggle` | M3 **segmented button** (pill, secondary-container selected + check) | pill | `secondary-container` selected | layers + selection anim | shape-shift on select | — | Far |
+| `StatusChip` | M3 chips (assist/filter/input/suggestion), check morph | `small`(8) not pill | named container tokens (kill `${hex}1A`) | layers | select morph | — | Medium-far |
+| `MetricCard` / domain cards | **tonal "container" cards** (pastel surface/secondary/tertiary, ~28px, tonal elevation, ≤1px outline) | `large`→`xl` 28 | container roles | press layer | entrance spring | 16–24px, responsive grid | **Far (biggest screenshot gap)** |
+| `PagedList` | spring list-item motion / shared-element | n/a | n/a | item layer | spring stagger | mobile→grid | Medium |
+| `BottomSheet` | M3 sheet | **28** top corners | `surface-container-low` | layers | **drag-dismiss spring** | — | Medium |
+| `Modal`/`ConfirmDialog` | M3 dialog (hero icon slot) | **28** | `surface-container-high` | layers | emphasized open/close | — | Medium-far |
+| `StickyHeader` | M3 top app bar (small/med/large), tonal-on-scroll | — | `surface-container` on scroll | — | emphasized collapse | med/large headline variants | Medium-far |
+| `BottomNav` | M3 navigation bar (**active-indicator pill + morph**) | pill indicator | `secondary-container` | indicator state layer | indicator morph | 80dp; rail at ≥900 (later) | Far |
+| `StickyActionBar` | M3 **docked/floating Toolbar** (grouped actions + optional FAB) | pill (floating) | container | layers | — | — | Far |
+| `PageTabs` | M3 primary/secondary tabs | M3 indicator | container | layers | indicator anim | — | Medium-near |
+| `Spinner` | **waveform/wavy progress** + M3 loading indicator | rounded ends | `primary` | n/a | wavy→straighten | — | Far |
+
+### New expressive components to build (no equivalent today)
+1. **Split button** — `buttons/SplitButton`: leading primary action + trailing menu trigger that **spins + reshapes** on open. 5 sizes; filled/tonal/elevated/outlined.
+2. **Button group** — `buttons/ButtonGroup`: connected buttons with shared shape/motion/width; pressing one squeezes neighbors. XS–XL.
+3. **Toolbar (docked + floating)** — replaces/augments `StickyActionBar`: docked replaces deprecated bottom app bar; floating = pill action cluster that can host a FAB.
+4. **FAB menu** — augments `app/Fab`: FAB morphs into a menu container of labelled actions (replaces speed-dial).
+5. **Expressive Card** — tonal container card variants (surface/secondary/tertiary), 16–28px, tonal elevation, press shape-morph.
+6. **Waveform progress** — `feedback/WaveProgress`: linear + circular wavy active track that straightens as it completes (the M3E signature) + new contained loading indicator.
+7. **M3 Segmented button** — rebuild `StatusToggle`: pill, `secondary-container` selected segment, check affordance, selection animation.
+
+---
+
+## 5. Responsiveness, margin/padding & animation guidelines (owner asked explicitly)
+
+### Responsiveness
+- **Today: hard mobile-only.** `BottomNav` defers the `≥900px` rail to "a later phase" (a TODO comment); cards never grid; the app bar has no medium/large variants; breakpoints are essentially unused.
+- **Baseline re-skin keeps single-column mobile** but makes cards grid-capable (2-up at `sm`, 3-up at `md`) and sizes containers fluidly.
+- **Follow-on (separate phase, owner decision):** adopt M3 **window-size classes** (compact / medium / expanded) driving nav-bar → nav-rail → nav-drawer, and multi-pane layouts for tablet/desktop. Out of scope for the core skin to keep risk low.
+
+### Margin / padding
+- **Keep the 8px (4/8) grid** — it is the least-broken axis and M3-compatible.
+- **Grow container rhythm:** cards/sheets to **16–24px** internal padding (M3E is more generous than the current uniform `p:2`/16px).
+- Touch targets **48×48dp minimum** (up from 44). Preserve the existing **safe-area inset** CSS-var handling (good PWA hygiene).
+
+### Animation
+- **Spring-first.** Spatial springs (bouncy, `damping .6–.8`) for position/size/**corner-radius** changes; effects springs (`damping ~1`, no overshoot) for color/opacity/elevation. Reserve bounce for spatial only.
+- **Shape-shift is a first-class interaction:** press bump (scale down + corners morph rounder→squarer, release with overshoot), selection shape-change, container morph (FAB→menu, button→loading).
+- **Use `prefers-reduced-motion`** to collapse all springs to instant/short cross-fade — keep this discipline (it already exists).
+- Page transitions move from cubic-bezier to **emphasized / shared-axis / container-transform**.
+
+---
+
+## 6. Phased build plan (with effort + reliability guardrails)
+
+> **Guardrails for every phase:** data/TanStack-Query layer untouched; `theme.custom.*` and `palette.accent` token *names* kept alive (mapped to M3 roles) so the **39 consuming files / 72 sites** don't need edits; run a regression build + visual smoke test at each phase; each phase independently shippable and revertible.
+
+| Phase | Scope | Effort | Reliability guardrail |
+|---|---|---|---|
+| **0. Seed decision + token generator** | Pick brand seed; add `@material/material-color-utilities`; emit M3 role tokens (incl. surface ladder) as typed object + CSS vars at build time | ~2–3 d | Build-time only, zero runtime; no component touched yet |
+| **1. Theme tokens** | Re-model `palette.ts` (tonal roles), `index.ts` (shape scale, tonal elevation, state-layer mixin), `motion.ts` (6 springs); extend `theme.d.ts`; map old custom tokens → M3 roles | ~3–4 d | Centralized; alias old token names; regression build; biggest visual win, lowest risk |
+| **2. Primitives restyle (Near/Medium)** | TextField family, PageTabs, StatusChip, BottomSheet, Modal/ConfirmDialog onto new tokens | ~3–4 d | Token swaps + corner/elevation nudges; per-component revertible |
+| **3. Far rebuilds** | AppButton, IconAction, Fab, cards (tonal containers), BottomNav (active-indicator), SearchBar, StatusToggle, StickyHeader | ~5–7 d | Rebuild on MUI primitives + springs; presentational only |
+| **4. New expressive components** | Split button, Button group, Toolbar, FAB menu, waveform progress, segmented button | ~5–7 d | Net-new, presentational, no data touch |
+| **5. Per-screen restyle** | Apply expressive components + tonal cards across role pages (auth/route/customers/catalog/billing/payments/analytics/admin) | ~3–5 d | Page-by-page; visual review per screen |
+| **6. (Optional / later)** | Dark theme; window-size-class adaptivity (rail/drawer); MUI v6→v7 codemod | TBD | Separate decision; not required for the skin |
+
+**Total core (phases 0–5): ~3–4 weeks.** Low-medium risk throughout (same framework, same render model, backend decoupled).
+
+---
+
+## 7. Locked decisions (owner-approved)
+
+1. **Expressiveness:** **FULL EXPRESSIVE EVERYWHERE** — bouncy spatial springs, shape-morph on press/select, large 28px shapes, hero display type across screens (Expressive spring scheme is the default; Standard reserved only where motion would impede dense data entry).
+2. **Light + DARK from the start** — generate both tonal sets from the seed.
+3. **Typeface: Roboto Flex** (M3 default; variable axes enable the "emphasized" hero weights). Self-host the variable font (subset) to avoid a network round-trip.
+4. **All expressive components are must-have for v1:** tonal pastel cards, waveform/wavy progress, M3 segmented buttons, nav-bar active-indicator (morphing pill), split button, button group, FAB menu, docked/floating toolbar.
+5. **PERFORMANCE MANDATE — "must not feel laggy" (hard requirement):**
+   - Animate ONLY `transform` + `opacity` (GPU compositor); never animate layout/`width`/`top`/box-shadow on interaction. Tonal "elevation" via pre-baked surface colors, not animated shadows.
+   - Color tokens generated at BUILD time (`@material/material-color-utilities`) → zero runtime palette cost; emitted as CSS vars so theme/dark switch is a class flip, not a re-render.
+   - Springs via Framer Motion with `will-change`/`transform` only; cap concurrent animations; **code-split** the heavy expressive components; keep the eager bundle small (fixes audit M19 cold-start too).
+   - Honor `prefers-reduced-motion` (collapse springs to instant) and throttle list-stagger on long lists (virtualize/animate only on-screen items).
+   - Target 60fps on a mid-range Android; verify with a perf pass.
+6. **Brand seed color:** PENDING — the one input everything generates from (see follow-up question).
+7. **Adaptive/tablet (window-size-class rail/drawer):** deferred to a later phase (keep core re-skin low-risk).
+
+---
+
+**Recommendation (one line):** Approve **Approach A** — re-theme MUI v6 to a seed-generated M3 tonal token system and hand-build ~7 expressive components on MUI + Framer springs, sequenced tokens → primitives → expressive components → per-screen, with the data layer untouched.

frontend/PWA/design/m3/current-components.md

@@ -0,0 +1,304 @@
+# U3 — Current Components Audit vs Material 3 Expressive
+
+Scope: `src/components/**` + `src/app/**` (AppShell). Goal: measure each component's distance from its
+M3 Expressive equivalent across **shape, state layer, tonal color, motion, padding/margins, responsiveness**,
+and enumerate the M3 Expressive components we **lack entirely**.
+
+---
+
+## 0. The honest top-line (the theme "is not worth it" — agreed)
+
+The current system is a **competent generic SaaS theme**, not Material 3, and definitely not M3 *Expressive*.
+It was clearly hand-authored against an internal `DESIGN_SYSTEM` doc that predates M3 Expressive. The gap is
+not cosmetic — it is **structural**, and a "re-skin" cannot be a palette swap. Concretely:
+
+1. **No tonal-palette system.** `palette.ts` is a flat set of 6 brand hexes + a hardcoded status map.
+   There is **no surface-container ramp** (surface / surface-container-low/-/-high/-highest), no
+   secondary-/tertiary-container, no `on-*` roles. M3 Expressive's entire pastel-container look (the
+   screenshot's soft tonal cards) is impossible to express with this palette. Alpha hacks like
+   `${primary.main}14` (8% overlay) are used to *fake* tonal fills — that is the tell.
+2. **No state-layer model.** M3 requires hover/focus/pressed/dragged state layers (8%/10%/10%/16% of the
+   role color) on every interactive surface. The app relies on MUI's default ripple + ad-hoc `&:hover`
+   `bgcolor` bumps. There is no consistent focus state layer, no pressed state layer beyond Framer
+   `scale: 0.97` on AppButton.
+3. **Shapes are too conservative & static.** Radii are `sm 8 / md 12 / lg 16 / pill 999`. M3 Expressive
+   uses a *larger* and *more varied* shape scale (extra-large 28, full pills as defaults for buttons,
+   shape **morph** on interaction — the springy shape-shift). Nothing here morphs shape on press/select.
+4. **Motion is easing-curve / fade-and-rise, not spring-physics.** `motion.ts` is all cubic-bezier
+   durations + one spring reserved for the bottom sheet. M3 Expressive's signature is **spatial spring
+   motion** (the "expressive" springs) applied broadly — shape morph, container transform, emphasized
+   easing. The app's motion vocabulary is fade+12px-rise list stagger and a scale-tap. That reads as
+   "tasteful 2021 web app," not Expressive.
+5. **Elevation = soft drop shadows.** M3 leans on **tonal elevation (surface containers)** with restrained
+   shadow. The current `e1/e2/e3` shadow ramp + 1px borders on every card is the opposite approach.
+6. **Color-as-status via alpha.** `StatusChip`/`StatusToggle` build soft backgrounds via `${hex}1A`
+   alpha. M3 wants *named container/on-container token pairs*, not runtime alpha math, which also risks
+   contrast failures on a dark theme that does not yet exist.
+
+So: re-skin = **introduce M3 tokens (tonal palettes, surface containers, state layers, shape scale, spring
+motion) and rebuild the component layer on top.** Below is the per-component gap list.
+
+---
+
+## 1. Buttons & actions
+
+### `buttons/AppButton.tsx`
+- **Shape:** `radius.md` (12px) rounded rect. M3 Expressive buttons default to **full/pill** shape and
+  ship in **5 sizes** (xs–xl) with a **shape-morph on press** (round ⇄ squarish). We have 3 sizes via a
+  height map and a fixed corner. **Far.**
+- **State layer:** none of the M3 layers. Pressed = Framer `scale 0.97`; hover = a manual `bgcolor` bump
+  only for the tonal `secondary` variant. No focus-visible state layer. **Far.**
+- **Tonal color:** `secondary` variant fakes a tonal button with `${primary.main}14/24` alpha instead of a
+  real `secondary-container`/`on-secondary-container` pair. **Conceptually wrong, not just off.**
+- **Motion:** the idle→loading→success(check morph)→error(shake) machine is genuinely nice and *more*
+  animated than stock MUI — but it is bespoke, not the M3 emphasized/spring vocabulary, and there is no
+  shape morph. **Medium.**
+- **Padding/margins:** `px 2/3`, `minHeight 40/48/52`. Reasonable, but not aligned to M3 size specs.
+- **Variants gap:** has primary/secondary/ghost/danger/whatsapp. **Missing M3 button variants:**
+  elevated, filled-tonal (real one), outlined are conflated/absent. No **Split button**, no **Button group**
+  (see §7).
+
+### `buttons/IconAction.tsx`
+- 44px tap target, `color="inherit"`, default MUI ripple. **No M3 icon-button shape variants**
+  (M3 has filled / tonal / outlined / standard icon buttons, **width variants** narrow→wide, and selected
+  toggle state with shape morph). No selected/toggle state layer. **Far.**
+
+### `app/Fab.tsx`
+- Single circular/extended FAB, amber, 56px, `e2` shadow, `radius.lg`/pill. M3 Expressive ships
+  **FAB sizes** (small/regular/large/**extended**) with **container-transform** and, critically, the new
+  **FAB Menu** (FAB that springs open into a speed-dial of labelled actions). We have **no FAB menu** and
+  no container-transform open animation. Color is a raw `accent.main` rather than a `primary-container`/
+  tertiary token. **Far + missing the headline Expressive component.**
+
+---
+
+## 2. Fields / inputs
+
+### `fields/TextField.tsx` (+ NumberField, PhoneField, SelectField, DateField, SwitchField, KeyboardAwareField)
+- Wraps MUI outlined `TextField`, `radius.md` (12px), 16px font (good — blocks iOS zoom), RHF-bound.
+- **vs M3:** M3 text fields are **filled or outlined with the specific M3 token treatment** (active
+  indicator, supporting text, leading/trailing icon slots, state layers on the container). MUI outlined is
+  *visually adjacent* to M3 outlined, so this is the **closest-to-M3 family** — but still lacks M3 state
+  layers, the M3 error/focus token colors, and M3's larger label/shape rhythm. **Medium-near.**
+- No expressive flourish (M3 fields are mostly restrained, so acceptable), but corners should grow to M3 scale.
+
+### `fields/QtyStepper.tsx`
+- Bespoke −/value/+ with 44px targets inside a 12px bordered box. Solid UX, unit-aware. **Not an M3
+  pattern at all** (M3 has no stepper; closest is a connected **Button group** / segmented). Acceptable as
+  a domain control, but should adopt M3 connected-button shape + state layers + press shape-morph. **Far in
+  styling, fine in function.**
+
+### `fields/SearchBar.tsx`
+- `Paper` + `InputBase`, 12px radius, 44px tall, border, clear-✕. M3 has a dedicated **Search bar / Search
+  view** pattern: **full/pill** shape, surface-container-high fill (no border), leading menu/search icon,
+  trailing avatar/action, and an **expand-to-full-screen search view** transition. Ours is a flat bordered
+  box with none of that. **Far.**
+
+### `fields/StatusToggle.tsx`
+- MUI `ToggleButtonGroup`, `radius.sm` (8px) segments, neutral grey via sx alpha. This is the app's
+  **segmented control**. M3's **segmented button** is pill-shaped, full-width-optional, uses
+  secondary-container for the selected segment + a check icon, with **state layers and selection
+  animation**. Ours: square-ish 8px corners, alpha tints, no selection motion, no check affordance.
+  **Medium-far — wrong shape & color model.**
+
+---
+
+## 3. Status / chips
+
+### `status/StatusChip.tsx`
+- MUI `Chip`, pill radius, **soft bg via `${hex}1A` alpha + colored text + dot/icon**. This is the single
+  source of status→color. M3 chips (assist/filter/input/suggestion) use **named container tokens**, an 8px
+  corner (M3 chips are *not* fully pill by default — they're small radius), state layers, and a selected
+  state with check morph. Ours is pill + alpha. **Color model is non-M3 (alpha math), shape is over-rounded
+  for an M3 chip.** Also: no filter/input/suggestion chip variants exist anywhere. **Medium-far.**
+- `StickyTotalBar` also uses a raw MUI `Chip color="primary"` (solid) — inconsistent with StatusChip.
+
+---
+
+## 4. Cards & containers
+
+### `charts/MetricCard.tsx`, `domain/CustomerCard.tsx`, `domain/ProductCard.tsx`, `domain/BillCard.tsx`, rows
+- All built on MUI `Card` themed to `radius.lg` (16px) + **1px border + e1 shadow + white paper**.
+- **vs M3 Expressive:** the headline Expressive look is **tonal "container" cards** — pastel
+  surface-container / secondary-container / tertiary-container fills, **large 28px corners**, *little or no
+  border*, tonal elevation instead of drop shadow, and sometimes **asymmetric / varied corner shapes** and
+  shape-morph on press. Our cards are flat white bordered rectangles. This is the **biggest visual gap to
+  the screenshot** the owner referenced. **Far.**
+- **Padding:** uniform `p: 2` (16px) everywhere — fine, but M3 expressive cards tend to 16–24px with more
+  generous internal rhythm.
+- **Motion:** cards have no press/hover state layer and no entrance spring of their own (entrance comes only
+  from `PagedList` fade+rise). **Far.**
+- **Responsiveness:** cards are full-width stacked; no responsive grid / breakpoint behavior at tablet
+  widths. Mobile-only assumption baked in.
+
+### `domain/CustomerCard` rank badge / Avatar
+- Avatar uses `background.default` fill + primary icon — should map to a `*-container` token in M3. Minor.
+
+---
+
+## 5. Lists
+
+### `lists/PagedList.tsx`
+- Solid functional list (infinite/load-more, pull-to-refresh, skeleton/empty/error states). Spacing
+  `1.5` gap. Entrance = fade + 12px rise staggered by `stagger.step` (40ms). **Honest motion critique:**
+  fade+rise is the *generic* entrance; M3 Expressive favors **spring-based list item motion** and
+  container/shared-element transforms. No shape, no spring. **Medium** (function strong, motion generic).
+- `usePullToRefresh` indicator is a custom spinner — M3 has a refreshable indicator but this is acceptable.
+- No M3 **list item** spec adoption (leading/trailing slots, dividers, state layers) — list items are just
+  domain cards. Acceptable but non-M3.
+
+---
+
+## 6. Overlays
+
+### `overlays/BottomSheet.tsx`
+- MUI `Drawer` bottom anchor, 16px top corners, `e3` shadow, grab handle, keyboard-aware footer lift,
+  reduced-motion fade. **Deliberately uses Drawer's Slide, not a spring.** M3 Expressive bottom sheet =
+  **28px top corners**, surface-container-low tonal fill, drag-to-dismiss with **spring physics**, and the
+  expressive container motion. Ours slides linearly with 16px corners. **Medium** — right idea, under-rounded
+  and non-spring.
+
+### `overlays/Modal.tsx`
+- MUI `Dialog`, 16px radius, `e3`, close-✕ top-right. M3 dialogs: **28px corners**, tonal
+  surface-container-high, hero icon slot, emphasized open/close motion. **Medium-far** (corner + tonal + motion).
+
+### `overlays/ConfirmDialog.tsx`
+- (Wraps the dialog pattern.) Same gaps as Modal. Should adopt M3 basic-dialog layout + tonal + spring.
+
+---
+
+## 7. AppShell (`src/app/**`)
+
+### `app/StickyHeader.tsx`
+- MUI `AppBar`+`Toolbar`, 56px, white bg, **1px bottom border**, shadow only when `elevated`, optional 48px
+  sub-row. **vs M3:** M3 top app bars (small/medium/large/center) use **surface-container tonal color on
+  scroll**, larger expressive title sizes (medium/large variants with big headlines), and emphasized
+  collapse motion. Ours is a flat 56px bar with a border — closest to M3 *small* app bar but no tonal-scroll,
+  no medium/large expressive headline variants. **Medium-far.**
+
+### `app/BottomNav.tsx`
+- MUI `BottomNavigation`, 60px, top border, active=primary/inactive=secondary, **showLabels always**.
+  **vs M3:** M3 **Navigation bar** uses an **active indicator pill (state layer) behind the active icon**
+  with a **morphing/animated indicator** on switch, secondary-container token, and a specific 80px height.
+  Ours has **no active indicator pill and no switch animation** — just color change. **Far** (missing the
+  signature M3 nav-bar indicator + motion). Also note: `>=900px left rail` is only a TODO comment — **no
+  responsive nav rail exists**, so tablet/desktop is unhandled.
+
+### `app/StickyActionBar.tsx`
+- `Paper` + `e3` top shadow, keyboard lift, primary/secondary stacked, safe-area padding. Functionally a
+  bottom button container. M3 Expressive's equivalent is the **Bottom app bar / Toolbar** (incl. the new
+  **floating/docked Toolbar** with grouped actions + FAB). Ours is a shadowed slab with stacked buttons, not
+  an M3 toolbar. **Far** (and see §8 Toolbar gap).
+
+### `nav/PageTabs.tsx`
+- MUI `Tabs` fullWidth. M3 primary/secondary **Tabs** with active indicator are close to MUI's, but lack the
+  M3 indicator shape/animation and label/icon tab spec. **Medium-near.**
+
+### `nav/DateStrip.tsx`, `nav/StickyTotalBar.tsx`
+- Bespoke; `StickyTotalBar` uses a solid primary chip (inconsistent w/ StatusChip) + count-up. Fine
+  functionally; non-M3 styling.
+
+### `app/PageTransition.tsx`
+- Page transitions exist (good) but driven by the cubic-bezier `page` easing, not M3 emphasized/spring or
+  **shared-axis / container-transform** patterns. **Medium.**
+
+---
+
+## 8. Feedback / progress
+
+### `feedback/Spinner.tsx`
+- MUI `CircularProgress`, thickness 4.5. M3 Expressive **redesigned progress indicators**: the new
+  circular/linear indicators have a **gap + rounded ends**, and there is the brand-new **wavy / waveform
+  linear & circular progress**. We have a plain MUI spinner. **No waveform progress anywhere.** **Far.**
+
+### `feedback/Skeleton.tsx`, `EmptyState`, `ErrorState`, `ErrorBoundary`, `ToastProvider`
+- Standard. M3 has **Loading indicator** (the new contained activity indicator) and **Snackbar** spec;
+  ours are generic MUI/bespoke. Toasts are bespoke (not M3 snackbar tokens). **Medium**, low priority.
+
+---
+
+## 9. Charts (`charts/*`)
+- ApexCharts wrappers (Trend/Donut/Bar) + `ChartFrame` + `MetricCard`. Colors pulled from the flat palette,
+  not a tonal chart palette. M3 doesn't spec charts, but Expressive dashboards expect tonal-container chart
+  cards and harmonized accent tones. Charts will look off-brand until the palette becomes tonal. **N/A-to-medium.**
+
+---
+
+## 10. M3 Expressive components we LACK ENTIRELY
+
+These have **no equivalent** in `src/components` or `src/app` today:
+
+| M3 Expressive component | Status | Where it would land |
+| --- | --- | --- |
+| **Split button** (primary + attached menu trigger, shape-morph) | **Missing** | new `buttons/SplitButton` |
+| **Button group** (connected, shape-morph on press/selection) | **Missing** | new `buttons/ButtonGroup` |
+| **Toolbar** (floating/docked, grouped actions + optional FAB) | **Missing** | replaces/augments `StickyActionBar` |
+| **FAB Menu** (FAB springs open to labelled actions) | **Missing** | augments `app/Fab` |
+| **M3 Segmented button** (pill, secondary-container, check + selection anim) | **Have wrong impl** (`StatusToggle` = square ToggleButtonGroup) | rebuild `StatusToggle` |
+| **Navigation bar active-indicator pill + morph** | **Missing** (BottomNav = color-only) | rebuild `app/BottomNav` |
+| **Waveform / wavy progress** (linear + circular) | **Missing** (plain `CircularProgress`) | new `feedback/WaveProgress` |
+| **New M3 Loading indicator** (contained activity) | **Missing** | `feedback/Spinner` replacement |
+| **Tonal "container" expressive cards** (pastel surface/secondary/tertiary containers, 28px, tonal elevation) | **Missing** (all cards = white + border + shadow) | rebuild card layer |
+| **Surface-container ramp + state layers** (foundation) | **Missing** (flat palette + alpha hacks) | rebuild `theme/palette` |
+| **Shape-morph motion / spring physics** (the Expressive signature) | **Missing** (cubic-bezier + one sheet spring) | rebuild `theme/motion` |
+| **Icon button variants** (filled/tonal/outlined, width sizes, toggle morph) | **Missing** (single `IconAction`) | extend `IconAction` |
+| **M3 Search view** (expand-to-fullscreen) | **Missing** (flat SearchBar only) | extend `SearchBar` |
+| **Carousel** (M3 Expressive multi-item) | **Missing** | net-new if needed |
+
+---
+
+## 11. Per-component distance scorecard (quick reference)
+
+Distance: **Near** (token swap), **Medium** (restyle), **Far** (rebuild/conceptual gap).
+
+| Component | Shape | State layer | Tonal color | Motion | Padding/Resp. | Overall |
+| --- | --- | --- | --- | --- | --- | --- |
+| AppButton | Far | Far | Far (alpha) | Medium | Near | **Far** |
+| IconAction | Far | Far | Far | Far | Near | **Far** |
+| Fab | Medium | Far | Far | Far | Near | **Far** (no FAB menu) |
+| TextField family | Near | Medium | Medium | Near | Near | **Medium-near** |
+| QtyStepper | Far | Far | Medium | Far | Near | **Far (styling)** |
+| SearchBar | Far | Far | Far | Far | Near | **Far** |
+| StatusToggle (segmented) | Far | Far | Far (alpha) | Far | Medium | **Far** |
+| StatusChip | Medium | Far | Far (alpha) | Far | Near | **Medium-far** |
+| MetricCard / domain cards | Far | Far | Far | Far | Medium | **Far** (screenshot gap) |
+| PagedList | n/a | Far | n/a | Medium | Medium (mobile-only) | **Medium** |
+| BottomSheet | Medium | Far | Medium | Medium | Near | **Medium** |
+| Modal / ConfirmDialog | Medium | Far | Medium | Medium | Near | **Medium-far** |
+| StickyHeader (app bar) | Medium | Far | Far | Medium | Medium-far (no L/M variants) | **Medium-far** |
+| BottomNav | Far (no indicator) | Far | Far | Far | Far (no rail) | **Far** |
+| StickyActionBar | Far (not a Toolbar) | Far | Far | Medium | Medium | **Far** |
+| PageTabs | Medium | Medium | Medium | Medium | Near | **Medium-near** |
+| Spinner / progress | Far | n/a | n/a | Far (no waveform) | Near | **Far** |
+
+---
+
+## 12. Responsiveness, margin, padding & animation — overall notes
+
+- **Responsiveness:** the app is **hard mobile-only**. `BottomNav` literally defers the `>=900px` left rail
+  to "a later phase" (comment), cards never grid, app bar has no medium/large variants, no breakpoint-aware
+  layout. M3 Expressive is adaptive (nav rail/drawer, expanded panes) — this is a real gap for tablet/desktop.
+- **Padding/margins:** consistent and sane (`spacing: 8`, mostly `p: 2`). This is the **least broken axis** —
+  it just needs to grow to M3's more generous rhythm on containers. **Near.**
+- **Animation quality:** there is *real* care here (AppButton state machine, list stagger, sheet lift,
+  reduced-motion handling, page transitions) — better than stock MUI. But it is the **wrong dialect**:
+  duration+cubic-bezier fades/rises/scales, with exactly **one** spring (the sheet). M3 Expressive's identity
+  is **broad spring physics + shape morph + container transforms**. None of that exists. So: good engineering,
+  wrong design language. **Medium effort to re-aim, but conceptually Far.**
+
+---
+
+## 13. Bottom line for the re-skin
+
+A Material 3 Expressive re-skin of this codebase is a **foundation rebuild, then a component restyle**, in
+this order:
+
+1. **`theme/palette.ts` → M3 tonal system** (primary/secondary/tertiary palettes, surface-container ramp,
+   `on-*` roles, container pairs, error). Kill the `${hex}1A` alpha pattern.
+2. **`theme/motion.ts` → spring/emphasized tokens** (expressive springs, shape-morph helpers,
+   container-transform). Keep the reduced-motion discipline.
+3. **`theme/index.ts` → M3 shape scale** (xs–xl incl. 28px, pill defaults), **state-layer mixin**, tonal
+   elevation.
+4. Restyle the **Near/Medium** components (fields, tabs, sheet, dialog, chip) onto the new tokens.
+5. **Rebuild** the **Far** components and add the **missing** ones: Split button, Button group, Toolbar,
+   FAB menu, M3 segmented button, nav-bar active indicator, waveform progress, tonal expressive cards.

frontend/PWA/design/m3/current-theme.md

@@ -0,0 +1,155 @@
+# Current Theme Audit vs Material 3 Expressive
+
+**Scope:** `src/theme/{palette.ts, motion.ts, index.ts, theme.d.ts}` and how those tokens are consumed in `src/components/`.
+
+**Verdict up front:** The current theme is a competent, conventional *MUI v5/Material-2-era* setup with a hand-rolled "design system" bolted on via `theme.custom`. It is internally consistent and the discipline (no inline hex, tokens read from theme) is genuinely good. But as a foundation for **Material 3 Expressive** it is the wrong shape entirely. M3 is not "MUI with rounder corners and a blue primary" — it is a *tonal* system built on HCT tonal palettes, surface-container tiers, paired color roles (`on-*`, `*-container`, `on-*-container`), an expanded type scale, a tonal elevation model, state layers, and spring-based motion. The current theme has **none of those primitives**. Re-skinning is not a tweak; it is a token-model replacement. Everything below is why "it isn't worth it" to keep as-is.
+
+---
+
+## 1. Color / Palette — the biggest gap
+
+### What we have
+`palette.ts` defines **flat, single-stop solid colors**:
+
+```
+primary  #1E6FE0   secondary #2E9E5B   success #16A34A
+warning  #D97706    error    #DC2626    info    #0EA5E9
+background.default #F6F8FB   paper #FFFFFF   divider #E5E9F0
+text.primary #0F172A  secondary #64748B  disabled #94A3B8
++ custom: accent #F59E0B, eveningTint #4F46E5, status map
+```
+
+Each role is **one hex with a `contrastText`**. That's the entire color model. `AppButton` even hand-mixes a tonal fill by string-concatenating opacity onto the hex (`` `${t.palette.primary.main}14` ``, `...24` on hover) — i.e. the codebase is already *faking* tonal containers because the token system can't express them.
+
+### What M3 Expressive requires
+M3 derives color from **HCT tonal palettes** (tones 0–100) per key color, then maps them to a **role set**, light + dark, that MUI's flat palette cannot represent:
+
+| Role family | M3 roles (each needs a value) | We have |
+| --- | --- | --- |
+| Primary | `primary`, `on-primary`, `primary-container`, `on-primary-container` | only `primary.main` + `contrastText` |
+| Secondary | `secondary`, `on-secondary`, `secondary-container`, `on-secondary-container` | only `secondary.main` |
+| **Tertiary** | `tertiary`, `on-tertiary`, `tertiary-container`, `on-tertiary-container` | **missing entirely** — no tertiary role exists |
+| Error | `error`, `on-error`, `error-container`, `on-error-container` | only `error.main` |
+| Surfaces | `surface`, `surface-dim`, `surface-bright`, and **5 container tiers**: `surface-container-lowest / low / (base) / high / highest` | only `background.default` + `background.paper` (2 flat surfaces) |
+| On-surface | `on-surface`, `on-surface-variant`, `outline`, `outline-variant` | `text.primary/secondary` + one flat `divider` |
+| Fixed / inverse | `*-fixed`, `*-fixed-dim`, `on-*-fixed`, `inverse-surface`, `inverse-on-surface`, `inverse-primary`, `scrim`, `shadow` | none |
+
+**Concrete missing primitives:**
+- **No tonal ramp.** There is no tones-0..100 source. You cannot generate `primary-container` (~tone 90 light / tone 30 dark) or hover/press state-layer tones from a single `#1E6FE0`. The opacity hacks (`+14`, `+24`) are not the same thing and break in dark mode.
+- **No surface-container tiers.** M3 Expressive leans *heavily* on tonal surface containers to separate cards/sheets/toolbars from the background without borders. We instead draw 1px `#E5E9F0` borders on every Card (`index.ts` MuiCard override) — a Material-2 / Bootstrap idiom that M3 explicitly moves away from.
+- **No `on-*` role pairing.** Contrast is ad-hoc per component (e.g. MetricCard hardcodes `text.secondary`, AppButton hardcodes `primary.main` on a primary tint). M3 guarantees legible pairs by construction.
+- **No tertiary.** Expressive UIs use tertiary for accents/highlights (badges, selected chips, hero numbers). We substitute a one-off `accent #F59E0B` and an `eveningTint #4F46E5` — bespoke tokens that are not part of any system and won't recolor with the theme.
+- **No dark theme.** `palette.mode` is hardcoded `'light'`; the file comment says "dark-swap ready" but there is no second tonal set, and the opacity-mix tonal fakes will invert wrong. "Ready" is aspirational, not real.
+- **Status colors are a separate flat map** (`customTokens.status`) reusing the same success/warning/error hexes — not tied to container roles, so status chips can't get the soft tonal-container look M3 uses.
+
+**Why it isn't worth keeping:** the color foundation is one layer deep where M3 needs four (tone → role → container → on-role). You cannot "skin" your way from flat roles to tonal roles; the generator (HCT → roles) must be added and `theme.palette` re-modeled. Keeping the current palette means re-faking tonality per component forever (as AppButton already does).
+
+---
+
+## 2. Shape / Radius — too small, too uniform, not expressive
+
+### What we have
+`index.ts`: `radius = { sm: 8, md: 12, lg: 16, pill: 999 }`, `shape.borderRadius: 12`. Cards 16, buttons/inputs 12, chips pill. Three values, applied conservatively.
+
+### M3 Expressive
+M3 defines a **shape scale** — `none, extra-small (4), small (8), medium (12), large (16), extra-large (28), full`, plus **larger expressive tiers** (extra-large-increased, extra-extra-large) and, new in Expressive, **non-circular / cookie / morphing shapes** and shape *as a state* (components shape-shift on press/select). Expressive deliberately uses **big radii** (e.g. 28+ on cards, sheets, FABs, dialogs) and varied shapes per component size.
+
+**Gaps:**
+- Top radius is **16px** — M3's *baseline* large is 16 and Expressive routinely goes to **28**. Our UI will read as "rounded Material 2," not expressive.
+- **No `extra-large` (28) token**, no `xxl`. Bottom sheet uses `lg` (16) for its top corners — M3 sheets want 28.
+- **Uniform shapes only.** No concept of shape *morphing* between states (M3 Expressive buttons/FABs change shape on press; selected chips/toggles change corner). Our shapes are static.
+- **Radius is a flat `number` per size**, not mapped to component roles, so there's no way to express "FAB = large", "dialog = extra-large", "chip = small" as M3 prescribes.
+- The pill token (`999`) is fine and survives, but it's the only "expressive" feel present.
+
+**Why it isn't worth keeping:** the radius set is too small and too uniform to look like M3 Expressive at all. It needs a full shape *scale* up to 28+ and, ideally, morph tokens — a structural addition, not a value bump.
+
+---
+
+## 3. Typography — Inter + a flat 12-role MUI scale, not the M3 type scale
+
+### What we have
+`index.ts` typography: family `Inter` fallback `Segoe UI/Roboto`. Roles are **MUI's legacy variants** (`h1..h6, subtitle1/2, body1/2, caption, overline, button`) with px sizes (h1 28, h2 24, h3 20, body1 16…), weights 400/500/600/700, `htmlFontSize/fontSize: 16`.
+
+### M3 type scale
+M3 uses a **15-role scale across 5 families × 3 sizes**: `display-{large,medium,small}`, `headline-{l,m,s}`, `title-{l,m,s}`, `body-{l,m,s}`, `label-{l,m,s}`, each with defined size/line-height/weight/tracking and a **Roboto / Roboto Flex** default. M3 Expressive adds **emphasized type styles** (heavier weights, tighter tracking, optical sizing via Roboto Flex variable font) and uses *display* sizes (up to 57px) for expressive hero moments.
+
+**Gaps:**
+- **Wrong role taxonomy.** MUI `h1..h6/subtitle/body/caption` ≠ M3 `display/headline/title/body/label`. There is no `display-*` at all — so no hero typographic moments, which Expressive is built around. The biggest text is `h1` at **28px**; M3 `display-large` is **57px**.
+- **No `label-*` family.** M3 labels (for buttons, chips, tabs) are a distinct family with specific tracking; here button text is a one-off `button` variant (15px) and chips/tabs borrow `caption`.
+- **No emphasized/variable-weight variants.** Expressive relies on weight contrast (e.g. emphasized 500→700 within the same role) and optical sizing (Roboto Flex). Inter is static-weight here; no variable-font axes wired up.
+- **Tracking/letter-spacing** is only set on `overline`. M3 specifies tracking per role; ours is mostly default.
+- **Font is Inter**, not Roboto/Roboto Flex. Acceptable to keep brand-wise, but it must then be re-mapped to the M3 role grid with M3 metrics — currently it follows MUI metrics, which differ.
+
+**Why it isn't worth keeping:** the type system is the wrong *shape* (12 MUI roles vs 15 M3 roles, no display, no label family, no emphasized axis). Components reference `variant="h2"`/`"caption"` everywhere (see MetricCard), so adopting the M3 scale means re-mapping every `Typography variant` call — the current scale gives no migration head start.
+
+---
+
+## 4. Spacing / Density / Breakpoints / Responsiveness
+
+### What we have
+- `spacing: 8` (8px base) — this *does* match M3's 4/8 grid, the one token that's already compatible.
+- Touch targets: AppButton `SIZE_HEIGHT` 52/48/40, MuiButton `minHeight: 44`, IconButton 44×44 in BottomSheet. Good for mobile a11y.
+- Padding conventions ad-hoc: cards `p: 2` (16px) in MetricCard, sheets `px: 2, py: 2`. No documented density token set.
+- **Breakpoints:** essentially unused. Grep found `breakpoints/useMediaQuery/sm:/md:` in only ~8 files, mostly type defs and a couple of pages (LoginPage, RoutePage). The app is **single-column mobile-only**; there's no responsive/adaptive layout strategy.
+- Safe-area insets handled via CSS vars in `MuiCssBaseline` (good PWA hygiene).
+
+### M3 expectations
+- M3 spacing is 4dp-grid based — **we're compatible here**, the main genuine win.
+- M3 defines **density levels** (0 to −4) for compact surfaces; we have none (just per-size button heights).
+- M3 / Material adaptive defines **window-size classes** (compact / medium / expanded / large / extra-large) driving navigation patterns (bottom bar → nav rail → nav drawer) and pane layouts. We have **zero** of this — mobile-only, no rail/drawer adaptation. For an ERP that owners may use on tablet/desktop, this is a real gap, though out of scope for a pure re-skin.
+
+**Why it's a gap:** spacing base is fine, but there's no density model and no adaptive/responsive layer. M3 Expressive's new components (Toolbars, nav rail variants, FAB menus) assume window-size-class awareness the app doesn't have.
+
+---
+
+## 5. Motion — fixed durations/easings, not expressive springs
+
+### What we have
+`motion.ts`:
+- Durations: `instant 0, fast 120, base 200, page 280, sheet 320, countup 700, success 600`.
+- Easings: three cubic-beziers (`fast` easeOut, `base`, `page`) as both CSS strings and Framer arrays.
+- **One** spring: `sheetSpring = { damping: 30, stiffness: 320 }`, and even that is **not used** — BottomSheet's own comment says it keeps MUI Drawer's built-in `Slide` (fixed 320ms tween) instead of the spring.
+- Usage is sparse: grep shows springs/`whileTap`/`whileHover` in only 3 files. AppButton uses `whileTap scale .97` + a shake (a tween, not a spring). Most "motion" is duration-tween fades.
+
+### M3 Expressive motion
+This is one of the headline features of Expressive. M3 motion is now **spring-based**, with two token families:
+- **Spatial** springs (position/size/shape changes) — *fast / default / slow*, each *spatial* (with bounce) — e.g. `expressive-spatial-default` ≈ damping 0.8 / stiffness ~380.
+- **Effects** springs (opacity/color, non-spatial, no bounce).
+- Plus the **emphasized / standard easing** legacy set for CSS where springs don't apply.
+Expressive deliberately adds **bounce/overshoot** and **shape-shift** transitions (buttons morph, FAB menus spring open, containers stretch). The new **waveform / wavy progress indicators** are an explicit Expressive motion component.
+
+**Gaps:**
+- **Spring-as-primary is missing.** We have one unused spring and otherwise fixed-duration tweens. M3 Expressive wants spring tokens to be the default for spatial motion. No spatial/effects spring token families exist.
+- **No bounce/overshoot vocabulary.** Our easings are all settle-to-rest (easeOut-ish); nothing overshoots. Expressive's signature "springy, lively" feel is absent by construction.
+- **No shape-shift / morph motion.** AppButton's success state swaps icons but doesn't morph shape; M3 buttons/FABs shape-shift on press. No tokens for it.
+- **Progress indicators not Expressive.** Default MUI spinner (`Spinner`) — no waveform/wavy linear progress, which is a flagship Expressive component.
+- **The one good spring is dead code** — the actual sheet uses a 320ms tween, so even the spring that exists isn't expressive in practice.
+- Durations themselves are reasonable and reduced-motion handling is genuinely good (every animation short-circuits) — that discipline should be **kept**, but the easing/spring layer must be replaced.
+
+**Why it isn't worth keeping:** the motion system is duration-tween-first with a single unused spring. M3 Expressive is spring-first with bounce and shape-morph. The current tokens give the *opposite* feel and offer almost nothing to build the expressive motion on.
+
+---
+
+## Cross-cutting: architecture observations
+
+**The good (keep / reuse the mechanism, not the values):**
+- Strong **token discipline**: components read from `theme.custom.*` / `theme.palette.*`; only **5 files** contain raw hex/rgba and most are the theme + 2 justified overlays (Modal/BottomSheet scrims, StatusToggle). This means a token-model swap can be **centralized** — a real asset.
+- `theme.d.ts` module augmentation is the correct extension point; the M3 roles can be added there.
+- 8px spacing grid and reduced-motion handling are M3-compatible.
+
+**The bad (structural, not cosmetic):**
+- `theme.custom` is a **parallel, non-standard design system** invented on top of MUI (`border`, `surface`, `eveningTint`, `status`, flat `radius`, `motion`). None of it maps to M3 role names, so M3 adoption means deprecating most of `custom` and re-augmenting with M3 roles/shape/motion scales.
+- Components already **fake M3 features the tokens can't express** (AppButton tonal-container via opacity strings, Cards via 1px borders instead of surface containers). Every such hack is rework.
+- **No dark mode, no tertiary, no surface tiers, no display/label type, no springs** — these aren't gaps you patch; they're the missing 60% of the M3 token model.
+
+---
+
+## Concrete gap checklist (for the re-skin plan)
+
+1. Replace flat palette with **HCT-derived tonal roles**: add `*-container`, `on-*`, `on-*-container` for primary/secondary/**tertiary**/error; add **5 surface-container tiers** + `surface-dim/bright`, `outline`/`outline-variant`, inverse/fixed/scrim. Add a real **dark** tonal set.
+2. Kill the opacity-string tonal hacks and the 1px-border card idiom; move to **tonal surface containers + state layers**.
+3. Expand **shape scale to 4/8/12/16/28+** (add `xl`/`xxl`), map radii to component roles, add **shape-morph** state tokens.
+4. Replace MUI legacy type variants with the **M3 15-role scale** (display/headline/title/body/label × 3), add **emphasized** weights; wire **Roboto Flex / variable** axes (or re-map Inter to M3 metrics).
+5. Keep the 8px grid; add **density** tokens and a **window-size-class** adaptive layer (bottom bar → rail → drawer) for tablet/desktop.
+6. Replace duration-tween motion with **spring token families** (spatial fast/default/slow with bounce, effects springs); add **shape-shift/morph** motion and **waveform progress**. Keep the reduced-motion discipline.
+7. Adopt new **Expressive components** absent today: Toolbars, Split buttons, Button groups, FAB menus, updated/wavy progress indicators.

frontend/PWA/design/m3/feasibility.md

@@ -0,0 +1,90 @@
+# M3 Expressive — Feasibility & Approach (U4)
+
+Scope: how to get **Material 3 Expressive** into THIS app. Analysis only. No code changed, no builds run.
+
+## TL;DR Recommendation
+
+**Approach A — Re-theme MUI v6 to M3 + build ~6 custom "expressive" components on MUI primitives + Framer Motion.**
+Do NOT adopt `@material/web` (Approach B). It is in **maintenance mode** ("pending new maintainers", last release v2.4.1 on 2025-10-27), it has **no Card, no Toolbar, no Split button, no Button group, no FAB menu, and no M3 Expressive components at all** — exactly the pieces the owner is asking for. Adopting it would be a high-risk rewrite that still can't deliver the screenshot. Stay on MUI, which the entire app (102 of 114 `.tsx` files) already depends on, and which the data/query layer is fully decoupled from.
+
+Optionally bump MUI v6 → v7 first (mechanical codemod, same API surface) so we're on the actively-maintained line, but it is not required for M3.
+
+---
+
+## What "M3 Expressive" actually requires (the bar to clear)
+
+From m3.material.io + material-web docs, the visual/behavioral targets are:
+
+1. **Tonal color system** — a seed color expanded into tonal palettes (primary/secondary/tertiary/neutral) producing the pastel **surface containers** (surface, surface-container-low/high/highest) and `on-*` roles. This is the single biggest visual gap today.
+2. **Large expressive shapes** — bigger corner radii, pill-shaped buttons, shape morph on state change.
+3. **Expressive typography** — the M3 type scale (display/headline/title/body/label) with larger, rounder display sizes.
+4. **State layers** — hover/focus/press are translucent `on-color` overlays at 8%/10%/10%, not box-shadows.
+5. **Springy shape-shift motion** — spring-based, not the cubic-bezier easings used now.
+6. **New expressive components** — Toolbars (docked/floating), Split buttons, Button groups (with connected/squish behavior), FAB menus, updated progress (incl. **waveform** linear progress).
+
+---
+
+## Brutally honest read of the CURRENT theme (owner: "not worth it" — agreed)
+
+Looked at `src/theme/{palette,index,motion}.ts`. It is a competent **flat SaaS** theme. It is **not** Material and is **architecturally hostile** to M3:
+
+- **`palette.ts` is hand-picked hex, explicitly `as const` and "LOCKED".** Comment literally says "never hardcode a hex (dark-swap ready)" — but there is **no tonal palette and no dark map**, just one light set. M3 needs ~13 tones per key color generated from a seed. None of that exists; it would be thrown away.
+- **No surface containers.** There is one `surface: '#FFFFFF'` and `background.default: '#F6F8FB'`. M3's whole "tonal/pastel container" look is *absent by construction*. `CustomerCard` etc. use `bgcolor: 'background.default'` and a `1px` border — the opposite of M3 tonal surfaces.
+- **Elevation is drop-shadows (`e1/e2/e3`), and only 3 distinct values smeared across all 25 slots.** M3 Expressive leans on **tonal elevation + state layers**, not soft shadows. The `Fab` hardcodes `boxShadow: t.shadows[2]`.
+- **Typography is a custom px scale**, not the M3 type scale. Fine, but nothing reusable for M3; the names (`h1..body2`) don't map cleanly to display/headline/title/label.
+- **Motion is cubic-bezier easings + one spring** (`sheetSpring`). M3 Expressive is spring-forward. The bones (Framer Motion already wired, `useReducedMotion` respected in `AppButton`) are good and reusable.
+- **Custom-token coupling is real but contained.** `theme.custom.*` / `palette.accent` is referenced in **39 files / 72 sites**. A re-theme must keep these token *names* alive (mapped to M3 roles) to avoid touching all 39 — very doable.
+
+Verdict: the *visual* theme is a near-total rewrite for M3. The *plumbing* (MUI `createTheme`, module augmentation in `theme.d.ts`, Framer Motion, reduced-motion hook, `AppButton`'s state machine) is good and worth keeping. So "re-theme," not "re-platform."
+
+---
+
+## Approach A — Re-theme MUI v6/v7 to M3 (+ custom expressive components)
+
+**How:**
+- Add `@material/material-color-utilities`. Generate tonal palettes from a seed at build time, emit M3 role tokens (primary, on-primary, surface-container-*, etc.) as a typed object + CSS variables. Feed them into MUI `palette` and a new `theme.custom.m3` namespace (extend existing `theme.d.ts`).
+- Override `shape` (radius scale), `typography` (M3 type scale), and `components.*` for Button/Card/Chip/TextField/Paper to render tonal surfaces + state layers (state layers via `::before` overlay in `styleOverrides`).
+- Build ~6 **custom** components MUI doesn't ship, on MUI primitives + Framer springs: **Split button**, **Button group** (connected), **Toolbar** (docked/floating), **expressive Card** variants, **FAB menu**, **waveform/expressive progress**. These are presentational; they don't touch data.
+- Map existing `theme.custom.*` and `palette.accent` to M3 roles so the 39 consuming files keep working unchanged.
+
+| Dimension | Assessment |
+|---|---|
+| **Effort** | Medium-high. ~1.5–3 wks: token generator + theme override (~40%), 6 custom components (~45%), audit of 39 token-consumers (~15%). |
+| **Risk** | **Low-medium.** Same framework, same render model, same React 18/Vite/SSR-free PWA. No interop. Incremental & revertible per component. |
+| **Bundle / free-tier** | **Negligible delta.** `material-color-utilities` is small and can run at build time (zero runtime cost). MUI already shipped. Custom components reuse existing deps. |
+| **Match to screenshot** | **High (best achievable).** Tonal surfaces, expressive shapes/type, state layers, springs, and the expressive components are all reachable — though *hand-built*, so fidelity = effort we invest, not free. |
+| **Migration cost from current code** | **Low-medium.** Centralized in theme; per-component visual nudges. 39 token files insulated via token aliasing. No data/query changes. |
+| **Reliability** | **High.** Backend/TanStack Query untouched; this is a skin. |
+
+---
+
+## Approach B — Adopt `@material/web` (Lit web components) in React
+
+| Dimension | Assessment |
+|---|---|
+| **Maintenance** | **Disqualifying.** README: *"MWC is in maintenance mode pending new maintainers."* Roadmap: *"There is no current work planned for new features or components."* Last release **v2.4.1, 2025-10-27**. Betting the app's UI on an abandoned lib is a reliability anti-pattern. |
+| **Coverage of what's asked** | **Fails the brief.** No **Card**, no **Toolbar**, no **Split button**, no **Button group / segmented button** (segmented is on the *unbuilt* roadmap), no **FAB menu**. **M3 Expressive is not mentioned anywhere** in the repo. We'd be reimplementing the requested components ourselves anyway — on top of an unmaintained base. |
+| **Interop friction** | High. Lit custom elements in React 18 need wrappers for props/events (React 18 doesn't set custom-element properties or bind non-DOM events cleanly; `@lit/react` or manual refs). Forms (`react-hook-form` used here), `sx`, MUI theming, and Framer Motion don't apply to shadow-DOM web components. Two styling systems coexisting. |
+| **Effort** | **High** and largely wasted — interop layer + still hand-building the expressive components + dual theming. |
+| **Bundle / free-tier** | Adds Lit runtime + per-component JS **on top of** MUI (can't cleanly drop MUI given 102 files). Net **larger** bundle. |
+| **Match to screenshot** | **Low for the expressive bits** (don't exist); only baseline M3 for the primitives it does ship. |
+| **Migration cost** | **Very high.** Re-author 100+ files away from MUI to coexist with web components; rewire forms and theming. |
+| **PWA/SSR** | App is client-rendered (Vite, no SSR), so SSR isn't a blocker — but shadow-DOM styling/theme-variable wiring and offline asset behavior add complexity for no payoff. |
+
+**Conclusion:** B is the wrong tool — abandoned, missing the exact components requested, heavy interop, bigger bundle, lower fidelity.
+
+---
+
+## Approach C — Hybrid (MUI + a few `@material/web` elements)
+
+All the downsides of B (dual styling, interop, maintenance risk, bundle) for the *subset* of components MWC ships — none of which are the expressive ones we actually lack. The components we'd want from MWC (Card, Toolbar, Split button, Button group, FAB menu) **don't exist there**, so the hybrid buys nothing. **Reject.** The only "hybrid" worth considering is *within* Approach A: MUI for primitives + a thin set of bespoke expressive components — which is just Approach A.
+
+---
+
+## Recommendation (final)
+
+**Go with Approach A.** Re-theme MUI to M3 Expressive via a seed→tonal token generator (`@material/material-color-utilities`), M3 shape/type/component overrides with state layers, Framer-Motion springs, and ~6 hand-built expressive components (Split button, Button group, Toolbar, expressive Card, FAB menu, waveform progress). It is the only path that (a) reaches the screenshot, (b) keeps the backend/data layer and TanStack Query untouched, (c) reuses the 102-file MUI investment and insulates the 39 token-consumers, and (d) adds ~zero bundle/free-tier cost.
+
+**Sequencing:** tokens/theme first (biggest visual win, lowest risk) → swap shadows for tonal surfaces + state layers → migrate `AppButton`/`Fab`/`BottomNav`/cards → add expressive components last. Each step is independently shippable and revertible. Optionally land a MUI v6→v7 codemod up front to stay on the maintained line; not required for M3.
+
+**Do not** adopt `@material/web` (B) or a hybrid (C): maintenance-mode, missing exactly the expressive components requested, interop tax, and a larger bundle for lower fidelity.

frontend/PWA/design/m3/m3-spec.md

@@ -0,0 +1,253 @@
+# Material 3 Expressive — Design System Spec (U1)
+
+> Source extraction for re-skinning the MilkWay ERP PWA from its current ad‑hoc theme to **Material 3 Expressive (M3E)**.
+> Authoritative token values below are pulled from the `material-web` repo (`tokens/versions/v0_192/*.scss`, the shipping M3 token set) and the M3 Expressive docs/blog. Where a doc page was JS‑rendered and unreadable, values were confirmed via the token SCSS or corroborating engineering write-ups (cited inline).
+
+---
+
+## 0. What "Expressive" actually changes (TL;DR)
+
+M3 Expressive (announced May 2025, the largest M3 update) is **not a new token namespace** — it reuses the same `md.sys.*` roles. What changes is *how* they're used:
+
+1. **Motion becomes spring physics**, not bezier+duration. New `motionScheme` with spatial vs effects springs; bounce/overshoot is intentional.
+2. **Shape becomes a first-class, animatable property.** A 35‑shape morph library; components **shape‑shift on press/select** (e.g. button corners round → squarish, FAB → menu).
+3. **Bigger, rounder, higher-contrast containers.** Pastel tonal surface containers (lowest→highest) used heavily; larger corner radii by default; "full" rounding instead of 50%.
+4. **New components**: button groups, split button, FAB menu, docked/floating toolbars, loading indicator, updated (wavy) progress.
+5. **Emphasized type** — heavier weights on key labels; type is treated as an expressive brand asset.
+
+The current MilkWay theme satisfies *none* of these (see §8). This is a full re‑skin, not a palette tweak.
+
+---
+
+## 1. Color roles & the tonal system
+
+### 1.1 Seed → tonal palettes → roles
+M3 color is generated, not hand-picked:
+
+1. Pick **one seed color** (brand). HCT (Hue/Chroma/Tone) algorithm derives **5 source palettes**: `primary`, `secondary`, `tertiary`, `neutral`, `neutral-variant` (plus a fixed `error` palette).
+2. Each palette is sampled at **13 tone stops**: `0, 10, 20, 30, 40, 50, 60, 70, 80, 90, 95, 99, 100` (tone = perceptual L*, 0=black, 100=white). The neutral palette adds extra stops `4, 6, 12, 17, 22, 24, 87, 92, 94, 96, 98` — **these extra neutral tones are exactly what the surface-container ladder needs.**
+3. **Roles map to tones.** Light theme (the relevant one — app is light):
+
+| Role | Light tone | Dark tone |
+|---|---|---|
+| primary | P40 | P80 |
+| on-primary | P100 | P20 |
+| primary-container | P90 | P30 |
+| on-primary-container | P30 (P10 older) | P90 |
+| secondary / tertiary | same pattern on S/T palettes | |
+| error | E40 | E80 |
+| error-container | E90 | E30 |
+| outline | NV50 | NV60 |
+| outline-variant | NV80 | NV30 |
+| on-surface | N10 | N90 |
+| on-surface-variant | NV30 | NV80 |
+
+`secondary` and `tertiary` follow the identical 40/100/90/30 mapping on their own palettes. **Tertiary is the "expressive accent"** — M3E leans on it for delight (FAB menu items, highlights).
+
+### 1.2 The surface container ladder (the heart of the "pastel" feel)
+Old M3 used one `surface` + `surface-variant`. Current M3/M3E uses a **tonal elevation ladder** built from neutral tones — flat color instead of shadows:
+
+| Role | Light source tone | Use |
+|---|---|---|
+| surface-dim | N87 | dimmest bg |
+| surface | N98 | default page bg |
+| surface-bright | N98 | brightest bg |
+| surface-container-lowest | N100 (white) | lowest cards |
+| surface-container-low | N96 | |
+| surface-container | N94 | default card/sheet |
+| surface-container-high | N92 | raised (FAB rests here) |
+| surface-container-highest | N90 | highest, e.g. menus |
+
+These are **subtle, low-chroma pastels** (neutral palette is tinted by the seed hue), which is the M3E "tonal/pastel" look. Components stack by *swapping container role*, not by adding box-shadow.
+
+### 1.3 Full role inventory (the `md.sys.color.*` set)
+`primary, on-primary, primary-container, on-primary-container, primary-fixed, primary-fixed-dim, on-primary-fixed, on-primary-fixed-variant` (× secondary, × tertiary), `error, on-error, error-container, on-error-container`, `surface, on-surface, surface-variant, on-surface-variant, surface-dim, surface-bright, surface-container-{lowest,low,,high,highest}, surface-tint`, `outline, outline-variant`, `inverse-surface, inverse-on-surface, inverse-primary`, `background, on-background, scrim, shadow`.
+
+> **`*-fixed` roles**: stay the same tone across light/dark (for cross-theme persistent surfaces). `surface-tint` = primary, used for tonal-elevation overlays.
+
+### 1.4 Expressive color guidance
+- Use **container roles** (`primary-container` on `on-primary-container`) far more than raw `primary` — softer, pastel, higher comfort.
+- Use **tertiary** for accents/delight; don't make everything primary.
+- Dynamic color is opt‑in; brand seed is fine. Warning from docs: dynamic color *"can easily create contrast issues"* if applied without intent. Always verify on-/container pairings hit contrast (≥3:1 large, 4.5:1 body).
+
+---
+
+## 2. Shape scale
+
+### 2.1 Corner radius tokens (`md.sys.shape.corner.*`, v0_192)
+| Token | Value |
+|---|---|
+| corner-none | **0 dp** |
+| corner-extra-small | **4 dp** |
+| corner-small | **8 dp** |
+| corner-medium | **12 dp** |
+| corner-large | **16 dp** |
+| corner-extra-large | **28 dp** |
+| corner-full | **9999 px** (pill / stadium — note: "full", not 50%) |
+
+Directional variants exist for sheets/rails: `corner-extra-large-top (28 28 0 0)`, `corner-large-start (16 0 0 16)`, `corner-large-end`, `corner-large-top`, `corner-extra-small-top`. (M3E adds intermediate stops in newer token sets — extra-small=4, small=8, medium=12, large=16, **extra-large=28**, plus **extra-extra-large** tiers ~48dp used by large FAB/expressive heroes.)
+
+### 2.2 Expressive shape behavior
+- **35-shape morph library** (Figma + Compose `MaterialShapes`): squircle, cookie, clover, pill, sunny, scallop, pixel, etc. Shapes carry brand/visual rhythm.
+- **Shape is animated.** Components **shape‑shift** between two shapes on interaction:
+  - Buttons / icon buttons: rounded → **squarer / smaller-radius on press** (corner value animates via spatial spring).
+  - Toggle/selected state changes the shape (e.g. round ↔ squircle).
+  - FAB → expands/morphs into FAB **menu** container.
+  - Split-button trailing menu button **spins and changes shape** when its menu opens.
+- Default radii are **larger and more generous** than M2/legacy. Cards/containers commonly use `large (16)`; big surfaces `extra-large (28)`; pills for chips/buttons (`full`).
+
+---
+
+## 3. Typography scale
+
+### 3.1 Type scale (`md.sys.typescale.*`, v0_192). rem @ 16px base; px in parens.
+| Role | Size | Line height | Weight | Tracking |
+|---|---|---|---|---|
+| display-large | 3.5625rem (57) | 4rem (64) | 400 | -0.25px |
+| display-medium | 2.8125rem (45) | 3.25rem (52) | 400 | 0 |
+| display-small | 2.25rem (36) | 2.75rem (44) | 400 | 0 |
+| headline-large | 2rem (32) | 2.5rem (40) | 400 | 0 |
+| headline-medium | 1.75rem (28) | 2.25rem (36) | 400 | 0 |
+| headline-small | 1.5rem (24) | 2rem (32) | 400 | 0 |
+| title-large | 1.375rem (22) | 1.75rem (28) | 400 | 0 |
+| title-medium | 1rem (16) | 1.5rem (24) | 500 | 0.15px |
+| title-small | 0.875rem (14) | 1.25rem (20) | 500 | 0.1px |
+| body-large | 1rem (16) | 1.5rem (24) | 400 | 0.5px |
+| body-medium | 0.875rem (14) | 1.25rem (20) | 400 | 0.25px |
+| body-small | 0.75rem (12) | 1rem (16) | 400 | 0.4px |
+| label-large | 0.875rem (14) | 1.25rem (20) | **500** | 0.1px |
+| label-medium | 0.75rem (12) | 1rem (16) | 500 | 0.5px |
+| label-small | 0.6875rem (11) | 1rem (16) | 500 | 0.5px |
+
+- Default reference typeface: **Roboto** (Roboto Flex for variable-weight expressive use).
+- **`label-large` is the button/label font** (`--md-sys-typescale-label-large-font`) — all button components use it.
+
+### 3.2 Expressive typography
+- Each role has an **"emphasized" companion** (heavier weight / tighter tracking) for hero text and key labels — type is used as a brand/emotion tool, not just hierarchy.
+- Use **Roboto Flex** variable axes (weight, optical size) to push expressive headings without new font files.
+- Practical: bump titles/labels to **600–700** on emphasis moments; keep body at 400.
+
+---
+
+## 4. Motion — spring physics (the biggest shift)
+
+### 4.1 Legacy easing+duration tokens (still exist, `md.sys.motion.*` v0_192)
+**Durations (ms):** short1 50, short2 100, short3 150, short4 200, medium1 250, medium2 300, medium3 350, medium4 400, long1 450, long2 500, long3 550, long4 600, extra-long1 700 … extra-long4 1000.
+
+**Easing (cubic-bezier):**
+| Token | Curve |
+|---|---|
+| linear | (0,0,1,1) |
+| standard | (0.2, 0, 0, 1) |
+| standard-accelerate | (0.3, 0, 1, 1) |
+| standard-decelerate | (0, 0, 0, 1) |
+| **emphasized** | (0.2, 0, 0, 1) (3-keyframe in practice; the "signature" M3 curve) |
+| emphasized-accelerate | (0.3, 0, 0.8, 0.15) |
+| emphasized-decelerate | (0.05, 0.7, 0.1, 1) |
+| legacy (M2) | (0.4, 0, 0.2, 1) |
+
+> The famous "emphasized" feel is a **3‑point** curve: accelerate then decelerate over ~500ms (long2). Use it for hero/page transitions if not using springs.
+
+### 4.2 The Expressive Motion Scheme (springs)
+M3E replaces curve+duration with **physics springs**. `MaterialTheme.motionScheme` exposes **6 spring specs** = 2 categories × 3 speeds:
+
+- **Spatial springs** — animate *position, size, rotation, corner radius* (overshoot/**bounce allowed**).
+- **Effects springs** — animate *color, opacity, elevation* (**no overshoot**, damping ≈ 1).
+
+Two schemes: **Expressive** (opinionated, bouncier — default for hero moments/key interactions) and **Standard** (functional, minimal bounce — utilitarian flows).
+
+**Verified token values** (`dampingRatio` / `stiffness`):
+| Spec | Damping | Stiffness | Notes |
+|---|---|---|---|
+| Expressive **spatial-fast** | 0.6 | 800 | quick, springy (chips, small toggles) |
+| Expressive **spatial-default** | 0.8 | 380 | standard moves (most spatial) |
+| Expressive **spatial-slow** | ~0.8 | ~200 | large/hero transitions |
+| Expressive **effects-fast/default/slow** | ~1.0 (no bounce) | ~3800 / ~1600 / ~800 | color/opacity, never overshoots |
+| Standard scheme | ~0.9–1.0 | similar stiffness, **lower bounce** | utilitarian |
+
+> Rule of thumb to port to web (Framer Motion `type:'spring'`): spatial uses `damping` 0.6–0.8 → bouncy; effects uses `damping` ≈1 → crisp. Stiffness ~380 default, ~800 fast. Effects (opacity/color) must **not** overshoot.
+
+### 4.3 Shape-shift / bump interactions
+- **Press bump**: on press, component scales down slightly + **corner radius morphs** (rounder→squarer) via spatial-fast spring; releases with overshoot ("bounce into place").
+- **Selection shape-shift**: selected toggle/segmented items change shape, not just color.
+- **Container morph**: FAB → FAB menu, button → loading, split-button menu spin — all spatial-spring shape transitions.
+- Always honor **`prefers-reduced-motion`**: collapse springs to instant/short cross-fade (the current theme already has this instinct in `motion.ts`).
+
+---
+
+## 5. State layers, elevation, density
+
+### 5.1 State layers (`md.sys.state.*`)
+Interaction feedback is a **translucent overlay of the content color** (`on-surface` / `primary` etc.) over the component, not a different background:
+| State | Opacity |
+|---|---|
+| hover | **8%** |
+| focus | **10–12%** |
+| pressed | **10%** (ripple originates here) |
+| dragged | 16% |
+
+Disabled: content @ **38%** opacity, container @ **12%**. (MUI's default `action.*` opacities differ — must be retuned to these.)
+
+### 5.2 Elevation
+- **Tonal elevation** is primary: raise = move up the surface-container ladder (§1.2), not add shadow. `surface-tint` (=primary) can overlay for tinted elevation.
+- Shadow levels `md.sys.elevation.level0..5`: 0, 1, 3, 6, 8, 12 dp. M3E uses **shadow sparingly** — mostly FABs, menus, dialogs. Most cards = flat tonal container + (optional) `outline-variant` 1px.
+- FAB container rests at `surface-container-high`; its lowered variant at `surface-container-low`.
+
+### 5.3 Density / touch targets
+- Minimum touch target **48×48 dp** (current theme uses 44 — slightly under M3).
+- M3E components ship in **size ramps**: buttons/split-buttons/FAB in **XS, S, M, L, XL**; bigger defaults than legacy.
+
+---
+
+## 6. New & updated Expressive components
+
+| Component | Behavior / spec |
+|---|---|
+| **Common / Filled / Tonal / Elevated / Outlined / Text buttons** | 5 variants. Shape token `--md-*-button-container-shape` defaults to `corner-full` (pill). Label = `label-large`. M3E adds **5 sizes (XS–XL)** + **shape-shift on press** (corners morph). Tonal & elevated buttons sit on container roles. |
+| **Button groups** | New. A container holding multiple buttons/icon-buttons that apply **shape, motion, and width changes** together; pressing one can squeeze neighbors. XS–XL. Connected segmented look with springy widths. |
+| **Split button** | New. Leading button = primary action; trailing menu button = related secondary action. Trailing button **spins + changes shape** when its menu opens. 5 sizes; elevated/filled/tonal/outlined styles. |
+| **FAB** | Sizes: small **40dp** (icon 24), medium **56dp** (default, icon 24, shape `corner-large`/16), large **96dp** (icon 36, shape `corner-extra-large`/28). Colors: surface(default), primary, secondary, tertiary. **Branded FAB** (logo, medium/large only). Extended FAB = icon+label, no size variants. Container rests at `surface-container-high`. |
+| **FAB menu** | New (replaces speed dial). Opens from **any** FAB size & color; larger items with contrasting colors; FAB **morphs** into the menu container. |
+| **Toolbars (docked & floating)** | New. **Docked toolbar replaces the deprecated bottom app bar** — shorter, flexible, holds a row of actions. **Floating toolbar** = pill-shaped floating action cluster, flexible placement, can host a FAB. |
+| **Loading indicator** | New. For loads **< 5s**; an animated **morphing shape** (cycles through the shape library) — replaces indeterminate circular spinner in pull-to-refresh & quick loads. |
+| **Progress indicators (updated)** | Linear: `track-height 4px`, active-indicator `primary`, supports **buffer** (buffer dots) + indeterminate + `four-color`. Circular: `size 48px`, indicator width 8.33%, indeterminate + four-color. **Expressive variant is "wavy"** — the active track renders as a **waveform/wavy line** that straightens as it completes (the M3E signature progress look). |
+| **Chips** (assist/filter/input/suggestion) | Pill (`corner-small`/8 container, often `full`), state layers, can carry leading icon/avatar. |
+| **Switch / Slider** | M3E switch: larger thumb that grows on press; slider gets a **wavy active track** + notched thumb in expressive mode. |
+| **Cards** (elevated/filled/outlined) | Tonal containers; `corner-medium`/12→`large`/16; prefer outline/tonal over shadow. |
+| **Navigation** | Bottom **navigation bar** / **nav rail**; M3E adds flexible/expressive nav and the floating toolbar pattern for primary actions. |
+
+---
+
+## 7. Concrete porting cheatsheet (web / MUI v6)
+
+- **Color**: generate a tonal palette from the dairy brand seed (e.g. via `@material/material-color-utilities`) → emit `--md-sys-color-*` CSS vars (incl. the 8 surface-container roles). Map MUI `primary/secondary/error/background` to them; expose `tertiary`, container roles, and surface ladder as `theme.vars` / custom tokens.
+- **Shape**: replace ad-hoc `{sm8, md12, lg16, pill999}` with the full token scale `none0 / xs4 / s8 / m12 / l16 / xl28 / full`. Default cards→l16, sheets→xl28-top, buttons/chips→full.
+- **Type**: replace the bespoke `h1..button` block with the **15-role M3 scale** above; button uses `label-large` (14/20/500). Adopt Roboto Flex for emphasis.
+- **Motion**: model the 6 spring specs as Framer presets (`spatialFast {damping .6, stiffness 800}`, `spatialDefault {.8, 380}`, `effects {damping ~1, stiffness 1600}`); reserve bounce for spatial only; keep reduced-motion fallback.
+- **State layers**: retune overlays to hover 8% / focus 10% / press 10%, disabled 38%/12%.
+- **Components**: build the new ones MUI lacks (split button, button group, FAB menu, docked/floating toolbar, loading indicator, wavy progress) as custom; they don't exist in MUI v6 out of the box.
+
+---
+
+## 8. Honest criticism of the current MilkWay theme (`src/theme/`)
+
+The owner is right — the current theme is **not worth keeping** for an M3E target. Concrete problems:
+
+1. **Hardcoded hex palette, no tonal system** (`palette.ts`). `primary:#1E6FE0`, `secondary:#2E9E5B`, etc. are flat single values with only `main`/`contrastText`. There are **no container roles, no on- roles beyond contrastText, no surface-container ladder, no tertiary**. The entire pastel-tonal foundation of M3E is absent. The comment even brags it's "Solid, no neon" — i.e. deliberately the opposite of expressive tonal surfaces.
+2. **The colors are Tailwind defaults, not a brand seed.** `#16A34A`, `#D97706`, `#DC2626`, `#0EA5E9`, `#F59E0B`, slate text `#0F172A/#64748B/#94A3B8` are literally Tailwind's green-600/amber-600/red-600/sky-500/amber-500/slate ramp. No HCT, no generated harmony, no dark-theme tone mapping (despite the "dark-swap ready" claim — there is no dark palette).
+3. **Shadow-based elevation, not tonal.** `index.ts` defines `e1/e2/e3` box-shadows and fills all 25 MUI slots with `e3`. M3E is tonal-elevation-first; this is the old material-2 mental model.
+4. **Shape scale too small & non-M3.** `radius = {sm8, md12, lg16, pill999}`. Missing `xs4`, `xl28`, and the expressive large radii. Cards at 16 is fine, but there's no shape-morph concept and `borderRadius` base is 12 (M3 base is effectively per-component).
+5. **Typography is bespoke px values, not the M3 scale.** `h1:28/34/700 … button:15/20/600`. None of the 15 M3 roles, no display tier, no `label-large`, sizes/line-heights/tracking don't match. Inter instead of Roboto/Roboto Flex (acceptable, but not the expressive default).
+6. **Motion is bezier+duration only — no springs.** `motion.ts` has `dur/easing/ease` curves `(.2,0,.2,1)` etc. and a *single* `sheetSpring {damping30, stiffness320}`. M3E needs **6 spring specs** split into spatial (bouncy) vs effects (no overshoot). The custom easings don't even match M3's `emphasized`/`standard` curves. **Reduced-motion handling is the one genuinely good instinct here — keep it.**
+7. **No state-layer system.** Relies on MUI defaults; no hover-8/focus-10/press-10 overlay tokens.
+8. **Touch target 44px** (`MuiButton minHeight:44`) is under M3's 48dp minimum.
+9. **Status colors hardcoded** in `customTokens.status` as flat hex — in M3E these should derive from semantic roles (success→tertiary/green-container, warning→amber-container, error→error-container) so they re-tone with the palette.
+
+**Verdict:** the file structure (theme/palette/motion split, module augmentation, reduced-motion awareness) is reusable scaffolding, but **every value inside is non-M3** and must be regenerated from a seed. Treat it as a rewrite, not an edit.
+
+---
+
+## 9. Sources
+- material-web token SCSS (v0_192): `tokens/versions/v0_192/_md-sys-{shape,motion,typescale}.scss`, `_md-sys-color.scss`, `_md-ref-palette.scss` — authoritative numeric values.
+- material-web docs: `docs/components/{button,fab,progress}.md`.
+- M3 Expressive components & motion: supercharge.design/blog/material-3-expressive; 9to5google M3E coverage; ProAndroidDev / Medium (navczydev, zoewave) engineering write-ups for spring damping/stiffness values; m3.material.io (motion/shape/color/type overviews — JS-rendered, cross-checked).

frontend/PWA/index.html

@@ -8,14 +8,9 @@
       name="viewport"
       content="width=device-width, initial-scale=1.0, viewport-fit=cover"
     />
-    <meta name="theme-color" content="#1E6FE0" />
-    <!-- Global visible focus ring for keyboard users (DESIGN_SYSTEM §10). -->
-    <style>
-      :focus-visible {
-        outline: 2px solid #1e6fe0;
-        outline-offset: 2px;
-      }
-    </style>
+    <!-- M3 seed (#6750A4). Focus ring + body surface now live in src/styles/global.css,
+         driven by --md-sys-color-* vars so they follow the light/dark data-attr flip. -->
+    <meta name="theme-color" content="#6750A4" />
     <meta name="apple-mobile-web-app-capable" content="yes" />
     <meta name="apple-mobile-web-app-status-bar-style" content="default" />
     <meta name="description" content="MilkWay ERP — dairy route, billing & analytics" />

frontend/PWA/package-lock.json

@@ -10,7 +10,9 @@
       "dependencies": {
         "@emotion/react": "^11.13.3",
         "@emotion/styled": "^11.13.0",
+        "@fontsource-variable/roboto-flex": "^5.2.8",
         "@fontsource/inter": "^5.1.0",
+        "@material/material-color-utilities": "^0.4.0",
         "@mui/icons-material": "^6.1.6",
         "@mui/material": "^6.1.6",
         "@tanstack/react-query": "^5.59.16",
@@ -2157,6 +2159,15 @@
         "node": ">=12"
       }
     },
+    "node_modules/@fontsource-variable/roboto-flex": {
+      "version": "5.2.8",
+      "resolved": "https://registry.npmjs.org/@fontsource-variable/roboto-flex/-/roboto-flex-5.2.8.tgz",
+      "integrity": "sha512-Q9zbz+P2VrDeIxBu9YAIG+eYpLmQF5FIJEEwAWn8En9Lao1TOISnoYcywGV+jSv7LGsHEndCR8hveXPnvCBEQQ==",
+      "license": "OFL-1.1",
+      "funding": {
+        "url": "https://github.com/sponsors/ayuhito"
+      }
+    },
     "node_modules/@fontsource/inter": {
       "version": "5.2.8",
       "resolved": "https://registry.npmjs.org/@fontsource/inter/-/inter-5.2.8.tgz",
@@ -2233,6 +2244,12 @@
         "@jridgewell/sourcemap-codec": "^1.4.14"
       }
     },
+    "node_modules/@material/material-color-utilities": {
+      "version": "0.4.0",
+      "resolved": "https://registry.npmjs.org/@material/material-color-utilities/-/material-color-utilities-0.4.0.tgz",
+      "integrity": "sha512-dlq6VExJReb8dhjj3a/yTigr3ncNwoFmL5Iy2ENtbDX03EmNeOEdZ+vsaGrj7RTuO+mB7L58II4LCsl4NpM8uw==",
+      "license": "Apache-2.0"
+    },
     "node_modules/@mui/core-downloads-tracker": {
       "version": "6.5.0",
       "resolved": "https://registry.npmjs.org/@mui/core-downloads-tracker/-/core-downloads-tracker-6.5.0.tgz",

frontend/PWA/package.json

@@ -13,7 +13,9 @@
   "dependencies": {
     "@emotion/react": "^11.13.3",
     "@emotion/styled": "^11.13.0",
+    "@fontsource-variable/roboto-flex": "^5.2.8",
     "@fontsource/inter": "^5.1.0",
+    "@material/material-color-utilities": "^0.4.0",
     "@mui/icons-material": "^6.1.6",
     "@mui/material": "^6.1.6",
     "@tanstack/react-query": "^5.59.16",

frontend/PWA/scripts/gen-m3.mjs

@@ -0,0 +1,33 @@
+/**
+ * Build-time runner for the M3 color generator.
+ *
+ * @material/material-color-utilities@0.4.0 ships ESM with a few extension-less
+ * internal imports that Node's strict resolver rejects, so we esbuild-bundle the
+ * TS generator (esbuild fixes the extensions) to a temp .mjs and execute it.
+ *
+ * Run from the PWA project root:  node scripts/gen-m3.mjs
+ * Emits (committed): src/theme/m3/roles.ts and src/theme/m3/tokens.css
+ */
+import { build } from 'esbuild';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { dirname, resolve } from 'node:path';
+import { rmSync } from 'node:fs';
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const entry = resolve(root, 'src/theme/m3/generate.ts');
+const tmp = resolve(root, 'src/theme/m3/.generate.bundle.mjs');
+
+await build({
+  entryPoints: [entry],
+  bundle: true,
+  platform: 'node',
+  format: 'esm',
+  target: 'node18',
+  outfile: tmp,
+  logLevel: 'warning',
+});
+
+// generate.ts writes relative to process.cwd(); ensure that is the PWA root.
+process.chdir(root);
+await import(pathToFileURL(tmp).href);
+rmSync(tmp, { force: true });

frontend/PWA/src/main.tsx

@@ -1,16 +1,21 @@
 import { StrictMode } from 'react';
 import { createRoot } from 'react-dom/client';
-import { ThemeProvider } from '@mui/material/styles';
 import CssBaseline from '@mui/material/CssBaseline';
 import { QueryClientProvider } from '@tanstack/react-query';
 import { BrowserRouter } from 'react-router-dom';
 
-import '@fontsource/inter/400.css';
-import '@fontsource/inter/500.css';
-import '@fontsource/inter/600.css';
-import '@fontsource/inter/700.css';
+// Roboto Flex (M3 default) — self-hosted variable font (@fontsource-variable),
+// NOT a Google Fonts <link>. Replaces the old Inter @fontsource import. A
+// system fallback (-apple-system/Segoe UI/system-ui) is kept in theme + global.css.
+import '@fontsource-variable/roboto-flex';
 
-import { theme } from '@/theme';
+// Theme barrel imports m3/tokens.css (the --md-sys-color-* vars). Import it
+// BEFORE global.css so those custom properties resolve when global.css reads them.
+import { ThemeModeProvider } from '@/theme';
+
+// Global baseline: paints body/html from M3 surface vars, smooths the
+// light<->dark flip (bg/color only, reduced-motion-aware), M3 :focus-visible ring.
+import '@/styles/global.css';
 import { queryClient } from '@/app/queryClient';
 import { ToastProvider, ErrorBoundary } from '@/components';
 import { AppRoutes } from './AppRoutes';
@@ -20,7 +25,7 @@ if (!rootEl) throw new Error('Root element #root not found');
 
 createRoot(rootEl).render(
   <StrictMode>
-    <ThemeProvider theme={theme}>
+    <ThemeModeProvider>
       <CssBaseline />
       <QueryClientProvider client={queryClient}>
         <ToastProvider>
@@ -31,6 +36,6 @@ createRoot(rootEl).render(
           </BrowserRouter>
         </ToastProvider>
       </QueryClientProvider>
-    </ThemeProvider>
+    </ThemeModeProvider>
   </StrictMode>,
 );

frontend/PWA/src/styles/global.css

@@ -0,0 +1,56 @@
+/* Global CSS baseline — P3 (Roboto Flex + global).
+ *
+ * Drives the page surface from the M3 --md-sys-color-* CSS vars (defined in
+ * src/theme/m3/tokens.css). Because those vars flip via html[data-theme='dark']
+ * (see ThemeModeProvider), the theme switch is a pure CSS-var swap here — no
+ * React palette recompute (PERFORMANCE MANDATE).
+ *
+ * NOTE: this file is imported AFTER tokens.css in main.tsx, so the vars below
+ * resolve. It intentionally only paints background/color + the focus ring;
+ * components keep reading the MUI theme. Do NOT add layout here.
+ */
+
+/* Page surface comes straight from the M3 surface roles, so flipping
+ * html[data-theme] re-paints the whole page with zero JS. */
+html {
+  background-color: var(--md-sys-color-surface, #fdf8fd);
+  color: var(--md-sys-color-on-surface, #1c1b1e);
+  /* Keep the system fallback before the variable font hydrates. */
+  font-family: 'Roboto Flex Variable', 'Roboto Flex', Roboto, -apple-system,
+    'Segoe UI', system-ui, sans-serif;
+  -webkit-text-size-adjust: 100%;
+}
+
+body {
+  margin: 0;
+  background-color: var(--md-sys-color-surface, #fdf8fd);
+  color: var(--md-sys-color-on-surface, #1c1b1e);
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+/* Smooth the light <-> dark switch WITHOUT animating layout: only the two
+ * compositor-cheap paint properties, short, and scoped to the surface chrome.
+ * Components animate their own colors via MUI/Framer; this is just the page. */
+html,
+body {
+  transition:
+    background-color 200ms ease,
+    color 200ms ease;
+}
+
+/* M3 focus ring: a 3:1-contrast primary outline for keyboard users.
+ * Replaces the hardcoded brand-blue ring that used to live in index.html. */
+:focus-visible {
+  outline: 2px solid var(--md-sys-color-primary, #6750a4);
+  outline-offset: 2px;
+}
+
+/* Honor reduced-motion: kill the theme-switch transition entirely so the
+ * flip is instant and we never animate for motion-sensitive users. */
+@media (prefers-reduced-motion: reduce) {
+  html,
+  body {
+    transition: none;
+  }
+}

frontend/PWA/src/theme/ThemeModeProvider.tsx

@@ -0,0 +1,83 @@
+// Theme-mode store + provider.
+// PERFORMANCE MANDATE: the M3 *color* vars (--md-sys-color-*) switch via a
+// data-attribute flip on <html> (tokens.css), NOT a React palette recompute.
+// We still swap the MUI Theme object (light/dark are prebuilt once) so MUI
+// components that read palette hex theme correctly — but no palette is rebuilt
+// at runtime.
+
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+  type ReactNode,
+} from 'react';
+import { ThemeProvider } from '@mui/material/styles';
+import { lightTheme, darkTheme } from './index';
+
+export type ThemeMode = 'light' | 'dark';
+
+const STORAGE_KEY = 'mw-theme-mode';
+
+type ThemeModeContextValue = {
+  mode: ThemeMode;
+  setMode: (m: ThemeMode) => void;
+  toggleMode: () => void;
+};
+
+const ThemeModeContext = createContext<ThemeModeContextValue | null>(null);
+
+function getInitialMode(): ThemeMode {
+  if (typeof window === 'undefined') return 'light';
+  const stored = window.localStorage.getItem(STORAGE_KEY);
+  if (stored === 'light' || stored === 'dark') return stored;
+  // Default light; respect prefers-color-scheme only as the INITIAL hint.
+  if (window.matchMedia?.('(prefers-color-scheme: dark)').matches) return 'dark';
+  return 'light';
+}
+
+function applyHtmlAttr(mode: ThemeMode) {
+  if (typeof document === 'undefined') return;
+  document.documentElement.setAttribute('data-theme', mode);
+}
+
+export function ThemeModeProvider({ children }: { children: ReactNode }) {
+  const [mode, setModeState] = useState<ThemeMode>(getInitialMode);
+
+  // Flip html[data-theme] so the CSS vars switch with zero React palette cost.
+  useEffect(() => {
+    applyHtmlAttr(mode);
+    try {
+      window.localStorage.setItem(STORAGE_KEY, mode);
+    } catch {
+      /* storage may be unavailable (private mode) — non-fatal */
+    }
+  }, [mode]);
+
+  const setMode = useCallback((m: ThemeMode) => setModeState(m), []);
+  const toggleMode = useCallback(
+    () => setModeState((m) => (m === 'light' ? 'dark' : 'light')),
+    [],
+  );
+
+  const ctx = useMemo<ThemeModeContextValue>(
+    () => ({ mode, setMode, toggleMode }),
+    [mode, setMode, toggleMode],
+  );
+
+  const muiTheme = mode === 'dark' ? darkTheme : lightTheme;
+
+  return (
+    <ThemeModeContext.Provider value={ctx}>
+      <ThemeProvider theme={muiTheme}>{children}</ThemeProvider>
+    </ThemeModeContext.Provider>
+  );
+}
+
+export function useThemeMode(): ThemeModeContextValue {
+  const ctx = useContext(ThemeModeContext);
+  if (!ctx) throw new Error('useThemeMode must be used within <ThemeModeProvider>');
+  return ctx;
+}

frontend/PWA/src/theme/index.ts

@@ -1,117 +1,236 @@
 import { createTheme, type Theme } from '@mui/material/styles';
-import { palette, customTokens } from './palette';
-import { motion } from './motion';
+import { buildPalette, buildCustomTokens, type PaletteMode } from './palette';
+import { motion, stateLayer } from './motion';
+import { m3Roles } from './m3/roles';
+import './m3/tokens.css'; // emit --md-sys-color-* CSS vars (build-time, zero runtime cost)
 import './theme.d';
 
-// Radius tokens (DESIGN_SYSTEM §2.3): cards 16, interactive 12.
-const radius = { sm: 8, md: 12, lg: 16, pill: 999 } as const;
+// ---- SHAPE scale (M3 md.sys.shape.corner.*) --------------------------------
+// Existing names kept (sm/md/lg/pill); xs4 + xl28 ADDED. Default card = lg(16),
+// default borderRadius = 16 (M3 large). Sheets/dialogs/large-FAB use xl(28).
+const radius = { xs: 4, sm: 8, md: 12, lg: 16, xl: 28, pill: 999 } as const;
 
+// Roboto Flex (self-hosted via @fontsource-variable/roboto-flex, imported in main.tsx).
 const fontFamily = [
-  'Inter',
+  '"Roboto Flex Variable"',
+  '"Roboto Flex"',
+  'Roboto',
   '-apple-system',
   '"Segoe UI"',
-  'Roboto',
   'sans-serif',
 ].join(',');
 
-// Soft elevation ramp (DESIGN_SYSTEM §2.4). MUI needs all 25 slots.
-const e1 = '0 1px 2px rgba(15,23,42,.06)';
-const e2 = '0 4px 12px rgba(15,23,42,.08)';
-const e3 = '0 8px 24px rgba(15,23,42,.12)';
-const shadows: Theme['shadows'] = [
-  'none',
-  e1, // 1: cards at rest, list rows
-  e2, // 2: FAB, raised cards, popovers
-  e3, // 3: bottom sheets, dialogs, sticky action bar
-  e3, e3, e3, e3, e3, e3, e3, e3, e3, e3, e3, e3, e3, e3, e3, e3, e3, e3, e3, e3, e3,
-];
+// State-layer mixin: translucent overlay of the content color over a container.
+// Returns a CSS color-mix so it works against any base. (Build-time string.)
+function layer(content: string, base: string, op: number): string {
+  return `color-mix(in srgb, ${content} ${Math.round(op * 100)}%, ${base})`;
+}
 
-export const theme = createTheme({
-  palette: {
-    ...palette,
-    accent: customTokens.accent,
-  },
-  custom: {
-    border: customTokens.border,
-    surface: customTokens.surface,
-    eveningTint: customTokens.eveningTint,
-    status: customTokens.status,
-    radius,
-    motion,
-  },
-  shape: { borderRadius: radius.md },
-  shadows,
-  spacing: 8,
-  typography: {
-    fontFamily,
-    htmlFontSize: 16,
-    fontSize: 16,
-    h1: { fontSize: 28, lineHeight: '34px', fontWeight: 700 },
-    h2: { fontSize: 24, lineHeight: '30px', fontWeight: 700 },
-    h3: { fontSize: 20, lineHeight: '26px', fontWeight: 600 },
-    h4: { fontSize: 18, lineHeight: '24px', fontWeight: 600 },
-    subtitle1: { fontSize: 16, lineHeight: '22px', fontWeight: 600 },
-    subtitle2: { fontSize: 14, lineHeight: '20px', fontWeight: 600 },
-    body1: { fontSize: 16, lineHeight: '24px', fontWeight: 400 },
-    body2: { fontSize: 14, lineHeight: '20px', fontWeight: 400 },
-    caption: { fontSize: 12, lineHeight: '16px', fontWeight: 500 },
-    overline: {
-      fontSize: 12,
-      lineHeight: '16px',
-      fontWeight: 600,
-      letterSpacing: '0.06em',
-      textTransform: 'uppercase',
-    },
-    button: { fontSize: 15, lineHeight: '20px', fontWeight: 600, textTransform: 'none' },
-  },
-  components: {
-    MuiButtonBase: {
-      defaultProps: { disableRipple: false },
+export function buildTheme(mode: PaletteMode): Theme {
+  const palette = buildPalette(mode);
+  const customTokens = buildCustomTokens(mode);
+  const r = m3Roles[mode];
+
+  // ---- TONAL elevation: keep e1/e2/e3 NAMES, back them with surface-container
+  // tints + minimal shadow (tonal-first per M3 / PERFORMANCE MANDATE). The
+  // string values are still valid box-shadows so existing `shadows[n]` reads work.
+  const e1 = mode === 'light' ? '0 1px 2px rgba(0,0,0,.06)' : '0 1px 2px rgba(0,0,0,.30)';
+  const e2 = mode === 'light' ? '0 2px 6px rgba(0,0,0,.08)' : '0 2px 6px rgba(0,0,0,.36)';
+  const e3 = mode === 'light' ? '0 6px 18px rgba(0,0,0,.10)' : '0 6px 18px rgba(0,0,0,.44)';
+  const shadows: Theme['shadows'] = [
+    'none',
+    e1, // 1: cards at rest, list rows
+    e2, // 2: FAB, raised cards, popovers
+    e3, // 3: bottom sheets, dialogs, sticky action bar
+    e3, e3, e3, e3, e3, e3, e3, e3, e3, e3, e3, e3, e3, e3, e3, e3, e3, e3, e3, e3, e3,
+  ];
+
+  return createTheme({
+    palette: {
+      ...palette,
+      accent: customTokens.accent,
     },
-    MuiButton: {
-      defaultProps: { disableElevation: false },
-      styleOverrides: {
-        root: { borderRadius: radius.md, textTransform: 'none', minHeight: 44 },
+    custom: {
+      // legacy token names — kept alive, mapped to M3 roles
+      border: customTokens.border,
+      surface: customTokens.surface,
+      eveningTint: customTokens.eveningTint,
+      status: customTokens.status,
+      radius,
+      motion,
+      // NEW: full M3 role set + surface tiers (for new expressive components)
+      m3: r,
+      surfaces: {
+        dim: r['surface-dim'],
+        bright: r['surface-bright'],
+        containerLowest: r['surface-container-lowest'],
+        containerLow: r['surface-container-low'],
+        container: r['surface-container'],
+        containerHigh: r['surface-container-high'],
+        containerHighest: r['surface-container-highest'],
       },
     },
-    MuiPaper: {
-      styleOverrides: {
-        rounded: { borderRadius: radius.lg },
+    shape: { borderRadius: radius.lg },
+    shadows,
+    spacing: 8,
+    typography: {
+      fontFamily,
+      htmlFontSize: 16,
+      fontSize: 16,
+      // ---- MUI variants re-mapped to closest M3 role metrics (§3.3) --------
+      // h1 -> headline-large, h2 -> headline-medium, h3 -> headline-small,
+      // h4 -> title-large, h5 -> title-medium, h6 -> title-medium,
+      // subtitle1 -> title-medium, subtitle2 -> title-small,
+      // body1 -> body-large, body2 -> body-medium, caption -> body-small,
+      // button -> label-large, overline -> label-small (uppercased).
+      h1: { fontSize: 32, lineHeight: '40px', fontWeight: 400, letterSpacing: 0 },
+      h2: { fontSize: 28, lineHeight: '36px', fontWeight: 400, letterSpacing: 0 },
+      h3: { fontSize: 24, lineHeight: '32px', fontWeight: 400, letterSpacing: 0 },
+      h4: { fontSize: 22, lineHeight: '28px', fontWeight: 400, letterSpacing: 0 },
+      h5: { fontSize: 16, lineHeight: '24px', fontWeight: 500, letterSpacing: '0.15px' },
+      h6: { fontSize: 16, lineHeight: '24px', fontWeight: 500, letterSpacing: '0.15px' },
+      subtitle1: { fontSize: 16, lineHeight: '24px', fontWeight: 500, letterSpacing: '0.15px' },
+      subtitle2: { fontSize: 14, lineHeight: '20px', fontWeight: 500, letterSpacing: '0.1px' },
+      body1: { fontSize: 16, lineHeight: '24px', fontWeight: 400, letterSpacing: '0.5px' },
+      body2: { fontSize: 14, lineHeight: '20px', fontWeight: 400, letterSpacing: '0.25px' },
+      caption: { fontSize: 12, lineHeight: '16px', fontWeight: 400, letterSpacing: '0.4px' },
+      overline: {
+        fontSize: 11,
+        lineHeight: '16px',
+        fontWeight: 500,
+        letterSpacing: '0.5px',
+        textTransform: 'uppercase',
       },
-    },
-    MuiCard: {
-      defaultProps: { elevation: 1 },
-      styleOverrides: {
-        root: { borderRadius: radius.lg, border: `1px solid ${customTokens.border}` },
+      button: {
+        fontSize: 14,
+        lineHeight: '20px',
+        fontWeight: 500,
+        letterSpacing: '0.1px',
+        textTransform: 'none',
       },
+      // ---- M3 role names ADDED as typography entries (for new components) ----
+      displayLarge: { fontSize: 57, lineHeight: '64px', fontWeight: 400, letterSpacing: '-0.25px' },
+      displayMedium: { fontSize: 45, lineHeight: '52px', fontWeight: 400, letterSpacing: 0 },
+      displaySmall: { fontSize: 36, lineHeight: '44px', fontWeight: 400, letterSpacing: 0 },
+      headlineLarge: { fontSize: 32, lineHeight: '40px', fontWeight: 400, letterSpacing: 0 },
+      headlineMedium: { fontSize: 28, lineHeight: '36px', fontWeight: 400, letterSpacing: 0 },
+      headlineSmall: { fontSize: 24, lineHeight: '32px', fontWeight: 400, letterSpacing: 0 },
+      titleLarge: { fontSize: 22, lineHeight: '28px', fontWeight: 400, letterSpacing: 0 },
+      titleMedium: { fontSize: 16, lineHeight: '24px', fontWeight: 500, letterSpacing: '0.15px' },
+      titleSmall: { fontSize: 14, lineHeight: '20px', fontWeight: 500, letterSpacing: '0.1px' },
+      bodyLarge: { fontSize: 16, lineHeight: '24px', fontWeight: 400, letterSpacing: '0.5px' },
+      bodyMedium: { fontSize: 14, lineHeight: '20px', fontWeight: 400, letterSpacing: '0.25px' },
+      bodySmall: { fontSize: 12, lineHeight: '16px', fontWeight: 400, letterSpacing: '0.4px' },
+      labelLarge: { fontSize: 14, lineHeight: '20px', fontWeight: 500, letterSpacing: '0.1px' },
+      labelMedium: { fontSize: 12, lineHeight: '16px', fontWeight: 500, letterSpacing: '0.5px' },
+      labelSmall: { fontSize: 11, lineHeight: '16px', fontWeight: 500, letterSpacing: '0.5px' },
     },
-    MuiTextField: {
-      defaultProps: { variant: 'outlined', fullWidth: true },
-    },
-    MuiOutlinedInput: {
-      styleOverrides: {
-        root: { borderRadius: radius.md, fontSize: 16 },
+    components: {
+      MuiButtonBase: {
+        defaultProps: { disableRipple: false },
       },
-    },
-    MuiChip: {
-      styleOverrides: { root: { borderRadius: radius.pill, fontWeight: 500 } },
-    },
-    MuiCssBaseline: {
-      styleOverrides: {
-        ':root': {
-          '--mw-safe-top': 'env(safe-area-inset-top, 0px)',
-          '--mw-safe-bottom': 'env(safe-area-inset-bottom, 0px)',
-          '--mw-safe-left': 'env(safe-area-inset-left, 0px)',
-          '--mw-safe-right': 'env(safe-area-inset-right, 0px)',
+      MuiButton: {
+        defaultProps: { disableElevation: true },
+        styleOverrides: {
+          root: {
+            borderRadius: radius.pill, // M3 buttons are pills
+            textTransform: 'none',
+            minHeight: 48, // M3 48dp touch target
+            paddingLeft: 24,
+            paddingRight: 24,
+            fontSize: 14,
+            fontWeight: 500,
+            letterSpacing: '0.1px',
+            // M3 state layers (hover 8 / focus 10 / press 10) on the content color.
+            '&:hover': {
+              backgroundColor: layer(r['primary'], 'transparent', stateLayer.hover),
+            },
+            '&:active': {
+              backgroundColor: layer(r['primary'], 'transparent', stateLayer.pressed),
+            },
+          },
+          containedPrimary: {
+            '&:hover': {
+              backgroundColor: layer(r['on-primary'], r['primary'], stateLayer.hover),
+            },
+          },
+        },
+      },
+      MuiPaper: {
+        styleOverrides: {
+          rounded: { borderRadius: radius.lg },
+        },
+      },
+      MuiCard: {
+        defaultProps: { elevation: 0 },
+        styleOverrides: {
+          // Tonal card: surface-container fill + 1px outline-variant, no shadow.
+          root: {
+            borderRadius: radius.lg,
+            border: `1px solid ${customTokens.border}`,
+            backgroundColor: r['surface-container-low'],
+            backgroundImage: 'none',
+          },
+        },
+      },
+      MuiTextField: {
+        defaultProps: { variant: 'outlined', fullWidth: true },
+      },
+      MuiOutlinedInput: {
+        styleOverrides: {
+          root: { borderRadius: radius.sm, fontSize: 16 }, // M3 fields = small(8)
+        },
+      },
+      MuiChip: {
+        styleOverrides: { root: { borderRadius: radius.sm, fontWeight: 500 } },
+      },
+      MuiIconButton: {
+        styleOverrides: {
+          root: { minWidth: 48, minHeight: 48 }, // M3 48dp touch target
+        },
+      },
+      MuiCssBaseline: {
+        styleOverrides: {
+          ':root': {
+            '--mw-safe-top': 'env(safe-area-inset-top, 0px)',
+            '--mw-safe-bottom': 'env(safe-area-inset-bottom, 0px)',
+            '--mw-safe-left': 'env(safe-area-inset-left, 0px)',
+            '--mw-safe-right': 'env(safe-area-inset-right, 0px)',
+          },
+          html: { WebkitFontSmoothing: 'antialiased' },
+          // Body surface from the M3 var (global.css owns this too) so it follows
+          // the html[data-theme] flip — NOT the static palette hex — keeping the
+          // page bg in sync with the dark toggle without a React recompute.
+          body: {
+            backgroundColor: `var(--md-sys-color-surface, ${palette.background.default})`,
+            color: `var(--md-sys-color-on-surface, ${palette.text.primary})`,
+            margin: 0,
+          },
+          '#root': { minHeight: '100dvh' },
         },
-        html: { WebkitFontSmoothing: 'antialiased' },
-        body: { backgroundColor: palette.background.default, margin: 0 },
-        '#root': { minHeight: '100dvh' },
       },
     },
-  },
-});
+  });
+}
+
+export const lightTheme = buildTheme('light');
+export const darkTheme = buildTheme('dark');
+
+// Default export keeps the SAME name `theme` (light) so existing imports work.
+export const theme = lightTheme;
 
 export type AppTheme = typeof theme;
 export { palette, customTokens } from './palette';
-export { motion, dur, stagger, easing, ease, sheetSpring } from './motion';
+export {
+  motion,
+  dur,
+  stagger,
+  easing,
+  m3Easing,
+  ease,
+  spring,
+  sheetSpring,
+  stateLayer,
+  sec,
+} from './motion';
+export { ThemeModeProvider, useThemeMode } from './ThemeModeProvider';

frontend/PWA/src/theme/m3/generate.ts

@@ -0,0 +1,340 @@
+/**
+ * M3 color generator (P1 — Phase 0).
+ *
+ * From the locked brand seed (#6750A4, violet) this derives the FULL Material 3
+ * `md.sys.color.*` role set for LIGHT and DARK via HCT tonal palettes
+ * (@material/material-color-utilities), following the role->tone mapping in
+ * M3_THEME_PLAN.md §3.1 + the surface-container ladder in §1.2.
+ *
+ * It is a BUILD-TIME generator. Running it emits two committed artifacts so the
+ * app pays ZERO runtime color-computation cost (PERFORMANCE MANDATE):
+ *
+ *   (a) src/theme/m3/roles.ts  — typed `{ light, dark }` hex object for MUI to consume.
+ *   (b) src/theme/m3/tokens.css — `--md-sys-color-*` CSS vars: :root (light) +
+ *                                 html[data-theme='dark'] (dark). Theme switch is a
+ *                                 data-attribute flip, never a palette recompute.
+ *
+ * Run:  node scripts/gen-m3.mjs   (esbuild-bundles this file, then executes it)
+ *
+ * Do NOT import this module at app runtime — import the emitted `roles.ts` /
+ * `tokens.css` instead.
+ */
+import {
+  CorePalette,
+  TonalPalette,
+  Hct,
+  argbFromHex,
+  hexFromArgb,
+} from '@material/material-color-utilities';
+import { writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+// ---------------------------------------------------------------------------
+// Seed (LOCKED) + tonal palettes
+// ---------------------------------------------------------------------------
+
+/** Brand seed — LOCKED decision. Everything generates from this one value. */
+export const SEED = '#6750A4';
+
+/**
+ * The 6 source tonal palettes derived from the seed via HCT.
+ *  a1 = primary, a2 = secondary, a3 = tertiary,
+ *  n1 = neutral (feeds the surface ladder), n2 = neutral-variant, error = fixed.
+ */
+function corePalettes(seed: string) {
+  const cp = CorePalette.of(argbFromHex(seed));
+  return {
+    primary: cp.a1,
+    secondary: cp.a2,
+    tertiary: cp.a3,
+    neutral: cp.n1,
+    neutralVariant: cp.n2,
+    error: cp.error,
+  } satisfies Record<string, TonalPalette>;
+}
+
+/**
+ * Success & warning are SEMANTIC status colors that must re-tone with the
+ * palette. Per M3_THEME_PLAN §3.1 we derive them from fixed expressive hues
+ * (green for success, amber for warning) but at full M3 tonal chroma so they
+ * read as tonal container roles, not flat brand hexes. Info reuses the
+ * secondary palette (it is an informational, non-alarming accent).
+ */
+function statusPalettes(palettes: ReturnType<typeof corePalettes>) {
+  return {
+    // Green ~ hue 142, high chroma — success / paid / delivered / active.
+    success: TonalPalette.fromHueAndChroma(142, 48),
+    // Amber ~ hue 80, high chroma — warning / partial / hold.
+    warning: TonalPalette.fromHueAndChroma(80, 60),
+    // Info reuses secondary so it harmonises with the seed.
+    info: palettes.secondary,
+  } satisfies Record<string, TonalPalette>;
+}
+
+const tone = (tp: TonalPalette, t: number) => hexFromArgb(tp.tone(t));
+
+// ---------------------------------------------------------------------------
+// Role set
+// ---------------------------------------------------------------------------
+
+/** Every emitted role name (kept in one list so roles.ts + tokens.css stay in sync). */
+export const ROLE_NAMES = [
+  'primary',
+  'on-primary',
+  'primary-container',
+  'on-primary-container',
+  'primary-fixed',
+  'primary-fixed-dim',
+  'on-primary-fixed',
+  'on-primary-fixed-variant',
+  'secondary',
+  'on-secondary',
+  'secondary-container',
+  'on-secondary-container',
+  'secondary-fixed',
+  'secondary-fixed-dim',
+  'on-secondary-fixed',
+  'on-secondary-fixed-variant',
+  'tertiary',
+  'on-tertiary',
+  'tertiary-container',
+  'on-tertiary-container',
+  'tertiary-fixed',
+  'tertiary-fixed-dim',
+  'on-tertiary-fixed',
+  'on-tertiary-fixed-variant',
+  'error',
+  'on-error',
+  'error-container',
+  'on-error-container',
+  'success',
+  'on-success',
+  'success-container',
+  'on-success-container',
+  'warning',
+  'on-warning',
+  'warning-container',
+  'on-warning-container',
+  'info',
+  'on-info',
+  'info-container',
+  'on-info-container',
+  'background',
+  'on-background',
+  'surface',
+  'on-surface',
+  'surface-variant',
+  'on-surface-variant',
+  'surface-dim',
+  'surface-bright',
+  'surface-container-lowest',
+  'surface-container-low',
+  'surface-container',
+  'surface-container-high',
+  'surface-container-highest',
+  'outline',
+  'outline-variant',
+  'inverse-surface',
+  'inverse-on-surface',
+  'inverse-primary',
+  'surface-tint',
+  'scrim',
+  'shadow',
+] as const;
+
+export type RoleName = (typeof ROLE_NAMES)[number];
+export type RoleSet = Record<RoleName, string>;
+export type Roles = { light: RoleSet; dark: RoleSet };
+
+/**
+ * Builds one full role set for a given scheme.
+ * `m` selects the tone for a "main" accent (40 light / 80 dark) and the
+ * remaining accent tones follow the canonical M3 light/dark mapping (§3.1).
+ */
+function buildScheme(seed: string, mode: 'light' | 'dark'): RoleSet {
+  const p = corePalettes(seed);
+  const s = statusPalettes(p);
+  const light = mode === 'light';
+
+  // Accent quadruple: [main, on, container, on-container] tones per mode.
+  // Light:  40 / 100 / 90 / 30   | Dark: 80 / 20 / 30 / 90  (§3.1)
+  const accent = (tp: TonalPalette) =>
+    light
+      ? { main: tone(tp, 40), on: tone(tp, 100), container: tone(tp, 90), onContainer: tone(tp, 30) }
+      : { main: tone(tp, 80), on: tone(tp, 20), container: tone(tp, 30), onContainer: tone(tp, 90) };
+
+  // *-fixed roles stay constant across light/dark (cross-theme persistent surfaces).
+  const fixed = (tp: TonalPalette) => ({
+    fixed: tone(tp, 90),
+    fixedDim: tone(tp, 80),
+    onFixed: tone(tp, 10),
+    onFixedVariant: tone(tp, 30),
+  });
+
+  const P = accent(p.primary);
+  const S = accent(p.secondary);
+  const T = accent(p.tertiary);
+  const E = accent(p.error);
+  const Su = accent(s.success);
+  const Wa = accent(s.warning);
+  const In = accent(s.info);
+
+  const Pf = fixed(p.primary);
+  const Sf = fixed(p.secondary);
+  const Tf = fixed(p.tertiary);
+
+  const n = p.neutral;
+  const nv = p.neutralVariant;
+
+  return {
+    primary: P.main,
+    'on-primary': P.on,
+    'primary-container': P.container,
+    'on-primary-container': P.onContainer,
+    'primary-fixed': Pf.fixed,
+    'primary-fixed-dim': Pf.fixedDim,
+    'on-primary-fixed': Pf.onFixed,
+    'on-primary-fixed-variant': Pf.onFixedVariant,
+
+    secondary: S.main,
+    'on-secondary': S.on,
+    'secondary-container': S.container,
+    'on-secondary-container': S.onContainer,
+    'secondary-fixed': Sf.fixed,
+    'secondary-fixed-dim': Sf.fixedDim,
+    'on-secondary-fixed': Sf.onFixed,
+    'on-secondary-fixed-variant': Sf.onFixedVariant,
+
+    tertiary: T.main,
+    'on-tertiary': T.on,
+    'tertiary-container': T.container,
+    'on-tertiary-container': T.onContainer,
+    'tertiary-fixed': Tf.fixed,
+    'tertiary-fixed-dim': Tf.fixedDim,
+    'on-tertiary-fixed': Tf.onFixed,
+    'on-tertiary-fixed-variant': Tf.onFixedVariant,
+
+    error: E.main,
+    'on-error': E.on,
+    'error-container': E.container,
+    'on-error-container': E.onContainer,
+
+    // Semantic status — derived from tonal palettes, re-tone with the scheme.
+    success: Su.main,
+    'on-success': Su.on,
+    'success-container': Su.container,
+    'on-success-container': Su.onContainer,
+    warning: Wa.main,
+    'on-warning': Wa.on,
+    'warning-container': Wa.container,
+    'on-warning-container': Wa.onContainer,
+    info: In.main,
+    'on-info': In.on,
+    'info-container': In.container,
+    'on-info-container': In.onContainer,
+
+    // Backgrounds & surfaces (tonal). Light: N98/N10 ... Dark: N6/N90.
+    background: light ? tone(n, 98) : tone(n, 6),
+    'on-background': light ? tone(n, 10) : tone(n, 90),
+    surface: light ? tone(n, 98) : tone(n, 6),
+    'on-surface': light ? tone(n, 10) : tone(n, 90),
+    'surface-variant': light ? tone(nv, 90) : tone(nv, 30),
+    'on-surface-variant': light ? tone(nv, 30) : tone(nv, 80),
+
+    // Surface-container ladder (§1.2) — tonal elevation, NOT shadow.
+    'surface-dim': light ? tone(n, 87) : tone(n, 6),
+    'surface-bright': light ? tone(n, 98) : tone(n, 24),
+    'surface-container-lowest': light ? tone(n, 100) : tone(n, 4),
+    'surface-container-low': light ? tone(n, 96) : tone(n, 10),
+    'surface-container': light ? tone(n, 94) : tone(n, 12),
+    'surface-container-high': light ? tone(n, 92) : tone(n, 17),
+    'surface-container-highest': light ? tone(n, 90) : tone(n, 22),
+
+    outline: light ? tone(nv, 50) : tone(nv, 60),
+    'outline-variant': light ? tone(nv, 80) : tone(nv, 30),
+
+    'inverse-surface': light ? tone(n, 20) : tone(n, 90),
+    'inverse-on-surface': light ? tone(n, 95) : tone(n, 20),
+    'inverse-primary': light ? tone(p.primary, 80) : tone(p.primary, 40),
+
+    'surface-tint': P.main,
+    scrim: tone(n, 0),
+    shadow: tone(n, 0),
+  };
+}
+
+export function generateRoles(seed: string = SEED): Roles {
+  return { light: buildScheme(seed, 'light'), dark: buildScheme(seed, 'dark') };
+}
+
+// ---------------------------------------------------------------------------
+// Emit (a) roles.ts and (b) tokens.css
+// ---------------------------------------------------------------------------
+
+function emitRolesTs(roles: Roles): string {
+  const setBody = (set: RoleSet) =>
+    ROLE_NAMES.map((r) => `    '${r}': '${set[r]}',`).join('\n');
+  return `/* AUTO-GENERATED by src/theme/m3/generate.ts — DO NOT EDIT BY HAND.
+ * Seed: ${SEED}. Regenerate with: node scripts/gen-m3.mjs
+ * Full M3 md.sys.color.* role set (light + dark) as hex, for MUI to consume. */
+
+export type M3RoleName =
+${ROLE_NAMES.map((r) => `  | '${r}'`).join('\n')};
+
+export type M3RoleSet = Record<M3RoleName, string>;
+
+export const m3Roles: { light: M3RoleSet; dark: M3RoleSet } = {
+  light: {
+${setBody(roles.light)}
+  },
+  dark: {
+${setBody(roles.dark)}
+  },
+};
+
+export default m3Roles;
+`;
+}
+
+function emitTokensCss(roles: Roles): string {
+  const vars = (set: RoleSet, indent: string) =>
+    ROLE_NAMES.map((r) => `${indent}--md-sys-color-${r}: ${set[r]};`).join('\n');
+  return `/* AUTO-GENERATED by src/theme/m3/generate.ts — DO NOT EDIT BY HAND.
+ * Seed: ${SEED}. Regenerate with: node scripts/gen-m3.mjs
+ * M3 color tokens as CSS custom properties. Theme switch = flip
+ * html[data-theme='dark'] (no React palette recompute — PERFORMANCE MANDATE). */
+
+:root {
+${vars(roles.light, '  ')}
+}
+
+html[data-theme='dark'] {
+${vars(roles.dark, '  ')}
+}
+
+/* Respect explicit light selection even if the OS prefers dark. */
+@media (prefers-color-scheme: dark) {
+  html:not([data-theme='light']):not([data-theme='dark']) {
+${vars(roles.dark, '    ')}
+  }
+}
+`;
+}
+
+/** Entry point — only runs when executed directly (not when imported). */
+function main() {
+  const roles = generateRoles(SEED);
+  // Outputs live alongside this generator. Run from the PWA project root so
+  // process.cwd() resolves to .../frontend/PWA (the runner enforces this).
+  const outDir = resolve(process.cwd(), 'src/theme/m3');
+  writeFileSync(resolve(outDir, 'roles.ts'), emitRolesTs(roles), 'utf8');
+  writeFileSync(resolve(outDir, 'tokens.css'), emitTokensCss(roles), 'utf8');
+  // eslint-disable-next-line no-console
+  console.log(
+    `[m3] generated ${ROLE_NAMES.length} roles x 2 schemes -> roles.ts + tokens.css (seed ${SEED})`,
+  );
+}
+
+// Execute only as a script. `Hct` import kept referenced for future seed tooling.
+void Hct;
+main();

frontend/PWA/src/theme/m3/roles.ts

@@ -0,0 +1,199 @@
+/* AUTO-GENERATED by src/theme/m3/generate.ts — DO NOT EDIT BY HAND.
+ * Seed: #6750A4. Regenerate with: node scripts/gen-m3.mjs
+ * Full M3 md.sys.color.* role set (light + dark) as hex, for MUI to consume. */
+
+export type M3RoleName =
+  | 'primary'
+  | 'on-primary'
+  | 'primary-container'
+  | 'on-primary-container'
+  | 'primary-fixed'
+  | 'primary-fixed-dim'
+  | 'on-primary-fixed'
+  | 'on-primary-fixed-variant'
+  | 'secondary'
+  | 'on-secondary'
+  | 'secondary-container'
+  | 'on-secondary-container'
+  | 'secondary-fixed'
+  | 'secondary-fixed-dim'
+  | 'on-secondary-fixed'
+  | 'on-secondary-fixed-variant'
+  | 'tertiary'
+  | 'on-tertiary'
+  | 'tertiary-container'
+  | 'on-tertiary-container'
+  | 'tertiary-fixed'
+  | 'tertiary-fixed-dim'
+  | 'on-tertiary-fixed'
+  | 'on-tertiary-fixed-variant'
+  | 'error'
+  | 'on-error'
+  | 'error-container'
+  | 'on-error-container'
+  | 'success'
+  | 'on-success'
+  | 'success-container'
+  | 'on-success-container'
+  | 'warning'
+  | 'on-warning'
+  | 'warning-container'
+  | 'on-warning-container'
+  | 'info'
+  | 'on-info'
+  | 'info-container'
+  | 'on-info-container'
+  | 'background'
+  | 'on-background'
+  | 'surface'
+  | 'on-surface'
+  | 'surface-variant'
+  | 'on-surface-variant'
+  | 'surface-dim'
+  | 'surface-bright'
+  | 'surface-container-lowest'
+  | 'surface-container-low'
+  | 'surface-container'
+  | 'surface-container-high'
+  | 'surface-container-highest'
+  | 'outline'
+  | 'outline-variant'
+  | 'inverse-surface'
+  | 'inverse-on-surface'
+  | 'inverse-primary'
+  | 'surface-tint'
+  | 'scrim'
+  | 'shadow';
+
+export type M3RoleSet = Record<M3RoleName, string>;
+
+export const m3Roles: { light: M3RoleSet; dark: M3RoleSet } = {
+  light: {
+    'primary': '#6750a4',
+    'on-primary': '#ffffff',
+    'primary-container': '#e9ddff',
+    'on-primary-container': '#4f378a',
+    'primary-fixed': '#e9ddff',
+    'primary-fixed-dim': '#cfbcff',
+    'on-primary-fixed': '#22005d',
+    'on-primary-fixed-variant': '#4f378a',
+    'secondary': '#625b71',
+    'on-secondary': '#ffffff',
+    'secondary-container': '#e8def8',
+    'on-secondary-container': '#4a4458',
+    'secondary-fixed': '#e8def8',
+    'secondary-fixed-dim': '#cbc2db',
+    'on-secondary-fixed': '#1e192b',
+    'on-secondary-fixed-variant': '#4a4458',
+    'tertiary': '#7e5260',
+    'on-tertiary': '#ffffff',
+    'tertiary-container': '#ffd9e3',
+    'on-tertiary-container': '#633b48',
+    'tertiary-fixed': '#ffd9e3',
+    'tertiary-fixed-dim': '#efb8c8',
+    'on-tertiary-fixed': '#31101d',
+    'on-tertiary-fixed-variant': '#633b48',
+    'error': '#ba1a1a',
+    'on-error': '#ffffff',
+    'error-container': '#ffdad6',
+    'on-error-container': '#93000a',
+    'success': '#306b25',
+    'on-success': '#ffffff',
+    'success-container': '#b1f49d',
+    'on-success-container': '#16520e',
+    'warning': '#7d5700',
+    'on-warning': '#ffffff',
+    'warning-container': '#ffdeab',
+    'on-warning-container': '#5f4100',
+    'info': '#625b71',
+    'on-info': '#ffffff',
+    'info-container': '#e8def8',
+    'on-info-container': '#4a4458',
+    'background': '#fdf8fd',
+    'on-background': '#1c1b1e',
+    'surface': '#fdf8fd',
+    'on-surface': '#1c1b1e',
+    'surface-variant': '#e7e0eb',
+    'on-surface-variant': '#49454e',
+    'surface-dim': '#ddd8dd',
+    'surface-bright': '#fdf8fd',
+    'surface-container-lowest': '#ffffff',
+    'surface-container-low': '#f7f2f7',
+    'surface-container': '#f2ecf1',
+    'surface-container-high': '#ece7eb',
+    'surface-container-highest': '#e6e1e6',
+    'outline': '#7a757f',
+    'outline-variant': '#cac4cf',
+    'inverse-surface': '#313033',
+    'inverse-on-surface': '#f4eff4',
+    'inverse-primary': '#cfbcff',
+    'surface-tint': '#6750a4',
+    'scrim': '#000000',
+    'shadow': '#000000',
+  },
+  dark: {
+    'primary': '#cfbcff',
+    'on-primary': '#381e72',
+    'primary-container': '#4f378a',
+    'on-primary-container': '#e9ddff',
+    'primary-fixed': '#e9ddff',
+    'primary-fixed-dim': '#cfbcff',
+    'on-primary-fixed': '#22005d',
+    'on-primary-fixed-variant': '#4f378a',
+    'secondary': '#cbc2db',
+    'on-secondary': '#332d41',
+    'secondary-container': '#4a4458',
+    'on-secondary-container': '#e8def8',
+    'secondary-fixed': '#e8def8',
+    'secondary-fixed-dim': '#cbc2db',
+    'on-secondary-fixed': '#1e192b',
+    'on-secondary-fixed-variant': '#4a4458',
+    'tertiary': '#efb8c8',
+    'on-tertiary': '#4a2532',
+    'tertiary-container': '#633b48',
+    'on-tertiary-container': '#ffd9e3',
+    'tertiary-fixed': '#ffd9e3',
+    'tertiary-fixed-dim': '#efb8c8',
+    'on-tertiary-fixed': '#31101d',
+    'on-tertiary-fixed-variant': '#633b48',
+    'error': '#ffb4ab',
+    'on-error': '#690005',
+    'error-container': '#93000a',
+    'on-error-container': '#ffdad6',
+    'success': '#96d783',
+    'on-success': '#013a00',
+    'success-container': '#16520e',
+    'on-success-container': '#b1f49d',
+    'warning': '#ffba30',
+    'on-warning': '#422c00',
+    'warning-container': '#5f4100',
+    'on-warning-container': '#ffdeab',
+    'info': '#cbc2db',
+    'on-info': '#332d41',
+    'info-container': '#4a4458',
+    'on-info-container': '#e8def8',
+    'background': '#141316',
+    'on-background': '#e6e1e6',
+    'surface': '#141316',
+    'on-surface': '#e6e1e6',
+    'surface-variant': '#49454e',
+    'on-surface-variant': '#cac4cf',
+    'surface-dim': '#141316',
+    'surface-bright': '#3a383c',
+    'surface-container-lowest': '#0f0e11',
+    'surface-container-low': '#1c1b1e',
+    'surface-container': '#201f22',
+    'surface-container-high': '#2b292d',
+    'surface-container-highest': '#363438',
+    'outline': '#948f99',
+    'outline-variant': '#49454e',
+    'inverse-surface': '#e6e1e6',
+    'inverse-on-surface': '#313033',
+    'inverse-primary': '#6750a4',
+    'surface-tint': '#cfbcff',
+    'scrim': '#000000',
+    'shadow': '#000000',
+  },
+};
+
+export default m3Roles;

frontend/PWA/src/theme/m3/tokens.css

@@ -0,0 +1,199 @@
+/* AUTO-GENERATED by src/theme/m3/generate.ts — DO NOT EDIT BY HAND.
+ * Seed: #6750A4. Regenerate with: node scripts/gen-m3.mjs
+ * M3 color tokens as CSS custom properties. Theme switch = flip
+ * html[data-theme='dark'] (no React palette recompute — PERFORMANCE MANDATE). */
+
+:root {
+  --md-sys-color-primary: #6750a4;
+  --md-sys-color-on-primary: #ffffff;
+  --md-sys-color-primary-container: #e9ddff;
+  --md-sys-color-on-primary-container: #4f378a;
+  --md-sys-color-primary-fixed: #e9ddff;
+  --md-sys-color-primary-fixed-dim: #cfbcff;
+  --md-sys-color-on-primary-fixed: #22005d;
+  --md-sys-color-on-primary-fixed-variant: #4f378a;
+  --md-sys-color-secondary: #625b71;
+  --md-sys-color-on-secondary: #ffffff;
+  --md-sys-color-secondary-container: #e8def8;
+  --md-sys-color-on-secondary-container: #4a4458;
+  --md-sys-color-secondary-fixed: #e8def8;
+  --md-sys-color-secondary-fixed-dim: #cbc2db;
+  --md-sys-color-on-secondary-fixed: #1e192b;
+  --md-sys-color-on-secondary-fixed-variant: #4a4458;
+  --md-sys-color-tertiary: #7e5260;
+  --md-sys-color-on-tertiary: #ffffff;
+  --md-sys-color-tertiary-container: #ffd9e3;
+  --md-sys-color-on-tertiary-container: #633b48;
+  --md-sys-color-tertiary-fixed: #ffd9e3;
+  --md-sys-color-tertiary-fixed-dim: #efb8c8;
+  --md-sys-color-on-tertiary-fixed: #31101d;
+  --md-sys-color-on-tertiary-fixed-variant: #633b48;
+  --md-sys-color-error: #ba1a1a;
+  --md-sys-color-on-error: #ffffff;
+  --md-sys-color-error-container: #ffdad6;
+  --md-sys-color-on-error-container: #93000a;
+  --md-sys-color-success: #306b25;
+  --md-sys-color-on-success: #ffffff;
+  --md-sys-color-success-container: #b1f49d;
+  --md-sys-color-on-success-container: #16520e;
+  --md-sys-color-warning: #7d5700;
+  --md-sys-color-on-warning: #ffffff;
+  --md-sys-color-warning-container: #ffdeab;
+  --md-sys-color-on-warning-container: #5f4100;
+  --md-sys-color-info: #625b71;
+  --md-sys-color-on-info: #ffffff;
+  --md-sys-color-info-container: #e8def8;
+  --md-sys-color-on-info-container: #4a4458;
+  --md-sys-color-background: #fdf8fd;
+  --md-sys-color-on-background: #1c1b1e;
+  --md-sys-color-surface: #fdf8fd;
+  --md-sys-color-on-surface: #1c1b1e;
+  --md-sys-color-surface-variant: #e7e0eb;
+  --md-sys-color-on-surface-variant: #49454e;
+  --md-sys-color-surface-dim: #ddd8dd;
+  --md-sys-color-surface-bright: #fdf8fd;
+  --md-sys-color-surface-container-lowest: #ffffff;
+  --md-sys-color-surface-container-low: #f7f2f7;
+  --md-sys-color-surface-container: #f2ecf1;
+  --md-sys-color-surface-container-high: #ece7eb;
+  --md-sys-color-surface-container-highest: #e6e1e6;
+  --md-sys-color-outline: #7a757f;
+  --md-sys-color-outline-variant: #cac4cf;
+  --md-sys-color-inverse-surface: #313033;
+  --md-sys-color-inverse-on-surface: #f4eff4;
+  --md-sys-color-inverse-primary: #cfbcff;
+  --md-sys-color-surface-tint: #6750a4;
+  --md-sys-color-scrim: #000000;
+  --md-sys-color-shadow: #000000;
+}
+
+html[data-theme='dark'] {
+  --md-sys-color-primary: #cfbcff;
+  --md-sys-color-on-primary: #381e72;
+  --md-sys-color-primary-container: #4f378a;
+  --md-sys-color-on-primary-container: #e9ddff;
+  --md-sys-color-primary-fixed: #e9ddff;
+  --md-sys-color-primary-fixed-dim: #cfbcff;
+  --md-sys-color-on-primary-fixed: #22005d;
+  --md-sys-color-on-primary-fixed-variant: #4f378a;
+  --md-sys-color-secondary: #cbc2db;
+  --md-sys-color-on-secondary: #332d41;
+  --md-sys-color-secondary-container: #4a4458;
+  --md-sys-color-on-secondary-container: #e8def8;
+  --md-sys-color-secondary-fixed: #e8def8;
+  --md-sys-color-secondary-fixed-dim: #cbc2db;
+  --md-sys-color-on-secondary-fixed: #1e192b;
+  --md-sys-color-on-secondary-fixed-variant: #4a4458;
+  --md-sys-color-tertiary: #efb8c8;
+  --md-sys-color-on-tertiary: #4a2532;
+  --md-sys-color-tertiary-container: #633b48;
+  --md-sys-color-on-tertiary-container: #ffd9e3;
+  --md-sys-color-tertiary-fixed: #ffd9e3;
+  --md-sys-color-tertiary-fixed-dim: #efb8c8;
+  --md-sys-color-on-tertiary-fixed: #31101d;
+  --md-sys-color-on-tertiary-fixed-variant: #633b48;
+  --md-sys-color-error: #ffb4ab;
+  --md-sys-color-on-error: #690005;
+  --md-sys-color-error-container: #93000a;
+  --md-sys-color-on-error-container: #ffdad6;
+  --md-sys-color-success: #96d783;
+  --md-sys-color-on-success: #013a00;
+  --md-sys-color-success-container: #16520e;
+  --md-sys-color-on-success-container: #b1f49d;
+  --md-sys-color-warning: #ffba30;
+  --md-sys-color-on-warning: #422c00;
+  --md-sys-color-warning-container: #5f4100;
+  --md-sys-color-on-warning-container: #ffdeab;
+  --md-sys-color-info: #cbc2db;
+  --md-sys-color-on-info: #332d41;
+  --md-sys-color-info-container: #4a4458;
+  --md-sys-color-on-info-container: #e8def8;
+  --md-sys-color-background: #141316;
+  --md-sys-color-on-background: #e6e1e6;
+  --md-sys-color-surface: #141316;
+  --md-sys-color-on-surface: #e6e1e6;
+  --md-sys-color-surface-variant: #49454e;
+  --md-sys-color-on-surface-variant: #cac4cf;
+  --md-sys-color-surface-dim: #141316;
+  --md-sys-color-surface-bright: #3a383c;
+  --md-sys-color-surface-container-lowest: #0f0e11;
+  --md-sys-color-surface-container-low: #1c1b1e;
+  --md-sys-color-surface-container: #201f22;
+  --md-sys-color-surface-container-high: #2b292d;
+  --md-sys-color-surface-container-highest: #363438;
+  --md-sys-color-outline: #948f99;
+  --md-sys-color-outline-variant: #49454e;
+  --md-sys-color-inverse-surface: #e6e1e6;
+  --md-sys-color-inverse-on-surface: #313033;
+  --md-sys-color-inverse-primary: #6750a4;
+  --md-sys-color-surface-tint: #cfbcff;
+  --md-sys-color-scrim: #000000;
+  --md-sys-color-shadow: #000000;
+}
+
+/* Respect explicit light selection even if the OS prefers dark. */
+@media (prefers-color-scheme: dark) {
+  html:not([data-theme='light']):not([data-theme='dark']) {
+    --md-sys-color-primary: #cfbcff;
+    --md-sys-color-on-primary: #381e72;
+    --md-sys-color-primary-container: #4f378a;
+    --md-sys-color-on-primary-container: #e9ddff;
+    --md-sys-color-primary-fixed: #e9ddff;
+    --md-sys-color-primary-fixed-dim: #cfbcff;
+    --md-sys-color-on-primary-fixed: #22005d;
+    --md-sys-color-on-primary-fixed-variant: #4f378a;
+    --md-sys-color-secondary: #cbc2db;
+    --md-sys-color-on-secondary: #332d41;
+    --md-sys-color-secondary-container: #4a4458;
+    --md-sys-color-on-secondary-container: #e8def8;
+    --md-sys-color-secondary-fixed: #e8def8;
+    --md-sys-color-secondary-fixed-dim: #cbc2db;
+    --md-sys-color-on-secondary-fixed: #1e192b;
+    --md-sys-color-on-secondary-fixed-variant: #4a4458;
+    --md-sys-color-tertiary: #efb8c8;
+    --md-sys-color-on-tertiary: #4a2532;
+    --md-sys-color-tertiary-container: #633b48;
+    --md-sys-color-on-tertiary-container: #ffd9e3;
+    --md-sys-color-tertiary-fixed: #ffd9e3;
+    --md-sys-color-tertiary-fixed-dim: #efb8c8;
+    --md-sys-color-on-tertiary-fixed: #31101d;
+    --md-sys-color-on-tertiary-fixed-variant: #633b48;
+    --md-sys-color-error: #ffb4ab;
+    --md-sys-color-on-error: #690005;
+    --md-sys-color-error-container: #93000a;
+    --md-sys-color-on-error-container: #ffdad6;
+    --md-sys-color-success: #96d783;
+    --md-sys-color-on-success: #013a00;
+    --md-sys-color-success-container: #16520e;
+    --md-sys-color-on-success-container: #b1f49d;
+    --md-sys-color-warning: #ffba30;
+    --md-sys-color-on-warning: #422c00;
+    --md-sys-color-warning-container: #5f4100;
+    --md-sys-color-on-warning-container: #ffdeab;
+    --md-sys-color-info: #cbc2db;
+    --md-sys-color-on-info: #332d41;
+    --md-sys-color-info-container: #4a4458;
+    --md-sys-color-on-info-container: #e8def8;
+    --md-sys-color-background: #141316;
+    --md-sys-color-on-background: #e6e1e6;
+    --md-sys-color-surface: #141316;
+    --md-sys-color-on-surface: #e6e1e6;
+    --md-sys-color-surface-variant: #49454e;
+    --md-sys-color-on-surface-variant: #cac4cf;
+    --md-sys-color-surface-dim: #141316;
+    --md-sys-color-surface-bright: #3a383c;
+    --md-sys-color-surface-container-lowest: #0f0e11;
+    --md-sys-color-surface-container-low: #1c1b1e;
+    --md-sys-color-surface-container: #201f22;
+    --md-sys-color-surface-container-high: #2b292d;
+    --md-sys-color-surface-container-highest: #363438;
+    --md-sys-color-outline: #948f99;
+    --md-sys-color-outline-variant: #49454e;
+    --md-sys-color-inverse-surface: #e6e1e6;
+    --md-sys-color-inverse-on-surface: #313033;
+    --md-sys-color-inverse-primary: #6750a4;
+    --md-sys-color-surface-tint: #cfbcff;
+    --md-sys-color-scrim: #000000;
+    --md-sys-color-shadow: #000000;
+  }
+}

frontend/PWA/src/theme/motion.ts

@@ -1,12 +1,18 @@
-// Motion tokens (DESIGN_SYSTEM §4). Durations are tokens; never inline a ms value.
+// Motion tokens — Material 3 Expressive.
 // Every animation short-circuits to instant / short cross-fade under reduced-motion.
+//
+// NOTE: all the legacy export NAMES (dur/stagger/easing/ease/sheetSpring/sec/motion)
+// are KEPT ALIVE so consuming files (PageTransition, AppButton, LedgerList, Money,
+// PagedList, RouteSection, StickyHeader/ActionBar/Sheet via theme.custom.motion)
+// keep compiling. New M3 spring specs are ADDED alongside.
 
+// ---- Legacy duration tokens (kept) — M3 md.sys.motion.duration aligned ----
 export const dur = {
   instant: 0,
-  fast: 120,
-  base: 200,
-  page: 280,
-  sheet: 320,
+  fast: 120, // ~short3
+  base: 200, // short4
+  page: 280, // medium2-ish
+  sheet: 320, // medium3
   countup: 700,
   success: 600,
 } as const;
@@ -16,24 +22,66 @@ export const stagger = {
   card: 60, // dashboard metric/chart cards
 } as const;
 
-// Easing (CSS cubic-bezier strings; Framer-compatible arrays below).
+// ---- Easing (CSS cubic-bezier strings) — kept names, M3 curves --------------
 export const easing = {
-  fast: 'cubic-bezier(0,0,0.2,1)', // easeOut
-  base: 'cubic-bezier(.2,.0,.2,1)',
-  page: 'cubic-bezier(.2,.0,0,1)',
+  fast: 'cubic-bezier(0,0,0.2,1)', // standard-decelerate (easeOut)
+  base: 'cubic-bezier(0.2,0,0,1)', // M3 emphasized
+  page: 'cubic-bezier(0.2,0,0,1)', // M3 emphasized
+} as const;
+
+// M3 named easing set (additive — for new components).
+export const m3Easing = {
+  standard: 'cubic-bezier(0.2,0,0,1)',
+  standardAccelerate: 'cubic-bezier(0.3,0,1,1)',
+  standardDecelerate: 'cubic-bezier(0,0,0,1)',
+  emphasized: 'cubic-bezier(0.2,0,0,1)',
+  emphasizedAccelerate: 'cubic-bezier(0.3,0,0.8,0.15)',
+  emphasizedDecelerate: 'cubic-bezier(0.05,0.7,0.1,1)',
 } as const;
 
 export const ease = {
   fast: [0, 0, 0.2, 1] as [number, number, number, number],
-  base: [0.2, 0, 0.2, 1] as [number, number, number, number],
+  base: [0.2, 0, 0, 1] as [number, number, number, number], // emphasized
   page: [0.2, 0, 0, 1] as [number, number, number, number],
 } as const;
 
-// Bottom-sheet spring (DESIGN_SYSTEM §4.1).
+// ---- M3 Expressive spring specs (6 = 2 categories x 3 speeds) ---------------
+// Spatial = position/size/rotation/corner radius (bounce allowed).
+// Effects = color/opacity/elevation (no overshoot, damping ~1).
+export const spring = {
+  spatialFast: { type: 'spring', damping: 0.6, stiffness: 800 },
+  spatialDefault: { type: 'spring', damping: 0.8, stiffness: 380 },
+  spatialSlow: { type: 'spring', damping: 0.8, stiffness: 200 },
+  effectsFast: { type: 'spring', damping: 1.0, stiffness: 3800 },
+  effectsDefault: { type: 'spring', damping: 1.0, stiffness: 1600 },
+  effectsSlow: { type: 'spring', damping: 1.0, stiffness: 800 },
+} as const;
+
+// Bottom-sheet spring — kept name; now points at the M3 spatial-default feel.
 export const sheetSpring = { type: 'spring', damping: 30, stiffness: 320 } as const;
 
+// ---- State-layer opacities (M3 md.sys.state.*) ------------------------------
+export const stateLayer = {
+  hover: 0.08,
+  focus: 0.1,
+  pressed: 0.1,
+  dragged: 0.16,
+  disabledContent: 0.38,
+  disabledContainer: 0.12,
+} as const;
+
 // Seconds helper for Framer (which takes seconds, not ms).
 export const sec = (ms: number) => ms / 1000;
 
-export const motion = { dur, stagger, easing, ease, sheetSpring, sec } as const;
+export const motion = {
+  dur,
+  stagger,
+  easing,
+  m3Easing,
+  ease,
+  spring,
+  sheetSpring,
+  stateLayer,
+  sec,
+} as const;
 export type MotionTokens = typeof motion;

frontend/PWA/src/theme/palette.ts

@@ -1,40 +1,120 @@
-// MilkWay LOCKED palette — light v1. Solid, no neon, not monochrome.
-// Components must read color from the theme, never hardcode a hex (dark-swap ready).
-
-export const palette = {
-  mode: 'light',
-  primary: { main: '#1E6FE0', contrastText: '#FFFFFF' },
-  secondary: { main: '#2E9E5B', contrastText: '#FFFFFF' },
-  success: { main: '#16A34A', contrastText: '#FFFFFF' },
-  warning: { main: '#D97706', contrastText: '#FFFFFF' },
-  error: { main: '#DC2626', contrastText: '#FFFFFF' },
-  info: { main: '#0EA5E9', contrastText: '#FFFFFF' },
-  background: { default: '#F6F8FB', paper: '#FFFFFF' },
-  divider: '#E5E9F0',
-  text: { primary: '#0F172A', secondary: '#64748B', disabled: '#94A3B8' },
-} as const;
-
-// Custom tokens surfaced via module augmentation (theme.palette.accent, theme.custom.*).
-export const customTokens = {
-  // amber: DARK text for AA contrast (never white on amber).
-  accent: { main: '#F59E0B', contrastText: '#0F172A' },
-  border: '#E5E9F0',
-  surface: '#FFFFFF',
-  // Shift section tints (route morning/evening). Morning reuses the amber accent;
-  // evening is an indigo tint kept here so components read it from the theme.
-  eveningTint: '#4F46E5',
-  // Single source of semantic status -> color. ONLY StatusChip reads this.
-  status: {
-    paid: '#16A34A',
-    delivered: '#16A34A',
-    active: '#16A34A',
-    partial: '#D97706',
-    hold: '#D97706',
-    unpaid: '#DC2626',
-    skipped: '#64748B',
-    inactive: '#64748B',
-    pending: '#64748B',
-  },
-} as const;
+// MilkWay palette — Material 3 (seed #6750A4), light + dark.
+// Values come from src/theme/m3/roles.ts (build-time generated from the seed).
+// Components must read color from the theme, never hardcode a hex.
+//
+// NOTE on token NAMES: every name the ~39 consuming files already use
+// (palette.accent, customTokens.{border,surface,eveningTint,status}) is kept
+// alive here and MAPPED onto an M3 role, so no component file needs editing.
+
+import { m3Roles, type M3RoleSet } from './m3/roles';
+
+export type PaletteMode = 'light' | 'dark';
+
+// ---- MUI core palette built from M3 roles -------------------------------
+// primary.main  = role `primary`          (+ container roles exposed below)
+// secondary.main= role `secondary`
+// error/warning/success/info = role <name> (+ matching containers)
+// background.default = role `surface`      (M3 page bg)
+// background.paper   = role `surface-container-low` (default card tier)
+// divider            = role `outline-variant`
+// text.primary       = role `on-surface`
+// text.secondary     = role `on-surface-variant`
+// text.disabled      = on-surface @ 38% (M3 disabled content) — kept as hex+alpha
+export function buildPalette(mode: PaletteMode) {
+  const r: M3RoleSet = m3Roles[mode];
+  return {
+    mode,
+    primary: {
+      main: r['primary'],
+      contrastText: r['on-primary'],
+      // M3 container pair, surfaced via augmentation (Palette.primary.container/onContainer).
+      container: r['primary-container'],
+      onContainer: r['on-primary-container'],
+    },
+    secondary: {
+      main: r['secondary'],
+      contrastText: r['on-secondary'],
+      container: r['secondary-container'],
+      onContainer: r['on-secondary-container'],
+    },
+    success: {
+      main: r['success'],
+      contrastText: r['on-success'],
+      container: r['success-container'],
+      onContainer: r['on-success-container'],
+    },
+    warning: {
+      main: r['warning'],
+      contrastText: r['on-warning'],
+      container: r['warning-container'],
+      onContainer: r['on-warning-container'],
+    },
+    error: {
+      main: r['error'],
+      contrastText: r['on-error'],
+      container: r['error-container'],
+      onContainer: r['on-error-container'],
+    },
+    info: {
+      main: r['info'],
+      contrastText: r['on-info'],
+      container: r['info-container'],
+      onContainer: r['on-info-container'],
+    },
+    background: {
+      default: r['surface'],
+      paper: r['surface-container-low'],
+    },
+    divider: r['outline-variant'],
+    text: {
+      primary: r['on-surface'],
+      secondary: r['on-surface-variant'],
+      disabled: alpha(r['on-surface'], 0.38),
+    },
+  } as const;
+}
+
+// Light palette kept as the named export the rest of the codebase imports.
+export const palette = buildPalette('light');
+
+// ---- Custom tokens (SAME SHAPE as before, re-mapped onto M3 roles) -------
+// accent       -> tertiary (the M3 "expressive accent")
+// border       -> outline-variant
+// surface      -> surface-container-low (the card surface)
+// eveningTint  -> secondary (evening route tint; re-tones with the palette)
+// status.*     -> success / warning / error / info, derived from semantic roles
+//                 so chips re-tone with the seed (kept as flat hex — StatusChip
+//                 concatenates `${hex}1A`).
+export function buildCustomTokens(mode: PaletteMode) {
+  const r: M3RoleSet = m3Roles[mode];
+  return {
+    accent: { main: r['tertiary'], contrastText: r['on-tertiary'] },
+    border: r['outline-variant'],
+    surface: r['surface-container-low'],
+    eveningTint: r['secondary'],
+    status: {
+      paid: r['success'],
+      delivered: r['success'],
+      active: r['success'],
+      partial: r['warning'],
+      hold: r['warning'],
+      unpaid: r['error'],
+      skipped: r['on-surface-variant'],
+      inactive: r['on-surface-variant'],
+      pending: r['on-surface-variant'],
+    },
+  } as const;
+}
+
+export const customTokens = buildCustomTokens('light');
 
 export type StatusKey = keyof typeof customTokens.status;
+
+// Tiny hex+alpha helper (build-time, no runtime palette cost). Accepts #rrggbb.
+function alpha(hex: string, a: number): string {
+  const h = hex.replace('#', '');
+  const r = parseInt(h.slice(0, 2), 16);
+  const g = parseInt(h.slice(2, 4), 16);
+  const b = parseInt(h.slice(4, 6), 16);
+  return `rgba(${r}, ${g}, ${b}, ${a})`;
+}

frontend/PWA/src/theme/theme.d.ts

@@ -1,12 +1,40 @@
 import '@mui/material/styles';
 import type { customTokens } from './palette';
 import type { motion as motionTokens } from './motion';
+import type { M3RoleSet } from './m3/roles';
 
 type AccentColor = {
   main: string;
   contrastText: string;
 };
 
+// M3 container pair added to the standard MUI color tokens.
+type M3ColorExtra = {
+  container: string;
+  onContainer: string;
+};
+
+type CustomTokens = {
+  // legacy names (kept alive, mapped to M3 roles)
+  border: string;
+  surface: string;
+  eveningTint: string;
+  status: typeof customTokens.status;
+  radius: { xs: number; sm: number; md: number; lg: number; xl: number; pill: number };
+  motion: typeof motionTokens;
+  // NEW M3 additions
+  m3: M3RoleSet;
+  surfaces: {
+    dim: string;
+    bright: string;
+    containerLowest: string;
+    containerLow: string;
+    container: string;
+    containerHigh: string;
+    containerHighest: string;
+  };
+};
+
 declare module '@mui/material/styles' {
   interface Palette {
     accent: AccentColor;
@@ -15,25 +43,51 @@ declare module '@mui/material/styles' {
     accent?: AccentColor;
   }
 
+  // Expose M3 container roles on the standard palette color objects.
+  interface PaletteColor extends M3ColorExtra {}
+  interface SimplePaletteColorOptions extends Partial<M3ColorExtra> {}
+
   interface Theme {
-    custom: {
-      border: string;
-      surface: string;
-      eveningTint: string;
-      status: typeof customTokens.status;
-      radius: { sm: number; md: number; lg: number; pill: number };
-      motion: typeof motionTokens;
-    };
+    custom: CustomTokens;
   }
   interface ThemeOptions {
-    custom?: {
-      border: string;
-      surface: string;
-      eveningTint: string;
-      status: typeof customTokens.status;
-      radius: { sm: number; md: number; lg: number; pill: number };
-      motion: typeof motionTokens;
-    };
+    custom?: CustomTokens;
+  }
+
+  // ---- M3 role typography variants (added in index.ts) -------------------
+  interface TypographyVariants {
+    displayLarge: React.CSSProperties;
+    displayMedium: React.CSSProperties;
+    displaySmall: React.CSSProperties;
+    headlineLarge: React.CSSProperties;
+    headlineMedium: React.CSSProperties;
+    headlineSmall: React.CSSProperties;
+    titleLarge: React.CSSProperties;
+    titleMedium: React.CSSProperties;
+    titleSmall: React.CSSProperties;
+    bodyLarge: React.CSSProperties;
+    bodyMedium: React.CSSProperties;
+    bodySmall: React.CSSProperties;
+    labelLarge: React.CSSProperties;
+    labelMedium: React.CSSProperties;
+    labelSmall: React.CSSProperties;
+  }
+  interface TypographyVariantsOptions {
+    displayLarge?: React.CSSProperties;
+    displayMedium?: React.CSSProperties;
+    displaySmall?: React.CSSProperties;
+    headlineLarge?: React.CSSProperties;
+    headlineMedium?: React.CSSProperties;
+    headlineSmall?: React.CSSProperties;
+    titleLarge?: React.CSSProperties;
+    titleMedium?: React.CSSProperties;
+    titleSmall?: React.CSSProperties;
+    bodyLarge?: React.CSSProperties;
+    bodyMedium?: React.CSSProperties;
+    bodySmall?: React.CSSProperties;
+    labelLarge?: React.CSSProperties;
+    labelMedium?: React.CSSProperties;
+    labelSmall?: React.CSSProperties;
   }
 }
 
@@ -48,3 +102,24 @@ declare module '@mui/material/SvgIcon' {
     accent: true;
   }
 }
+
+// Allow variant="displayLarge" etc. on <Typography>.
+declare module '@mui/material/Typography' {
+  interface TypographyPropsVariantOverrides {
+    displayLarge: true;
+    displayMedium: true;
+    displaySmall: true;
+    headlineLarge: true;
+    headlineMedium: true;
+    headlineSmall: true;
+    titleLarge: true;
+    titleMedium: true;
+    titleSmall: true;
+    bodyLarge: true;
+    bodyMedium: true;
+    bodySmall: true;
+    labelLarge: true;
+    labelMedium: true;
+    labelSmall: true;
+  }
+}

frontend/PWA/tsconfig.app.tsbuildinfo

@@ -1 +1 @@
-{"root":["./src/approutes.tsx","./src/main.tsx","./src/vite-env.d.ts","./src/api/apierror.ts","./src/api/client.ts","./src/api/endpoints.ts","./src/api/index.ts","./src/api/keys.ts","./src/api/types.ts","./src/api/hooks/index.ts","./src/api/hooks/useanalytics.ts","./src/api/hooks/useauth.ts","./src/api/hooks/usebills.ts","./src/api/hooks/usecustomerledger.ts","./src/api/hooks/usecustomers.ts","./src/api/hooks/usepayments.ts","./src/api/hooks/useprices.ts","./src/api/hooks/useproducts.ts","./src/api/hooks/useroute.ts","./src/api/hooks/usesettings.ts","./src/api/hooks/usesubscriptions.ts","./src/api/hooks/useusers.ts","./src/app/appshell.tsx","./src/app/bottomnav.tsx","./src/app/fab.tsx","./src/app/pagetransition.tsx","./src/app/stickyactionbar.tsx","./src/app/stickyheader.tsx","./src/app/index.ts","./src/app/navconfig.tsx","./src/app/queryclient.ts","./src/auth/authstore.ts","./src/auth/permissions.ts","./src/components/index.ts","./src/components/buttons/appbutton.tsx","./src/components/buttons/iconaction.tsx","./src/components/charts/barchart.tsx","./src/components/charts/chartframe.tsx","./src/components/charts/donutchart.tsx","./src/components/charts/metriccard.tsx","./src/components/charts/trendchart.tsx","./src/components/domain/billcard.tsx","./src/components/domain/billlinestable.tsx","./src/components/domain/customercard.tsx","./src/components/domain/deliveryrow.tsx","./src/components/domain/ledgerlist.tsx","./src/components/domain/paymentrow.tsx","./src/components/domain/productcard.tsx","./src/components/domain/qrviewer.tsx","./src/components/domain/subscriptionrow.tsx","./src/components/domain/whatsappsharebutton.tsx","./src/components/domain/types.ts","./src/components/feedback/emptystate.tsx","./src/components/feedback/errorboundary.tsx","./src/components/feedback/errorstate.tsx","./src/components/feedback/skeleton.tsx","./src/components/feedback/spinner.tsx","./src/components/feedback/toastprovider.tsx","./src/components/fields/datefield.tsx","./src/components/fields/keyboardawarefield.tsx","./src/components/fields/numberfield.tsx","./src/components/fields/phonefield.tsx","./src/components/fields/qtystepper.tsx","./src/components/fields/searchbar.tsx","./src/components/fields/selectfield.tsx","./src/components/fields/statustoggle.tsx","./src/components/fields/switchfield.tsx","./src/components/fields/textfield.tsx","./src/components/format/datelabel.tsx","./src/components/format/money.tsx","./src/components/format/qty.tsx","./src/components/gating/permissiongate.tsx","./src/components/gating/rolegate.tsx","./src/components/lists/pagedlist.tsx","./src/components/lists/usepulltorefresh.ts","./src/components/nav/datestrip.tsx","./src/components/nav/pagetabs.tsx","./src/components/nav/stickytotalbar.tsx","./src/components/overlays/bottomsheet.tsx","./src/components/overlays/confirmdialog.tsx","./src/components/overlays/modal.tsx","./src/components/status/statuschip.tsx","./src/features/admin/settingspage.tsx","./src/features/admin/staffpage.tsx","./src/features/admin/routes.tsx","./src/features/admin/useadminnav.ts","./src/features/admin/components/createemployeesheet.tsx","./src/features/admin/components/holidayssection.tsx","./src/features/admin/components/permissionlabels.ts","./src/features/admin/components/permissionssheet.tsx","./src/features/admin/components/staffrow.tsx","./src/features/analytics/dashboardpage.tsx","./src/features/analytics/daterangesheet.tsx","./src/features/analytics/rangecontrol.tsx","./src/features/analytics/reportspage.tsx","./src/features/analytics/unitqtychips.tsx","./src/features/analytics/charts.tsx","./src/features/analytics/controls.tsx","./src/features/analytics/index.ts","./src/features/analytics/routes.tsx","./src/features/analytics/unitqty.ts","./src/features/analytics/unittypes.ts","./src/features/analytics/usedaterange.ts","./src/features/auth/routes.tsx","./src/features/auth/pages/loginpage.tsx","./src/features/billing/billdetailpage.tsx","./src/features/billing/billingpage.tsx","./src/features/billing/index.ts","./src/features/billing/routes.tsx","./src/features/billing/components/adjustmentsheet.tsx","./src/features/billing/components/billlistcard.tsx","./src/features/billing/components/billslisttab.tsx","./src/features/billing/components/generatetab.tsx","./src/features/billing/components/recordpaymentsheet.tsx","./src/features/billing/components/statuschangesheet.tsx","./src/features/billing/hooks/usebillingshell.ts","./src/features/billing/hooks/usegeneratebills.ts","./src/features/billing/hooks/usegeneratepreview.ts","./src/features/billing/lib/billlineunit.ts","./src/features/catalog/routes.tsx","./src/features/catalog/unit.ts","./src/features/catalog/usecatalognav.ts","./src/features/catalog/components/addpricesheet.tsx","./src/features/catalog/components/pricerow.tsx","./src/features/catalog/components/productformsheet.tsx","./src/features/catalog/components/resolveratepreview.tsx","./src/features/catalog/pages/productpricespage.tsx","./src/features/catalog/pages/productslistpage.tsx","./src/features/customers/routes.tsx","./src/features/customers/components/consumptionbreakdown.tsx","./src/features/customers/components/customerformsheet.tsx","./src/features/customers/components/subscriptionformsheet.tsx","./src/features/customers/hooks/useappnav.ts","./src/features/customers/hooks/usecustomeroutstanding.ts","./src/features/customers/lib/format.ts","./src/features/customers/lib/units.ts","./src/features/customers/pages/customerdetailpage.tsx","./src/features/customers/pages/customerslistpage.tsx","./src/features/payments/index.ts","./src/features/payments/routes.tsx","./src/features/payments/components/paymentfilterssheet.tsx","./src/features/payments/components/recordpaymentsheet.tsx","./src/features/payments/hooks/usepaymentsfeature.ts","./src/features/payments/pages/paymentslistpage.tsx","./src/features/route/routes.tsx","./src/features/route/components/recorddeliverysheet.tsx","./src/features/route/components/routesection.tsx","./src/features/route/components/submitconfirmsheet.tsx","./src/features/route/hooks/useonline.ts","./src/features/route/hooks/useroutedraft.ts","./src/features/route/pages/routepage.tsx","./src/features/superadmin/adminspage.tsx","./src/features/superadmin/orgspage.tsx","./src/features/superadmin/index.ts","./src/features/superadmin/routes.tsx","./src/features/superadmin/components/adminrow.tsx","./src/features/superadmin/components/createadminsheet.tsx","./src/features/superadmin/components/orgcard.tsx","./src/features/superadmin/components/orgpickersheet.tsx","./src/features/superadmin/hooks/useorgpicker.ts","./src/features/superadmin/hooks/usesuperadminnav.ts","./src/features/superadmin/lib/seedorg.ts","./src/hooks/usekeyboardaware.ts","./src/hooks/usereducedmotion.ts","./src/lib/env.ts","./src/lib/formerrors.ts","./src/lib/unit.ts","./src/routes/homeplaceholder.tsx","./src/routes/morepage.tsx","./src/routes/preview.tsx","./src/routes/lazypage.tsx","./src/theme/index.ts","./src/theme/motion.ts","./src/theme/palette.ts","./src/theme/theme.d.ts"],"version":"5.9.3"}
+{"root":["./src/approutes.tsx","./src/main.tsx","./src/vite-env.d.ts","./src/api/apierror.ts","./src/api/client.ts","./src/api/endpoints.ts","./src/api/index.ts","./src/api/keys.ts","./src/api/types.ts","./src/api/hooks/index.ts","./src/api/hooks/useanalytics.ts","./src/api/hooks/useauth.ts","./src/api/hooks/usebills.ts","./src/api/hooks/usecustomerledger.ts","./src/api/hooks/usecustomers.ts","./src/api/hooks/usepayments.ts","./src/api/hooks/useprices.ts","./src/api/hooks/useproducts.ts","./src/api/hooks/useroute.ts","./src/api/hooks/usesettings.ts","./src/api/hooks/usesubscriptions.ts","./src/api/hooks/useusers.ts","./src/app/appshell.tsx","./src/app/bottomnav.tsx","./src/app/fab.tsx","./src/app/pagetransition.tsx","./src/app/stickyactionbar.tsx","./src/app/stickyheader.tsx","./src/app/index.ts","./src/app/navconfig.tsx","./src/app/queryclient.ts","./src/auth/authstore.ts","./src/auth/permissions.ts","./src/components/index.ts","./src/components/buttons/appbutton.tsx","./src/components/buttons/iconaction.tsx","./src/components/charts/barchart.tsx","./src/components/charts/chartframe.tsx","./src/components/charts/donutchart.tsx","./src/components/charts/metriccard.tsx","./src/components/charts/trendchart.tsx","./src/components/domain/billcard.tsx","./src/components/domain/billlinestable.tsx","./src/components/domain/customercard.tsx","./src/components/domain/deliveryrow.tsx","./src/components/domain/ledgerlist.tsx","./src/components/domain/paymentrow.tsx","./src/components/domain/productcard.tsx","./src/components/domain/qrviewer.tsx","./src/components/domain/subscriptionrow.tsx","./src/components/domain/whatsappsharebutton.tsx","./src/components/domain/types.ts","./src/components/feedback/emptystate.tsx","./src/components/feedback/errorboundary.tsx","./src/components/feedback/errorstate.tsx","./src/components/feedback/skeleton.tsx","./src/components/feedback/spinner.tsx","./src/components/feedback/toastprovider.tsx","./src/components/fields/datefield.tsx","./src/components/fields/keyboardawarefield.tsx","./src/components/fields/numberfield.tsx","./src/components/fields/phonefield.tsx","./src/components/fields/qtystepper.tsx","./src/components/fields/searchbar.tsx","./src/components/fields/selectfield.tsx","./src/components/fields/statustoggle.tsx","./src/components/fields/switchfield.tsx","./src/components/fields/textfield.tsx","./src/components/format/datelabel.tsx","./src/components/format/money.tsx","./src/components/format/qty.tsx","./src/components/gating/permissiongate.tsx","./src/components/gating/rolegate.tsx","./src/components/lists/pagedlist.tsx","./src/components/lists/usepulltorefresh.ts","./src/components/nav/datestrip.tsx","./src/components/nav/pagetabs.tsx","./src/components/nav/stickytotalbar.tsx","./src/components/overlays/bottomsheet.tsx","./src/components/overlays/confirmdialog.tsx","./src/components/overlays/modal.tsx","./src/components/status/statuschip.tsx","./src/features/admin/settingspage.tsx","./src/features/admin/staffpage.tsx","./src/features/admin/routes.tsx","./src/features/admin/useadminnav.ts","./src/features/admin/components/createemployeesheet.tsx","./src/features/admin/components/holidayssection.tsx","./src/features/admin/components/permissionlabels.ts","./src/features/admin/components/permissionssheet.tsx","./src/features/admin/components/staffrow.tsx","./src/features/analytics/dashboardpage.tsx","./src/features/analytics/daterangesheet.tsx","./src/features/analytics/rangecontrol.tsx","./src/features/analytics/reportspage.tsx","./src/features/analytics/unitqtychips.tsx","./src/features/analytics/charts.tsx","./src/features/analytics/controls.tsx","./src/features/analytics/index.ts","./src/features/analytics/routes.tsx","./src/features/analytics/unitqty.ts","./src/features/analytics/unittypes.ts","./src/features/analytics/usedaterange.ts","./src/features/auth/routes.tsx","./src/features/auth/pages/loginpage.tsx","./src/features/billing/billdetailpage.tsx","./src/features/billing/billingpage.tsx","./src/features/billing/index.ts","./src/features/billing/routes.tsx","./src/features/billing/components/adjustmentsheet.tsx","./src/features/billing/components/billlistcard.tsx","./src/features/billing/components/billslisttab.tsx","./src/features/billing/components/generatetab.tsx","./src/features/billing/components/recordpaymentsheet.tsx","./src/features/billing/components/statuschangesheet.tsx","./src/features/billing/hooks/usebillingshell.ts","./src/features/billing/hooks/usegeneratebills.ts","./src/features/billing/hooks/usegeneratepreview.ts","./src/features/billing/lib/billlineunit.ts","./src/features/catalog/routes.tsx","./src/features/catalog/unit.ts","./src/features/catalog/usecatalognav.ts","./src/features/catalog/components/addpricesheet.tsx","./src/features/catalog/components/pricerow.tsx","./src/features/catalog/components/productformsheet.tsx","./src/features/catalog/components/resolveratepreview.tsx","./src/features/catalog/pages/productpricespage.tsx","./src/features/catalog/pages/productslistpage.tsx","./src/features/customers/routes.tsx","./src/features/customers/components/consumptionbreakdown.tsx","./src/features/customers/components/customerformsheet.tsx","./src/features/customers/components/subscriptionformsheet.tsx","./src/features/customers/hooks/useappnav.ts","./src/features/customers/hooks/usecustomeroutstanding.ts","./src/features/customers/lib/format.ts","./src/features/customers/lib/units.ts","./src/features/customers/pages/customerdetailpage.tsx","./src/features/customers/pages/customerslistpage.tsx","./src/features/payments/index.ts","./src/features/payments/routes.tsx","./src/features/payments/components/paymentfilterssheet.tsx","./src/features/payments/components/recordpaymentsheet.tsx","./src/features/payments/hooks/usepaymentsfeature.ts","./src/features/payments/pages/paymentslistpage.tsx","./src/features/route/routes.tsx","./src/features/route/components/recorddeliverysheet.tsx","./src/features/route/components/routesection.tsx","./src/features/route/components/submitconfirmsheet.tsx","./src/features/route/hooks/useonline.ts","./src/features/route/hooks/useroutedraft.ts","./src/features/route/pages/routepage.tsx","./src/features/superadmin/adminspage.tsx","./src/features/superadmin/orgspage.tsx","./src/features/superadmin/index.ts","./src/features/superadmin/routes.tsx","./src/features/superadmin/components/adminrow.tsx","./src/features/superadmin/components/createadminsheet.tsx","./src/features/superadmin/components/orgcard.tsx","./src/features/superadmin/components/orgpickersheet.tsx","./src/features/superadmin/hooks/useorgpicker.ts","./src/features/superadmin/hooks/usesuperadminnav.ts","./src/features/superadmin/lib/seedorg.ts","./src/hooks/usekeyboardaware.ts","./src/hooks/usereducedmotion.ts","./src/lib/env.ts","./src/lib/formerrors.ts","./src/lib/unit.ts","./src/routes/homeplaceholder.tsx","./src/routes/morepage.tsx","./src/routes/preview.tsx","./src/routes/lazypage.tsx","./src/theme/thememodeprovider.tsx","./src/theme/index.ts","./src/theme/motion.ts","./src/theme/palette.ts","./src/theme/theme.d.ts","./src/theme/m3/generate.ts","./src/theme/m3/roles.ts"],"version":"5.9.3"}