Extrudex/design/01-filament-inventory-list.md

Filament Inventory List — Screen Specification

Screen ID: FIL-001
Source of Truth: Material Design 3
Tone: Modern Industrial/Maker
Theme: Dark Mode, High-Contrast
Last Updated: 2026-04-20

---

1. Objective

Provide a single, scannable view of all filament spools in inventory. Users (shop operators) must be able to:

• Rapidly assess stock levels at a glance (which spools are low/critical).
• Search by material type, brand, color, or internal tracking ID.
• Filter by status (Available, In Use, Low Stock, Depleted).
• Navigate to spool detail or initiate the Smart Intake workflow.

This is the primary landing screen for both the kiosk and the mobile PWA.

---

2. Screen Inventory

Element	MD3 Component	Notes
Top App Bar	md-top-app-bar (medium)	Title + search toggle + intake FAB
Search Bar	md-search-bar	Expandable on tap; collapses to icon on kiosk
Filter Chips	md-chip-set (filter)	Status filters: All / Available / In Use / Low / Depleted
Inventory List	md-list (3-line)	Spool cards as list items
Low-Stock Badge	md-badge	Tonal badge on list items
Extended FAB	md-fab (extended)	"Smart Intake" CTA
Navigation Rail	md-navigation-rail	Kiosk only — Inventory / Printers / Jobs / Settings
Bottom Navigation	md-navigation-bar	Mobile only — same destinations
Empty State	Illustration + md-text-button	When no spools match filter

---

3. Layout Specification

Title

"Filament Inventory" — displayed in the Top App Bar headline slot.

Sections

A. Top App Bar (56dp mobile / 64dp kiosk)

• Leading: Menu icon (kiosk) / Back arrow (mobile, if deep-linked)
• Title: "Filament Inventory"
• Trailing actions: Search icon (toggles search bar), Overflow menu (Sort by, Export)

B. Search Bar (0dp collapsed → 56dp expanded)

• Triggered by search icon tap or pull-down gesture on mobile
• Placeholder: "Search spools, brands, colors…"
• Auto-focus on expand; dismiss on back/clear
• Real-time filtering as user types

C. Filter Chip Row (52dp height, horizontal scroll)

• Chips: All | Available | In Use | Low Stock | Depleted
• Default selection: All
• Multi-select disabled — single filter active at a time
• Chip styling: Tonal variants per status color
  • Available: green tonal
  • In Use: blue tonal (primary)
  • Low Stock: yellow tonal (warning)
  • Depleted: red tonal (error)

D. Inventory List (flex, scrollable)

• Each item is a 3-line list item with leading/trailing elements:

┌──────────────────────────────────────────────────┐
│ [Color Swatch]  PLA Basic - Matte Black           │
│                Bambu Lab • Slot A3 • 842g left    │
│                ▓▓▓▓▓▓▓▓▓▓░░  67%  [Low] badge   │
├──────────────────────────────────────────────────┤
│ [Color Swatch]  PETG Basic - Transparent          │
│                Polymaker • Shelf B2 • 210g left   │
│                ▓▓▓░░░░░░░░░  21%  [Critical] ⚠  │
└──────────────────────────────────────────────────┘

• Leading: Circular color swatch (40dp) — matches filament color
• Line 1: Material name (MaterialBase + Finish + Modifier) — titleMedium, onSurface
• Line 2: Brand • Location • Remaining weight — bodyMedium, onSurfaceVariant
• Line 3: Linear progress indicator + percentage text — labelSmall, onSurfaceVariant
• Trailing: Status badge (tonal chip) + chevron icon
• Divider: Full-width between items

Sort order (default): Low stock first, then alphabetical by material name.

E. Extended FAB (Bottom-end, mobile; Bottom-end, kiosk)

• Label: "Smart Intake" + qr_code_scanner icon
• Container: primaryContainer color
• On tap → navigates to Smart Intake Scan State

F. Navigation (Screen-level)

• Kiosk: Navigation Rail on leading edge (80dp wide)
  • Destinations: Inventory (active), Printers, Jobs, Settings
• Mobile: Bottom Navigation Bar (80dp height)
  • Same destinations

Primary CTA

Smart Intake (Extended FAB) — always visible, anchored bottom-end.

Secondary Actions

• Tap list item → Spool Detail View
• Overflow → Sort options (Name A-Z, Name Z-A, Weight Low→High, Weight High→Low, Recently Used)
• Overflow → Export inventory (CSV)

Key Components

• Search bar with real-time filtering
• Filter chip set (single-select)
• 3-line list items with progress indicators
• Color swatch leading element
• Status tonal badges
• Extended FAB

States

State	Visual
Loading	md-circular-progress centered, list skeleton (shimmer)
Empty (no spools)	Spool icon illustration + "No spools in inventory" + "Add your first spool" text button
Empty (no filter matches)	"No spools match your filter" + Clear filter chip button
Error	Error illustration + "Couldn't load inventory" + Retry button
Low Stock item	Yellow tonal badge "Low" + progress bar < 25% yellow
Critical item	Red tonal badge "Critical" + progress bar < 10% red + pulsing dot
Depleted item	Red tonal badge "Depleted" + progress bar 0% + strikethrough title

---

4. UX Rationale

1. Progress bars beat numbers alone. A visual progress indicator communicates remaining spool life faster than parsing "210g / 1000g" — critical in a busy workshop where decisions are made in seconds.

2. Low stock first (default sort). Operators need to see what's running out before what's plentiful. This prevents the "surprise empty spool" problem mid-print.

3. Color swatches as leading elements. Filament identification is primarily visual — operators scan for color before reading text. The swatch leverages pre-attentive processing.

4. Single-select filters over multi-select. Workshop operators don't construct complex queries. They want one quick filter tap. Multi-select adds cognitive load for minimal practical benefit.

5. Smart Intake FAB, not a menu item. Intake is the most frequent action (new spools arrive regularly). It deserves the highest-affordance control on screen — a FAB is unmissable.

6. Search collapses by default. On kiosk, screen space is precious. The search icon expands the bar only when needed, preserving vertical list space.

7. Empty states with action. An empty inventory list should immediately offer the path forward — "Add your first spool" links directly to Smart Intake.

---

5. Visual Direction

Typography (MD3 Type Scale)

Role	Token	Size	Weight	Line Height
App Bar Title	titleLarge	22sp	400	28sp
List Item Line 1	titleMedium	16sp	500	24sp
List Item Line 2	bodyMedium	14sp	400	20sp
List Item Line 3	labelSmall	11sp	500	16sp
Filter Chip Text	labelLarge	14sp	500	20sp
FAB Label	labelLarge	14sp	500	20sp
Empty State Title	headlineSmall	24sp	400	32sp
Empty State Body	bodyMedium	14sp	400	20sp

Spacing (MD3 8dp grid)

Element	Spacing
App Bar internal padding	16dp horizontal, 12dp vertical
Filter chip row padding	16dp horizontal, 8dp vertical
Chip gap	8dp
List item padding	16dp horizontal, 12dp vertical (top/bottom of 3-line)
List item internal gap	16dp (leading to content), 16dp (content to trailing)
FAB margin	16dp from edges
Content area padding	0dp (list is edge-to-edge with dividers)

Color (MD3 Dark Theme — "Industrial Maker")

Based on a blue-grey primary seed for the industrial feel, with teal as secondary (maker accent).

Role	Token	Value (Dark)	Usage
Background	surface	#1C1B1F	Screen background
On Background	onSurface	#E6E1E5	Primary text
Surface Variant	surfaceContainer	#211F26	App bar, list items
On Surface Variant	onSurfaceVariant	#CAC4D0	Secondary text, chip outlines
Primary	primary	#A8CEDA	FAB container, active states
On Primary	onPrimary	#00303E	FAB label text
Primary Container	primaryContainer	#004D63	FAB container (tonal), active chip fill
On Primary Container	onPrimaryContainer	#A8CEDA	Active chip text
Secondary	secondary	#B1CCC7	Navigation rail active icon
Tertiary	tertiary	#EFB8C8	Accent (not used here)
Error	error	#F2B8B5	Depleted badge, critical states
Error Container	errorContainer	#8C1D18	Critical badge background
On Error Container	onErrorContainer	#F2B8B5	Critical badge text
Custom: Warning	—	#FFD580	Low stock indicator
Custom: Warning Container	—	#5D4200	Low stock badge background
Custom: Success	—	#8BD0A0	Available badge text
Custom: Success Container	—	#00522E	Available badge background
Outline	outline	#938F99	Dividers, chip outlines
Outline Variant	outlineVariant	#49454F	Subtle borders

Color Swatches

Spool color swatches use the actual filament color as a circular filled element (40dp diameter) with a 2dp outlineVariant border for visibility on dark backgrounds. For transparent/clear filaments, use a diagonal hatch pattern fill.

---

6. Responsiveness

Kiosk (800×480, Raspberry Pi 5 Touchscreen)

┌──────┬──────────────────────────────────────────────┐
│ NAV  │  Filament Inventory          [🔍] [⋮]       │
│ RAIL │──────────────────────────────────────────────│
│      │  [All] [Available] [In Use] [Low] [Depleted] │
│ 📦   │──────────────────────────────────────────────│
│ 🖨️   │  ● PLA Basic - Matte Black                   │
│ 📋   │    Bambu Lab • Slot A3 • 842g                │
│ ⚙️   │    ▓▓▓▓▓▓▓▓▓▓░░  67%               [Low]    │
│      │──────────────────────────────────────────────│
│      │  ● PETG Basic - Transparent                  │
│      │    Polymaker • Shelf B2 • 210g               │
│      │    ▓▓▓░░░░░░░░░  21%             [Critical]  │
│      │──────────────────────────────────────────────│
│      │  ● ABS Basic - White                         │
│      │    eSUN • Slot B1 • 950g                     │
│      │    ▓▓▓▓▓▓▓▓▓▓▓▓  95%           [Available]  │
│      │                                  [+ Smart   │
│      │                                   Intake] ↗  │
└──────┴──────────────────────────────────────────────┘

• Navigation Rail: 80dp wide, pinned left
• List area: 720dp × 420dp usable
• Visible items: ~4-5 spools without scrolling
• Touch targets: All interactive elements ≥ 48dp (exceeds 44dp minimum for workshop glove use)
• FAB: Bottom-right, 16dp margin from rail and screen edge

Mobile PWA (375×812, e.g., iPhone 14)

┌──────────────────────────────────┐
│  Filament Inventory    [🔍] [⋮]  │
│──────────────────────────────────│
│  [All] [Avail] [In Use] [Low] [×]│
│──────────────────────────────────│
│  ● PLA Basic - Matte Black       │
│    Bambu Lab • Slot A3 • 842g    │
│    ▓▓▓▓▓▓▓▓▓▓░░  67%    [Low]   │
│──────────────────────────────────│
│  ● PETG Basic - Transparent      │
│    Polymaker • Shelf B2 • 210g   │
│    ▓▓▓░░░░░░░░░  21%  [Critical] │
│──────────────────────────────────│
│  ● ABS Basic - White             │
│    eSUN • Slot B1 • 950g         │
│    ▓▓▓▓▓▓▓▓▓▓▓▓  95%  [Avail]   │
│──────────────────────────────────│
│                                  │
│              [+ Smart Intake] ↗  │
│──────────────────────────────────│
│  📦     🖨️     📋     ⚙️         │
│ Inventory Printers Jobs Settings │
└──────────────────────────────────┘

• Bottom Navigation: 80dp, pinned bottom
• List area: 375dp × ~600dp usable
• Visible items: ~5-6 spools without scrolling
• FAB: Floating above bottom nav, right-aligned
• Filter chips: Horizontally scrollable when more than screen width

Key Adaptations

Property	Kiosk (800×480)	Mobile (375×812)
Navigation	Rail (left)	Bottom bar
Search	Collapsed icon by default	Same, but swipe-down gesture also expands
List item density	Comfortable (3-line, 72dp)	Same density
FAB position	Bottom-right, above list	Bottom-right, above nav bar
Filter chips	All visible at once	Horizontally scrollable
Sort access	Overflow menu	Overflow menu

---

7. Developer Handoff Notes

Angular Material Components

UI Element	Angular Material Component	Notes
Top App Bar	<mat-toolbar>	Use @angular/material/toolbar. Medium emphasis variant.
Search	Custom wrapper + <input matInput>	No native mat-search-bar in Angular Material; implement custom expandable search with @ViewChild animation.
Filter Chips	<mat-chip-listbox>	Use mat-chip-option with selected binding. Single-select: deselect others on select.
List Items	<mat-list> + <mat-list-item>	3-line variant with matListItemTitle, matListItemLine, matListItemMeta.
Progress Bar	<mat-progress-bar>	Use mode="determinate" with [value] binding. Custom color classes for warning/error thresholds.
Badge	<mat-badge>	Overlay on list items. Use matBadgeColor for status colors.
Extended FAB	<button mat-fab extended>	Use @angular/material/button. extended attribute for label.
Nav Rail	<mat-sidenav> styled as rail	No native nav-rail in Angular Material yet; implement as styled sidenav with icon buttons.
Bottom Nav	<mat-bottom-nav> or custom	Use <nav mat-tab-nav-bar> positioned at bottom as a workaround.
Empty State	Custom component	Illustration (SVG) + <button mat-button>.
Loading	<mat-spinner>	Use mode="indeterminate" centered in list area.

Interaction Notes

1. Search expansion: Animate height from 0→56dp with @angular/animations (expandCollapse trigger, 200ms ease-out).
2. Filter chip selection: Single-select logic in component — on chip click, set selectedChip = chip.value, deselect all others.
3. List item tap → navigation: Use routerLink="/spools/:id" on each mat-list-item.
4. FAB → Smart Intake: Navigates to /intake/scan.
5. Progress bar color: Dynamically set based on percentage:
   • ≥ 25%: primary (teal-blue)
   • 10-24%: Custom warn-yellow class
   • < 10%: warn (red)
6. Skeleton loading: Use @angular/material skeleton pattern or custom shimmer CSS animation on list items during initial load.
7. Pull-to-refresh (mobile): Implement with Angular CDK @cdk/drag-drop or a custom gesture handler to refresh inventory data.
8. Infinite scroll / pagination: Load 20 spools initially, load more on scroll-to-bottom.

Accessibility

Requirement	Implementation
Screen reader	Each list item: aria-label="PLA Basic Matte Black, Bambu Lab, Slot A3, 842 grams remaining, 67 percent, Low stock"
Color swatch	aria-label="Color: Matte Black" + role="img"
Progress bar	aria-valuenow, aria-valuemin="0", aria-valuemax="100", aria-label="Remaining filament: 67 percent"
Filter chips	role="listbox", each chip role="option" + aria-selected
Search	role="search", aria-label="Search filament inventory"
FAB	aria-label="Smart Intake: scan new spool"
Keyboard nav	Tab through list items, Enter to select. Escape to dismiss search.
Focus management	On search expand, auto-focus input. On search collapse, return focus to search icon.
Motion reduction	Respect prefers-reduced-motion — disable shimmer, use opacity fade for loading.
Contrast	All text meets WCAG AA (4.5:1) against dark surface. Verified: onSurface (#E6E1E5) on surface (#1C1B1F) = 11.2:1 ✓

SignalR Integration

• Subscribe to SpoolUpdated hub event on screen init.
• On event: update the corresponding list item in-place (no full refresh).
• On SpoolAdded: insert at sorted position with highlight animation (300ms primaryContainer background flash).
• On SpoolDepleted: move to Depleted filter group, show toast notification.

Performance Notes

• Use TrackByFunction on *ngFor to prevent full list re-render on updates.
• Virtual scrolling via <cdk-virtual-scroll-viewport> if inventory exceeds 100 spools.
• Debounce search input at 300ms.