design-v3/iteration-2/00-ux-review.md

# Iteration 2: navigation, data display and interaction

2026-09-18. Builds on iteration 1 (`../screens/`, left unchanged for comparison).
Same Design System v3 tokens; the new components are in
`source/components.css`. Open **`screens/index.html`** first: it's the flow map,
with eight guided flows that deep-link into each state.

---

## 1. What was wrong with iteration 1

| # | Where | Problem | Why it matters | Iteration 2 fix |
|---|---|---|---|---|
| 1 | Nav, Dashboard | "Prints" and "All prints →" linked to `#`. Dead ends. | You lose trust in a nav item the first time it does nothing. | A real **Prints** page (history + attention queue, as on `dev`) |
| 2 | Filament → Edit | Edit navigated to a separate page | You lose your place, filter and scroll every time | **Detail panel** opens over the list; Esc/back returns you to where you were |
| 3 | Dashboard, Printers | A spool in "Running low" or an AMS slot wasn't clickable | The most natural next click went nowhere | Every spool, print and holder opens the same panel, on any page |
| 4 | Dashboard | Reported numbers but never said what to do | The kill criterion is **daily use**, so the home screen has to hand you today's jobs | **"Needs you"** queue, each item one click from its fix |
| 5 | Everywhere | Almost every value was an uppercase chip (status, provenance, warnings) | Nothing stands out when everything is loud, so a legend box was needed | Chip/label hierarchy (§5.1); provenance became quiet text with a tooltip |
| 6 | Filament table | Tare, source, gross, value, location and two actions in every row, 2–3 lines each | Too dense to scan 105 rows | **Stock / Weights** column sets; the full breakdown moves to the panel |
| 7 | All pages | No freshness, loading, empty or error state | The app polls every 10 s; stale data shown as live is the worst failure | "Live · updated 3s ago" in the header, an offline banner with the data's age, skeletons, empty states |
| 8 | Filament | "P1S · AMS 1 · **slot 2**" | **Invented.** The schema stores the holder, not the tray position | Holders show fill ("3 / 4") and contents; tray position listed under Future |
| 9 | Mobile | Nav squeezed into icon rows; no reachable primary action | Weighing happens at the shelf, on a phone | Bottom tab bar with badges, a floating **+** button, the panel as a full-screen sheet |
| 10 | Every page | A large proposal banner on top of every screen | Pushed content down; it read as part of the app | A small "Mockup" pill bottom-left, with the legend and demo controls inside |
| 11 | Printers | One card per section in three stacked sections | Two-thirds of the width empty; the lost printer was mid-page | Urgency order (lost → printing → idle) in one row, plus a "Jump to" strip |
| 12 | Printers ↔ Dashboard | "Open printer" landed at the top of the page | You had to find the right card yourself | `04-printers.html#printer=3` scrolls to that card and highlights it |

---

## 2. Navigation model

```
┌ Rail (desktop) / tab bar (phone) ─────────────────────────────┐
│ Dashboard · Filament · Prints [3] · Printers [1]              │  ← badges = work waiting
│ Manage: Lists · Labels [4] · Access (admin)                   │  ← kept on dev, not redesigned
└───────────────────────────────────────────────────────────────┘
Top bar on every page:  [ Search… ⌘K ]   ● Live · updated 3s ago   [◐]
```

- **Four destinations, ranked by how often they're used.** Manage items are
  second-tier and grouped separately. Access is labeled "admin".
- **Badges only for work waiting**: Prints = prints missing a spool or weight
  (amber); Printers = disconnected printers (red). No badge for totals, so a
  badge always means "go here".
- **One page header pattern**: title, a one-line summary with the key numbers,
  **one** primary button on the right, everything else under "More ▾".
- **Deep links for every state**, so browser Back, bookmarks and sharing all
  work:

| URL | Opens |
|---|---|
| `02-filament.html?f=low&q=black` | Filament, Low view, filtered |
| `…#spool=47` · `#spool=47&tab=weigh` · `&tab=edit&state=conflict` | Spool panel, on a tab, optionally in a demo state |
| `03-prints.html?tab=needs` · `#print=210` | Prints tab / print panel |
| `04-printers.html#printer=3` · `#load=p3-lite` | Scroll to printer / load a holder |
| `?palette=weigh%20black` | Palette open with a query (demo hook) |

---

## 3. Core flows (most frequent first)

| Flow | Steps in iteration 2 | Iteration 1 |
|---|---|---|
| **Morning check** | Dashboard → "Needs you" → Review 3 → **Use** suggestion ×2, type 1 weight | Not possible; no queue |
| **Attribute a print** | Prints › Needs attention: suggestion shown inline → **Use**. Or batch-select → one spool | Not designed |
| **Weigh a spool** | Row **⚖ Weigh**, or palette `weigh copper` → type reading → see before → after → Save | Open the form, find the weigh box, save the whole form |
| **Weigh several** | Filament › Low → **Start weighing** → **Save & weigh next** (j/k also steps) | One at a time, reopening the form each time |
| **Load a spool** | Printers → holder **+ Load** → filter stored spools → pick → Load | Not designed |
| **Move / unload** | Panel › Move: storage or any holder; full holders disabled with the reason | Only by typing a location |
| **Add a spool** | **+ Add spool** (header, FAB, palette) → panel with 5-part name preview | Separate page |
| **Handle a 409** | Panel › Edit: side-by-side you-opened / now / your-edit → reapply or discard | Same content, but on a separate page |
| **Tare unknown** | Tare unknown view → Weigh tab explains, offers spool type or weigh-empty | Only a hint under the form field |
| **Find anything** | `/` or `⌘K` → spools, prints, printers and actions in one list | Filament search only |

---

## 4. Interaction patterns

**Panel (drawer) vs page.** Use a page for a *collection* and a panel for *one
thing*. The panel sits on the right (520 px) and becomes a full-screen sheet
under 860 px. Tabs: Overview · Weigh · Move · Edit for spools; a single view for
prints, with the fix at the top when something is missing.
- Opens with the heading focused (or the tab's main input), traps Tab, and
  returns focus to the row that opened it.
- **Esc**, the ✕, clicking the backdrop or browser **Back** closes it.
- **↑ / ↓ buttons and j / k** step through the list it was opened from. The
  footer's **Save & weigh next** does the same while weighing.
- **Unsaved changes**: closing Edit with changes shows an inline "Discard
  unsaved changes?" bar, not a browser `confirm()`.

**Command palette.** `/` or `⌘K` from anywhere. Empty, it shows actions (Add
spool, Weigh a spool…, Prints needing attention, Switch theme) plus Go to.
Typing matches color, brand, `#id`, location, job name, gcode path or printer.
The `weigh ` prefix turns the list into "Weigh which spool?". ↑↓ ↵ Esc all work.
It uses the ARIA combobox + listbox pattern.

**Row actions.** A whole row is clickable and focusable (↵ opens it). The most
common action (**⚖ Weigh**) is visible on the row; the rest sit in a ⋯ menu,
which is always visible so touch and keyboard users can reach it. Destructive
items are last, after a separator, in red.

**Confirmation.** Only for destructive actions, and it says the consequence:
"Its print history stays… This can't be undone." Everything else saves
directly and confirms with a **toast** that names what changed ("Weighed Copper
· Sunlu: 97 g → 58 g"), with a **View** link. There's no fake Undo, because the
API has none.

**Batch.** Batch attribution follows `dev`'s AttributionQueue (select → attribute
to one spool). The weigh session is the batch pattern for weighing.

**Keyboard map.** `/` `⌘K` palette · `↵` open row · `Esc` close · `j` `k` next
and previous in the panel · `Tab` stays inside the panel while it's open.

---

## 5. Data display rules

### 5.1 Three visual tiers, used for nothing else

| Tier | Looks like | Used for | Examples |
|---|---|---|---|
| **State** | Colored dot/shape + bold word | What something *is doing* | ● Running · ● Finished · ◆ Unknown · ■ Failed · ○ Idle · ◆ Reconnecting |
| **Needs action** | Amber/red text with `!` or `⚠`, or an amber meter | Something *you* should do | `! no spool` · `⚠ 97 g` · `? tare unknown` |
| **Provenance** | Small gray icon + lowercase word, tooltip explains | *Where a number came from* | `✎ typed` · `▦ sliced` · `⎘ recalled` · `⚖ weighed bare` · `◇ community` · `≈ estimated` |

Each state has its own **shape** (dot, diamond, square, ring), so status never
relies on color alone. Chips (pills) remain only for view counts, filters and
the "Future, not built" marker.

### 5.2 Numbers

- Grams: `1,000 g` with thousands separators, always a space before the unit.
  Totals over 1 kg: `95.72 kg`. Money: `$1,721.18`.
- Right-aligned tabular numbers in tables; the unit is never dropped.
- **Net is the default.** "Remaining" always means net filament. Gross appears
  only with its tare beside it (`262 g tare + 812 g = 1,074 g`), so the three
  can't be confused.
- **Unknown is written out** (`unknown`, `no duration`, `—` only for "not
  applicable yet"). A missing tare is never 0.
- Durations: `3h 12m`. An upper bound is `≤ 3h 12m` in amber, with the gap
  count beneath.

### 5.3 Time

Today and yesterday are relative words plus a clock time (`Today 08:37`,
`Yesterday 21:48`); older dates are `16 Sep 10:20`. Freshness is relative
(`updated 3s ago`, `last contact 6m ago`), because the question it answers is
"can I trust this?".

### 5.4 Meters

The remaining meter carries a **tick at the 200 g line**, so "how close to low"
reads without a number. The fill turns amber below it.

### 5.5 Progressive disclosure

| Where | Shows | Moves to the panel |
|---|---|---|
| Filament row | Spool, remaining meter, location *or* tare/gross (column set), value | Full tare/gross breakdown, source, spool type, label, version, prints from this spool |
| Print row | Job, state, duration, grams + source, spool, cost | Job key, why the source matters, per-color table, use type, archive |
| Printer card | State, now/last job, camera, holder contents | Connection details (collapsed) |

### 5.6 System states on every list

Loading → skeletons of the real layout (never a spinner over an empty page).
Empty → what's missing and one action ("Clear filters"). Stale → header dot
turns amber, and a banner gives the data's age and says saving is paused.
All-done → "✓ Nothing needs you right now."

---

## 6. Accessibility of the new pieces

- Panel: `role="dialog"`, `aria-modal`, labeled by its heading, focus trap, focus
  returned on close.
- Palette: `role="combobox"` + `listbox` with `aria-activedescendant`.
- Tabs and segmented controls use `aria-selected`/`aria-pressed` **and** show a
  raised fill plus bold text, not shadow alone.
- Sortable headers use `aria-sort` with a visible ▲/▼/↕.
- Meters use `role="meter"` with min, max and now.
- Toasts sit in an `aria-live="polite"` region. The offline banner is
  `role="alert"`.
- Skip link, and focus rings on every interactive element (including rows).
- Motion (drawer slide, highlight flash, skeleton shimmer) turns off under
  `prefers-reduced-motion`.
- All contrast pairs are unchanged from v3 (54/54 pass). No new colors were
  introduced.

---

## 7. Things I fixed for honesty

- **Tray positions removed** (see §1 #8). The Move flow chooses a *holder*, and
  full holders are disabled with the reason.
- **"Loaded filament: recorded by Extrudex, not read from the printer"** on
  every printer card.
- **API gaps are labeled where they bite**: spool location history
  (`spool_location_event` has no read endpoint) and weight source on
  `/api/prints`.
- The weigh flow shows before → after and refuses, with the reason, a reading
  below tare or above a full spool (the same two checks `dev` does).

## 8. Not redesigned in this iteration

Lists (taxonomy), Labels, Access administration, the Add/Edit **printer** form,
and the phone scan session (`/s/:id`, `/c/:id`). They keep their `dev` screens.
The nav links to them show a toast saying so.

## 9. New open questions

1. **Suggested spool acceptance.** On `dev` a suggestion is "not confirmed or
   charged" until accepted. Iteration 2 puts **Use** one click away. Is one
   click enough confirmation for a deduction, or should it ask?
1a. On click is fine as long as it's accurate. It can always be manually updated if it was an error.
2. **Weigh session order.** It follows the current list order (least remaining
   first). Would shelf order be better? That needs location to be structured,
   not free text.
2a. Weight would be best, but the location should also be visible, that way I can see the rolls that are lowest and use them first.
3. **Default landing page.** Dashboard, or straight to Prints › Needs attention
   when it's non-empty?
3a. Dashboard
4. **Badge scope.** Should Filament get a badge for "tare unknown", or does that
   become nagging, since most tares resolve from a spool type?
4a. Yes, this is good. It identifies an assumed weight and could be off.
5. **Palette actions.** Worth adding "Load ‹spool› into ‹holder›" and "Attribute
   ‹print› to ‹spool›" as typed commands?
5a. Makes sense to me.

## 10. Extra implementation tasks from iteration 2 (titles only, smallest first)

1. Add a freshness indicator driven by the last successful poll
2. Show an offline banner with the data's age when polling fails
3. Add a 200 g tick to the remaining meter
4. Replace provenance chips with icon + text labels and tooltips
5. Make spool rows and holder contents open a detail panel
6. Deep-link panel state in the URL (`#spool=`, `#print=`, `&tab=`)
7. Add Stock / Weights column sets to Filament
8. Add saved views with counts to Filament (All, Low, Loaded, In storage, Tare unknown)
9. Add a Weigh tab with a live before/after preview
10. Add a weigh session (Save & weigh next)
11. Add a Move tab that picks a holder, disabling full ones
12. Add "+ Load" on printer holders with a stored-spool picker
13. Add a Needs attention tab to Prints with inline suggestion acceptance
14. Add nav badges for prints needing attention and disconnected printers
15. Add a "Needs you" queue to the Dashboard
16. Add a ⌘K command palette over spools, prints, printers and actions
17. Add a mobile bottom tab bar and a floating Add button
18. Order printer cards by urgency and support `#printer=` scroll-to