design-v3/00-understanding.md

Extrudex UI redesign: what exists today

Written 2026-09-18, before any design work. Every source here was read, not changed.

Source	Version read
CTXD extrudex: CONTEXT.MD v3, DECISIONS.MD v4, GLOSSARY.MD v3, HANDOFFS.MD v32 (skimmed)	2026-09-07 / 2026-09-17
Repository dev at 321ce0d (2026-09-17)	read only
Printer-connections feature branch, local ref origin/feature/7efc2030-…-printer-connections at 4e17f9e (2026-09-17)	read with git diff, no checkout, no fetch
Design System v2.0: http://pages.ccl/design-v2.0/	HTTP 200, tokens extracted

Scope agreed on 2026-09-18

• Designs are based on the current dev code, not on the 2026-08-12 picture in CTXD. CTXD is out of date (see "Differences between CTXD and the code" at the end).
• Screen 1 is a new standalone Dashboard. Today, the home route / is Floor.tsx.
• The Printers screen uses the fields stored on dev plus the lifecycle and staleness fields from the unmerged printer-connections feature branch. The branch fields are labeled "on feature branch, not in production".

---

1. Fields shown on each existing screen

Floor (pages/Floor.tsx, route /, the de facto dashboard)

Polls every 10 s. It has two columns.

Primary column

• Printers view (pages/Printers.tsx embedded; see below)
• "Today's prints", from midnight America/New_York, with an "All prints" link
• Print list (components/PrintList.tsx), one row per print:
  • job name (click to edit; locked while running with "name is captured from the printer")
  • printer name · started at
  • status badge: running / finished / failed / unknown
  • duration (— when null), plus a +gap marker when connection_gaps > 0. The tooltip says the figure is "an upper bound rather than a measurement".
  • grams used (click to edit) or a grams input; multi-color prints show "N g total"
  • spool picker ("274 g · Sunlu Mint Green · PLA · Matte"), with a suggested spool
  • cost, or "cost pending" on multi-color prints
  • use type select: Personal / Business / "Use not recorded"
  • archive control
  • per-color rows for multi-color prints: slot, spool, grams, color hex, suggested spool
• Empty states: "Nothing printed today." / "No prints captured yet."

Secondary column

• "Running low": spools under LOW_STOCK_GRAMS = 200 g, each with a color swatch, color name, brand and grams
• "Inventory" stats: Spools, Filament left (g), Stock value ($), Running low (count, warning style)
• Empty state: "No filament tracked yet."

Not shown today: weight_source (see §2 gaps), tare, gross weight.

Filament (pages/Filament.tsx + components/SpoolTable.tsx, route /filament)

• Header: "Labels outstanding: N", Download unlabeled labels, Manage lists, Add spool
• Filters: search ("Search brand, colour, material, location…"), Low stock only, In storage only, brand select with counts, material select with counts, sort (Least remaining / Most remaining / Brand A–Z / Colour A–Z / Highest value), Group identical, view toggle Table / Cards, pagination
• Table columns: swatch · color name (click to edit) + brand · Filament (material · type · finish · speed; "Standard"/"Basic" hidden) · Remaining ("N of M g" + bar, red below 200 g) · $/kg ("Not set" when 0) · Value · Location ("In storage · detail" or container name) · Delete
• Grouped rows: combined total, "N of M g each", "$X/kg each", expand/collapse
• Card view: swatch, color name, brand, taxonomy line, bar, "N g left", value, "In storage" / "Loaded · container", storage detail, Edit, Delete
• Delete opens ConfirmDelete
• Error and status lines, plus empty states

Not shown today: tare, tare source, gross weight, remaining source (typed/weighed), label printed date.

Add/Edit spool (components/SpoolForm.tsx, a modal <dialog>)

Title: "Add spool" / "Edit spool #ID". It has four sections.

1. Identity: Brand* · Material* · Type (optional) · Finish* · Speed (optional) · Spool type (optional, "sets the empty-spool weight") · Location (optional, "Shelf A")

2. Colour: Colour name (with a suggestion from the pinned FilamentColors.xyz catalog: unique, ambiguous or no match) · 1–3 colors, each with a swatch picker and hex text, plus Add colour / Remove / "Colour not known yet" (stores #888888)

3. Quantity and cost: Total grams ("filament, not incl. spool") · Remaining grams · Empty spool (tare, optional, "e.g. 250") with a tare origin note:

   • spool: "This spool's own weight. Saved with it."
   • spool_type: "From the X spool type", plus "(estimated — weigh your own to be sure)"
   • brand: "Guessed from the X brand…" (warning style)
   • unknown: "Recorded on this spool, but nothing says whether it was weighed…"
   • none: no note

   Then Cost per kg.

4. Weigh it (only when tare > 0): scale reading, placeholder "full reads N", hint "Remaining is filled in for you: reading minus N g of spool". Otherwise: "Set an empty-spool weight… and you can weigh the whole spool".

• Footer: client-side errors (scale below tare, capacity contradiction), a single server error line, Cancel, Save changes / Add spool
• 409 today: the server message ("this spool changed after you loaded it — reload it and reapply your edit, so a newer weigh-in is not overwritten (you loaded version 4, it is now version 5)") appears as plain text in the footer. There is no reload action and no side-by-side comparison.
• 400 today: also only in the footer, never next to the field that caused it.

Real 400 messages that can be mapped to a field: color_name is required · cost_per_kg cannot be negative · remaining_grams cannot be negative · remaining_grams cannot exceed total_grams · gross_grams must be greater than zero — it is the whole spool on the scale · a tare of 0 is not a measurement — leave it unset instead · scale_grams is required and must be greater than zero.

Printers (pages/Printers.tsx, embedded in Floor; /printers redirects to /)

This screen already exists on dev. It is not new.

• Header: Add printer / Manage AMS units (admin only; others see "Admin role required…")
• Grouped into In progress, Needs attention (paused, failed), Idle, Offline, with counts
• Full card (busy/paused/failed): name · state badge (Printing, Paused, Failed, Idle, Preparing, Slicing, Waiting…, Offline) · actions menu (Edit, Remove) · job name or "Job name unavailable" · camera snapshot (or "disabled" / "unavailable while offline" / "unavailable") · Loaded filament, "not confirmed in use": each container's label, used/capacity, and each spool's swatch, brand, color and grams (or "Empty") · last print line
• Compact row (idle/offline): state marker, name, badge, last job + "Ended …", or "Last contact unavailable" when offline
• Printer form (PrinterForm.tsx): name, brand (bambu/elegoo), model, IP, serial, access code (write-only)

---

2. Printer data Extrudex stores today

Stored in SQLite on dev (schema.sql)

Table	Field	Notes
printer	id, name (unique), brand (bambu/elegoo/null), model, ip, serial (unique), access_code (never returned; API gives has_access_code), created_at	brand and model are null together (rows imported from printers.json)
filament_container	id, printer_id, kind (ams/ams_lite/external), label, created_at, version; capacity derived (4/4/1)	every printer gets one "External" holder
spool	container_id	which holder a spool is in; NULL = storage
spool_location_event	spool_id, container_id, at, principal_id	move history, not shown in UI
print	printer (name text), printer_id, job_name, job_key, status, started_at, ended_at, duration_seconds, connection_gaps, grams_used, weight_source, cost_usd, deducted_grams, charged_rate_per_kg, spool_id, slice_objects, archived_at, use_type	per-print history
print_filament	slot, spool_id, suggested_spool_id, grams_used, color_hex, weight_source, deducted_grams, charged_rate_per_kg, cost_usd	multi-color components
job_grams	job_key, grams, updated_at	remembered weights

Live, in memory, served by GET /api/printers on dev (PrinterStatus)

id, name, connected (the transport session, not power), state (gcode_state: IDLE, PREPARE, RUNNING, PAUSE, FINISH, FAILED, SLICING, or "" until first seen), job_name (only while a job runs), camera (snapshot/unsupported/disabled), last_print. Also GET /api/printers/{id}/snapshot returns a JPEG.

Parsed but not stored or exposed

mc_percent (progress) and gcode_file_prepare_percent are read from MQTT and used internally only. There are no temperatures, ETA, layer or AMS remain %. Bambu never reports grams.

On the feature branch only (not on dev, not in production)

Added to PrinterStatus: lifecycle (connecting / synchronizing / ready / reconnecting / invalid_config / unsupported / stopped), ready, stale (state and job are cached from a session that is not ready), last_report_at, last_report_age_seconds, failure_category (setup_failed / setup_timeout / synchronization_timeout), failure_detail (a fixed sanitized phrase), session (generation counter). There are UI helpers for "Last known: Printing · 4m ago", "Disconnected — reconnecting" and "Last contact 4m ago".

The dropped-MQTT state the brief asks for is connected=false, which shows as "Offline" on dev. On the feature branch it becomes lifecycle=reconnecting with stale=true and a report age.

---

3. Design System v2.0 color palette (from http://pages.ccl/design-v2.0/)

It matches web/src/theme.css on dev exactly. v2.0 has one (dark) theme only. There is no light theme.

Token	Hex	Usage
--ccl-charcoal	#2c2c30	page background, near-black (--surface-page)
--ccl-charcoal-2	#36363a	raised surface (--surface-raised)
--ccl-charcoal-3	#1b1b1e	input / code block, recessed (--surface-code)
--ccl-gold	#8f7ae0	brand accent, violet despite the name (--accent, --focus-ring, alias --ccl-purple)
--ccl-gold-dim	#7a63cc	accent hover / pressed (--accent-hover)
--ccl-text	#f4f4f6	primary text
--ccl-text-muted	#b2b2ba	secondary text
--ccl-border	#3d3d44	hairline borders
--ccl-border-2	#4e4e57	stronger border / grid lines
--ccl-green	#a9d88b	success
--ccl-red	#f08b93	error
--ccl-white	#ffffff	white
--ccl-ink	#2a2431	text on accent
--ccl-purple-wash	rgba(143,122,224,0.12)	accent tint

Other v2.0 rules the redesign has to deal with:

• Radius: --radius-none/sm/md are all 0px ("the brand is square. 0 is the rule").
• Shadows: flat brand. The only shadow is --shadow-raised: 0 1px 0 0 var(--ccl-border).
• Font: JetBrains Mono for everything. Sizes are 11/12/14/15/18/22/28/40 px and weights 400/500/700/800.
• Spacing runs from 4 to 64 px. Motion is 100/160 ms with cubic-bezier(0.2,0,0,1).
• There is no warning or amber token. Low stock currently reuses red.

---

4. Differences between CTXD and the code

These are recorded so the design follows the code and not the docs.

CTXD says	dev has
pages/Dashboard.tsx	No such file. / is Floor
Printer status pages are out of scope	Printers view with camera, AMS containers and CRUD
No authentication	OIDC, sessions, API tokens, reader/operator/admin roles
Bambu only	Bambu MQTT + Elegoo Centauri SDCP
weight_source is typed/recalled/unknown	Also sliced (read from the 3MF over FTPS). The code says recalled is "no longer written"
Tare source: manufacturer/community/estimated	Two separate things: spool.tare_source/tare_origin (where this spool's tare came from: spool, spool type, brand, unknown, none) and spool_type.source (how trustworthy the published figure is: manufacturer, community, estimated)
Design system at pages.cubecraftlabs.com	404. The live guide is at pages.ccl

---

5. Assumptions I'm working from

None of these blocks the design. Each is a default I've picked, and each is repeated in SUMMARY.md so you can overturn it.

1. The Dashboard shows weight_source, even though GET /api/prints does not return it today. It is stored in the print column, and the cost payload has it. The mockup marks it as needing an API field.
2. Weight source has four values (typed, sliced, recalled, unknown). That follows the code, not DECISIONS.MD's three.
3. Tare is shown as two facts: where this spool's tare came from (origin) and, when it came from a spool type, that type's trust level (manufacturer, community, estimated).
4. The v3 light theme is new. v2.0 has none, so every light token counts as "added".
5. Neumorphism overturns two stated v2.0 brand rules: 0 radius and flat shadows. This is recorded as a deliberate departure, not as editing a token to suit a component.