Capstone: TrackFlow Ops Dashboard

Foundation: rules, skeleton, tokens

New repo. GEMINI.md rules: the three-layer separation above; semantic HTML (table for the board, button for actions — never clickable divs); all colors/spacing via CSS custom properties in :root; every interactive element keyboard-reachable; loading/error/empty are three distinct UI states, never conflated. Then generate the skeleton from a spec-comment in index.html (Move 1: type an HTML comment describing the regions — header with search + refresh, SLA banner, filter bar, order table, drawer <aside> — pause for ghost text, accept section by section) and the token sheet in style.css the same way.

Logic and data: testable before visible

Build logic.js function-by-function with spec-comments. The heart is SLA classification — spec it precisely:

// classifySla(order, nowIso) -> "ON_TIME" | "AT_RISK" | "BREACHED" | "MET"
// MET: order reached SHIPPED/DELIVERED on or before promised_ship_date.
// BREACHED: not shipped and now is past end of promised_ship_date.
// AT_RISK: not shipped and promised_ship_date is today or tomorrow.
// ON_TIME: everything else. Treat dates as YYYY-MM-DD strings in local time.
// Pure function: never call Date.now() — now arrives as a parameter.

Generate tests (Move 3: select classifySla → right-click → Generate unit tests, then in chat demand "node:test suite for classifySla covering all four outcomes plus the boundary: promised date == today"), run node --test tests/ in the integrated terminal, and iterate. Then api.js: mockApi first (deterministic orders covering every state and SLA class — generate it headlessly with Gemini CLI like the other capstones), then liveApi with timeouts and typed errors ({kind: "network" | "http", status?}) so the UI can distinguish failure from emptiness.

PS> node --test tests/
✔ classifySla: MET when shipped on or before promised date
✔ classifySla: BREACHED when unshipped past promised date
✔ classifySla: AT_RISK when promised date is today (the boundary)
✔ classifySla: AT_RISK when promised date is tomorrow
✔ classifySla: ON_TIME otherwise
✔ filterOrders: state and customer filters combine (AND)
✔ filterOrders: empty criteria returns all orders
✔ sortOrders: promised date ascending, stable for ties
✔ formatEvent: ISO timestamp renders as local short form
ℹ tests 14 • suites 4 • pass 14 • fail 0 • duration_ms 92

Render: where you review with your eyes

Build app.js in chat-sized increments: render the board from mock data → wire filters/sort (calling logic.js) → SLA banner → drawer → auto-refresh with the "last updated" stamp. Then force the three async states and look at each: mock mode with empty data (empty state: "No orders match" + a clear-filters action), live mode with the API stopped (error state: "Can't reach TrackFlow — data may be stale" + retry), and a throttled network (loading state visible, UI not frozen). Use chat to fix what you see, feeding it evidence G03-style: paste the console error or describe the misbehavior precisely.

http://localhost:8000/?mode=mock
  -> board renders 12 orders · banner reads "⚠ 2 BREACHED · 3 AT RISK"
  -> "Last updated 14:02:11" stamp ticks on every refresh

EMPTY  (mock mode, filter to a customer with no orders)
  -> "No orders match your filters"  +  [Clear filters] button
  -> banner counts unchanged (they reflect ALL orders, not the filter)

ERROR  (live mode, TrackFlow server stopped)
  -> red strip: "Can't reach TrackFlow — data may be stale"  +  [Retry]
  -> previous orders stay visible, marked stale — NOT a blank table
  -> DevTools console: one handled error log, no uncaught exceptions

LOADING  (DevTools → Network → throttle to Slow 3G, press Refresh)
  -> skeleton rows or spinner visible; filters remain clickable;
     the "Last updated" stamp does NOT advance until data lands

Accessibility audit, then an agent-built feature

First the audit — Move 2, attaching both files as context (the +/paperclip control in the chat box, or keep both open in editor tabs): "Audit index.html + app.js for keyboard and screen-reader accessibility: tab order, focus management when the drawer opens/closes (focus moves in, Escape closes, focus returns to the row), aria-live for the SLA banner and 'last updated', missing labels. List concrete fixes." Apply and verify by unplugging your mouse — complete a full task (find a breached order, open its drawer, read tracking, close) with keys alone. Then the G06 ticket:

Add dark/light theme support:
1. All colors already flow through CSS custom properties — add a light
   theme as a [data-theme="light"] override block. Do NOT touch component CSS.
2. A theme toggle button in the header (aria-pressed, persists in localStorage,
   defaults to the user's prefers-color-scheme).
3. Both themes must keep WCAG AA contrast for state chips and the SLA
   banner — list the contrast ratios you chose in your plan.
Plan first.

KEYBOARD-ONLY TASK (mouse unplugged)
  Tab order: search → refresh → theme toggle → SLA banner → filters → first row
  Arrow/Tab to the breached row, press Enter
    -> drawer opens, focus lands on the drawer heading
  Tab through: line items → audit timeline → tracking events
  Press Esc
    -> drawer closes, focus RETURNS to the row you opened it from

THEME
  Click toggle -> <html data-theme="light">; aria-pressed flips to "true"
  DevTools console:  localStorage.getItem("theme")  ->  "light"
  Reload -> still light.  Clear localStorage + reload
    -> follows OS prefers-color-scheme
  State chips and SLA banner readable in BOTH themes (AA: ≥4.5:1)

Ship: review gate plus the eyes-on checklist

Push to GitHub; .gemini/styleguide.md must-flags: DOM access outside app.js, Date.now() inside logic.js, clickable non-button elements, catch-blocks that render errors as empty states, hardcoded colors bypassing tokens. Open the theme feature as a PR, process the review (G09 discipline). Final verification is manual and honest: the three async states, the keyboard-only task, both themes, and ?mode=mock vs live against your running TrackFlow API.