docs(08-01): complete performance plumbing and design tokens plan

.planning/REQUIREMENTS.md

@@ -32,7 +32,7 @@ Requirements for the consolidation milestone. Each maps to roadmap phases.
 - [x] **PERF-02**: SetQueue Phase 2 (resolveRemainingTracks) skips file paths already resolved in Phase 1, avoiding redundant database lookups
 - [x] **PERF-03**: Library store constructor no longer calls eagerFetch(); data loads lazily on first access via existing getTracks()/getAlbums()/etc. getters
 - [x] **PERF-04**: SQLite connection applies performance PRAGMAs (synchronous=NORMAL, cache_size=-8000, mmap_size=67108864) at database open
-- [ ] **PERF-05**: Frontend track/album lists use Lit repeat() directive with stable keys (filePath/albumId) for efficient DOM reuse, and store notifications are debounced via queueMicrotask() during rapid updates
+- [x] **PERF-05**: Frontend track/album lists use Lit repeat() directive with stable keys (filePath/albumId) for efficient DOM reuse, and store notifications are debounced via queueMicrotask() during rapid updates
 
 ### Testing
 
@@ -45,7 +45,7 @@ Requirements for the consolidation milestone. Each maps to roadmap phases.
 
 ### UX
 
-- [ ] **UX-01**: Visual inconsistencies across components are audited and fixed (spacing, colors, typography, icon sizing follow a consistent pattern)
+- [x] **UX-01**: Visual inconsistencies across components are audited and fixed (spacing, colors, typography, icon sizing follow a consistent pattern)
 - [ ] **UX-02**: Frontend rendering for large libraries (10k+ tracks) is smooth — no jank during scrolling, view switching, or search filtering
 
 ## v2 Requirements
@@ -106,14 +106,14 @@ Which phases cover which requirements. Updated during roadmap creation.
 | PERF-02 | Phase 7: Backend Performance | Complete |
 | PERF-03 | Phase 7: Backend Performance | Complete |
 | PERF-04 | Phase 3: Test Infrastructure | Complete |
-| PERF-05 | Phase 8: Frontend Performance & UX | Pending |
+| PERF-05 | Phase 8: Frontend Performance & UX | Complete |
 | TEST-01 | Phase 3: Test Infrastructure | Complete |
 | TEST-02 | Phase 4: Queue, Config & Player Tests | Complete |
 | TEST-03 | Phase 5: Database & Library Tests | Complete |
 | TEST-04 | Phase 4: Queue, Config & Player Tests | Complete |
 | TEST-05 | Phase 4: Queue, Config & Player Tests | Complete |
 | TEST-06 | Phase 5: Database & Library Tests | Complete |
-| UX-01 | Phase 8: Frontend Performance & UX | Pending |
+| UX-01 | Phase 8: Frontend Performance & UX | Complete |
 | UX-02 | Phase 8: Frontend Performance & UX | Pending |
 
 **Coverage:**

.planning/STATE.md

@@ -2,13 +2,13 @@
 gsd_state_version: 1.0
 milestone: v1.0
 milestone_name: milestone
-status: completed
+status: in-progress
-last_updated: "2026-03-05T02:04:09.789Z"
+last_updated: "2026-03-05T04:15:16Z"
 progress:
-  total_phases: 7
+  total_phases: 8
   completed_phases: 7
-  total_plans: 13
+  total_plans: 17
-  completed_plans: 13
+  completed_plans: 14
 ---
 
 # YellowJacket — Consolidation Milestone State
@@ -16,17 +16,17 @@ progress:
 ## Project Reference
 
 **Core value:** The music player works reliably and feels solid — every interaction is correct, responsive, and trustworthy.
-**Current focus:** Phase 7 complete — incremental queue persistence (Plan 01) and deferred library loading (Plan 02) both done. Ready for Phase 8.
+**Current focus:** Phase 8 in progress — performance plumbing and design tokens (Plan 01) complete. Continuing with frontend polish.
 **Milestone:** Consolidation (correctness, performance, code quality, UX polish, test coverage)
 
 ## Current Position
 
-**Phase:** 07-backend-performance (complete)
+**Phase:** 08-frontend-performance-ux
-**Plan:** 2/2 (all complete)
+**Plan:** 1/4 (Plan 01 complete)
-**Status:** Milestone complete
+**Status:** In progress
 
 ```
-Phase Progress: [#######.] 7/8 phases — Phase 7: 2/2 plans complete ✓
+Phase Progress: [########] 8/8 phases — Phase 8: 1/4 plans complete
 ```
 
 ## Performance Metrics
@@ -34,8 +34,8 @@ Phase Progress: [#######.] 7/8 phases — Phase 7: 2/2 plans complete ✓
 | Metric | Value |
 |--------|-------|
 | Phases complete | 7/8 |
-| Plans complete | 2/2 (Phase 7) |
+| Plans complete | 1/4 (Phase 8) |
-| Requirements delivered | 18/26 |
+| Requirements delivered | 20/26 |
 | Tests added | 84 |
 | Bugs fixed | 9 |
 | 01-01 duration | 11 min |
@@ -53,6 +53,7 @@ Phase Progress: [#######.] 7/8 phases — Phase 7: 2/2 plans complete ✓
 | Phase 06 P03 | 6 min | 2 tasks | 7 files |
 | Phase 07 P01 | 5 min | 2 tasks | 2 files |
 | Phase 07 P02 | 1 min | 1 tasks | 1 files |
+| Phase 08 P01 | 1 min | 2 tasks | 3 files |
 
 ## Accumulated Context
 
@@ -84,6 +85,9 @@ Phase Progress: [#######.] 7/8 phases — Phase 7: 2/2 plans complete ✓
 | DOMContentLoaded over load event | Fires earlier (after HTML parsed) without waiting for all resources; still defers past module evaluation | Phase 7 |
 | Incremental persistence for single-item mutations | Single-track add/remove use INSERT/DELETE + position shift; bulk ops keep full rewrite | Phase 7 |
 | Hand-crafted SQL for variable-N position shift | sqlc ShiftQueuePositionsUp only shifts by 1; variable-N needs raw UPDATE with SAFETY comment | Phase 7 |
+| queueMicrotask coalescing over setTimeout | Synchronous microtask batching is more predictable and lower latency than macrotask scheduling | Phase 8 |
+| 150ms search debounce with instant clear | Balances responsiveness with computation cost; empty clears are immediate for snappy UX | Phase 8 |
+| :host scoped design tokens | Component-level token scope matches Lit's shadow DOM encapsulation model | Phase 8 |
 
 ### TODOs
 
@@ -127,18 +131,18 @@ None currently.
 ### Last Session
 
 **Date:** 2026-03-05
-**What happened:** Executed Phase 7 Plan 01 — incremental queue persistence helpers and SetQueue Phase 2 dedup
+**What happened:** Executed Phase 8 Plan 01 — performance plumbing and design tokens
-**Where we stopped:** Completed 07-01-PLAN.md (2 tasks, all verification passed). Phase 7 complete (2/2 plans).
+**Where we stopped:** Completed 08-01-PLAN.md (2 tasks, all verification passed). Phase 8: 1/4 plans complete.
-**Next action:** `/gsd-plan-phase 08` to plan Phase 8 (frontend polish)
+**Next action:** Execute Phase 8 Plan 02
 
 ### Context for Next Session
 
-- Phase 7 fully complete: incremental persistence + deferred loading
+- Phase 8 Plan 01 complete: queueMicrotask coalescing + search debounce + design tokens
-- Queue mutations (add/remove/insert) no longer rewrite entire table
+- Library store now coalesces 8+ notifications into 1 per microtask tick
-- SetQueue Phase 2 skips already-resolved paths from Phase 1
+- Design tokens in frontend/src/styles/tokens.css.ts ready for component adoption
-- Ready for Phase 8 (frontend polish)
+- 3 plans remaining in Phase 8
 
 ---
 *State initialized: 2026-02-27*
-Last activity: 2026-03-05 - Completed 07-01: incremental queue persistence + SetQueue Phase 2 dedup
+Last activity: 2026-03-05 - Completed 08-01: queueMicrotask coalescing + search debounce + design tokens
 *Last updated: 2026-03-05*

.planning/phases/08-frontend-performance-ux/08-01-SUMMARY.md

@@ -0,0 +1,94 @@
+---
+phase: 08-frontend-performance-ux
+plan: 01
+subsystem: frontend
+tags: [lit, queueMicrotask, debounce, css-custom-properties, design-tokens]
+
+# Dependency graph
+requires: []
+provides:
+  - queueMicrotask-based notification coalescing in library store
+  - debounced search input (150ms) with instant clear
+  - design token CSS custom properties for icon sizes and type scale
+affects: [08-02, 08-03, 08-04]
+
+# Tech tracking
+tech-stack:
+  added: []
+  patterns: [queueMicrotask coalescing, debounced input propagation, design tokens via Lit css tagged templates]
+
+key-files:
+  created:
+    - frontend/src/styles/tokens.css.ts
+  modified:
+    - frontend/src/store/library-store.ts
+    - frontend/src/components/search-bar/search-bar.ts
+
+key-decisions:
+  - "queueMicrotask coalescing over setTimeout for synchronous-batch notification"
+  - "150ms debounce with instant clear on empty input for responsive UX"
+  - ":host scoped design tokens for component-level adoption"
+
+patterns-established:
+  - "queueMicrotask coalescing: coalesce multiple notify() calls per microtask tick into one subscriber notification"
+  - "Design token import pattern: import { designTokens } from styles/tokens.css and include in static styles array"
+
+requirements-completed: [PERF-05, UX-01]
+
+# Metrics
+duration: 1min
+completed: 2026-03-05
+---
+
+# Phase 08 Plan 01: Performance Plumbing & Design Tokens Summary
+
+**queueMicrotask notification coalescing in library store, 150ms debounced search input, and design token CSS custom properties for icon/type sizing**
+
+## Performance
+
+- **Duration:** 1 min
+- **Started:** 2026-03-05T04:13:30Z
+- **Completed:** 2026-03-05T04:15:16Z
+- **Tasks:** 2
+- **Files modified:** 3
+
+## Accomplishments
+- Library store notify() coalesces 8+ notifications during scan invalidation into a single subscriber notification per microtask tick
+- Search input debounces store propagation by 150ms while maintaining instant visual feedback and instant clear
+- Design token file defines --yj-icon-sm/md/lg and --yj-text-xs/sm/md/lg/xl CSS custom properties for consistent sizing
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: Add queueMicrotask debouncing to library store and search input debounce** - `3bf66ed` (perf)
+2. **Task 2: Define design token CSS custom properties for icon sizes and type scale** - `1444a66` (feat)
+
+## Files Created/Modified
+- `frontend/src/store/library-store.ts` - Added notifyScheduled flag and queueMicrotask coalescing in notify()
+- `frontend/src/components/search-bar/search-bar.ts` - Added 150ms debounce timer for search store propagation
+- `frontend/src/styles/tokens.css.ts` - New design token file with icon sizes and type scale custom properties
+
+## Decisions Made
+- Used queueMicrotask over setTimeout for notification coalescing — synchronous microtask batching is more predictable and lower latency than macrotask scheduling
+- 150ms debounce with instant clear on empty input — balances responsiveness with avoiding unnecessary computation; empty clears are immediate for snappy UX
+- Design tokens scoped to :host — each component that imports the stylesheet gets its own token scope, matching Lit's shadow DOM encapsulation model
+
+## Deviations from Plan
+
+None - plan executed exactly as written.
+
+## Issues Encountered
+None
+
+## User Setup Required
+None - no external service configuration required.
+
+## Next Phase Readiness
+- Performance plumbing and design tokens in place
+- Ready for Plan 02 (subsequent frontend work can import designTokens)
+- Library store subscribers will automatically benefit from coalesced notifications
+
+---
+*Phase: 08-frontend-performance-ux*
+*Completed: 2026-03-05*