design-v3/SUMMARY.md

Extrudex Soft UI (Design System v3) proposal: summary

2026-09-18. This is a proposal only. Nothing was changed in the Extrudex repository (still clean at dev 321ce0d) or in CTXD. Nothing was deleted.

What I built and where it is

Everything is in ~/Design/extrudex-v3/.

File	What it is
00-understanding.md	Step 1: every field on each existing screen, every stored printer field, the v2.0 palette, and how CTXD differs from the code
design-system-v3.css	Step 2: the token set. v2.0 base kept, dark and light themes, neumorphism tokens (surfaces, raised and inset pairs, 4 intensity levels, radius scale), state tokens, reference components
design-system-v3.md	Step 2: every changed or added token with its reason, the state matrix, the dark-mode approach, 2 alternative palettes, and contrast tables for both themes (54/54 pass, plus 9 more pairs)
fonts/	JetBrains Mono 400/500/700/800 woff2 (the same @fontsource 5.3.0 files the app ships) + OFL license
screens/01-dashboard.html	New standalone Dashboard: stock tiles, running low (net + gross, tare unknown shown), net kg by material, recent prints with weight source and upper-bound duration marks, compact printer strip
screens/02-filament.html	Inventory: working search and filters, table/cards toggle, the 5-part name, net remaining vs tare (+ source) vs gross, Edit, Delete with a confirmation dialog
screens/03-spool-form.html	Add/Edit spool with a scenario switcher: 409 conflict, 400 field errors, tare unknown, add new, plus a control-state specimen
screens/04-printers.html	Printers: stored fields only, a "dev today / dev + feature branch" data toggle, the MQTT dropped state (A1), and a Future, not built section
source/	Build inputs (build.py makes each screen self-contained with base64 fonts) and checks/table.py, which regenerates the contrast table

Every screen has a Light/Dark toggle (also ?theme=light or ?theme=dark in the URL), has no network dependencies, and was checked at 1440 px and 390 px in headless Chrome.

Decisions that go against DECISIONS.MD or the v2.0 rules

1. Styling: "tokens verbatim… do not edit a token to suit a component." v3 changes the values of a few v2.0 semantic tokens (--surface-raised, --shadow-raised, --focus-ring, --radius-sm, --radius-md, --text-on-accent in light). This isn't editing a token to suit a component. It's a proposed new version of the design system, and each change has a reason in the .md. It still needs your call: adopting it means updating the guide at pages.ccl first and then copying it verbatim into theme.css, as the rule intends.
2. v2.0 brand rules "0 radius" and "flat shadows" are overturned. Soft UI can't exist without them. --radius-none stays for tables and code.
3. Primary buttons changed color, dark theme (#8f7ae0 → #a99af0), because v2.0's ink-on-accent is 4.32:1 and fails AA. That's a brand-color shift on the most visible control.
4. CONTEXT scope: "printer status pages… deliberately out until daily use." The Printers screen was designed because you asked for it. Note that a printers view already exists on dev, embedded in Floor.

Things I followed even where the code has moved past the docs:

• Weight source is shown with 4 values (typed, sliced, recalled, unknown). DECISIONS.MD lists 3. The schema adds sliced and says recalled is no longer written.
• Tare origin: the code (resolveTare in types.ts) falls back to a brand tare, labeled as a guess. DECISIONS.MD says tare comes "from spool_type, never from brand". The mockups never show a brand-derived tare.

Open questions

1. Adopt or reject the two brand-rule changes (radius, shadows) and the lighter primary-button violet? Everything else depends on this.
2. Floor → Dashboard + Printers. The proposal splits today's Floor into a stock-first Dashboard and a separate Printers page. Is that the direction, or should Floor stay as one page restyled?
3. Weight source in GET /api/prints. It's stored but not served, so the Dashboard needs a small API change. OK to add it?
4. recalled vs sliced. Should DECISIONS.MD be updated to say sliced exists and recalled is legacy? That's a CTXD edit, which I didn't make.
5. Brand-tare fallback. Code and DECISIONS.MD disagree. Which one is right?
6. Serial display. I masked the middle of serials (01P09A••••••4821). Show in full, masked, or hidden?
7. "Tare unknown only" filter is new on the Filament page (it helps work down the "weigh it yourself" list). Keep it?
8. The 409 "reapply my change" button assumes the client can diff the fields you changed against the new version. Today the form only shows the server's message. Do you want that behavior, or just "reload"?
9. Alternative palettes A (warm graphite) and B (slate/teal) are in the .md. Do you want either mocked up?
10. CTXD is out of date (Dashboard.tsx, no auth, Bambu only, the design system URL). Should someone refresh CONTEXT.MD? I made no CTXD edits.

Proposed Maestro tasks (titles only, smallest first; not created)

1. Add weight_source to the GET /api/prints response
2. Add v3 warning and info status tokens to theme.css
3. Add the --border-control token and apply it to buttons, inputs and selects
4. Replace the v2.0 focus ring with the v3 2px offset outline
5. Fix primary-button text contrast (4.32:1 → 6.14:1)
6. Show a weight-source chip on each print row
7. Show an upper-bound mark on durations with connection gaps
8. Show "gaps not counted" on prints with null connection_gaps
9. Show tare, tare source and gross weight on the Filament table and cards
10. Show "tare unknown" (never 0) wherever gross weight is derived
11. Add the "Tare unknown only" filter to Filament
12. Map spool 400 messages to their fields in SpoolForm
13. Add the 5-part name preview to SpoolForm
14. Add the net/tare/gross scale diagram to SpoolForm
15. Replace the SpoolForm 409 footer text with a conflict panel and reload actions
16. Add a light theme with a stored per-browser toggle
17. Add the neumorphism shadow and radius tokens (after the brand decision)
18. Restyle buttons, inputs and chips with the v3 state matrix
19. Split Floor into a stock-first Dashboard and a Printers page
20. Render the connection-lost state on printer cards (after the printer-connections feature merges)
21. Publish Design System v3 to pages.ccl and re-sync theme.css verbatim

---

Iteration 2 (2026-09-18): navigation, data display and interaction

Everything is in iteration-2/. Iteration 1 above is unchanged, for comparison.

File	What it is
iteration-2/00-ux-review.md	12 findings from iteration 1, the navigation model, flows ranked by frequency, interaction patterns, data-display rules, accessibility notes, 5 new questions, 18 more task titles
iteration-2/screens/index.html	Start here. Flow map plus 8 guided flows that deep-link into each state
iteration-2/screens/01-dashboard.html	"Needs you" queue first, then stock tiles, recent prints by day, printers and running low. Everything clickable
iteration-2/screens/02-filament.html	Saved views with counts, Stock/Weights columns, grouping, sortable headers, row ⋯ menu, weigh session
iteration-2/screens/03-prints.html	New. Needs attention (inline suggestions, grams, batch) · All · Running · Archived
iteration-2/screens/04-printers.html	Urgency order, jump strip, holder fill + Load, stale "last known" state, dev/feature toggle
iteration-2/source/	data.js (one shared model), app.js (shell, palette, panel, toasts), components.css, pages, build.py

What's shared across every page: the spool/print/load panel (deep-linked, Esc/back closes, j/k steps), the ⌘K palette, nav badges for work waiting, toasts after each save, a freshness indicator with an offline state, and a phone tab bar with a floating Add button.

Corrected from iteration 1: it showed AMS "slot" positions, which the database doesn't store. Iteration 2 shows holder fill ("3 / 4") instead.

Verified: every page and panel state loads with no console errors in headless Chrome, at 1440 px and 390 px, in both themes. There are no network requests, and no new colors (the v3 contrast table still applies).

---

Iteration 3 (2026-09-18): remaining screens, tablet and phone

Everything is in iteration-3/. Iterations 1 and 2 are unchanged.

• Start here: iteration-3/screens/index.html (flow map, 14 flows) and iteration-3/screens/devices.html (every screen in live phone 390 × 844, tablet 820 × 1180 and 1180 × 820 frames).
• New screens: 05 Lists · 06 Labels · 07 Access · 08 System · 09 Scan: holder · 10 Scan: spool, plus Add/Edit printer, Manage holders and Remove printer panels on Printers.
• Your answers from iteration-2/00-ux-review.md, applied: Change spool (with real grams-returned wording), lightest-first weigh sessions with location, Filament badge for unverified tares, and load/attribute palette commands.
• Responsive: three tiers (phone < 700, tablet 700–1180 with a compact rail, desktop). Spec in iteration-3/00-changes.md §4.
• Findings: list names are case-sensitive in the schema; audit log, low-filament report and machine tokens have APIs but no screens on dev.
• Verified: all 12 pages and 18 panel/palette states load with no console errors; checked at 390, 820 and 1180 px and desktop, in both themes. No network requests, no new colors.

Terminology update (2026-09-18): iteration 3's UI now says "empty spool weight" everywhere it said "tare" (verified: no rendered text, tooltip, label or placeholder contains "tare"). Code and API names (tare_grams etc.) are unchanged. See iteration-3/00-changes.md §1b. Open item: GLOSSARY.MD in CTXD still uses "Tare".