diff --git a/docs/workstreams/product-ux-ui-convergence.md b/docs/workstreams/product-ux-ui-convergence.md index 8bf136b9..6aa50144 100644 --- a/docs/workstreams/product-ux-ui-convergence.md +++ b/docs/workstreams/product-ux-ui-convergence.md @@ -40,19 +40,28 @@ Desired outcome: neutral graphite canvas, low decorative chroma, stronger inform | UXUI-00..09 | Existing product UX/UI + hardening | — | DONE | | UXUI-10 | Existing automated built-product/golden baseline | UXUI-09 | DONE | | PVR-00 | Visual/component baseline audit | UXUI-10 | DONE | -| PVR-01 | Visual direction + `brand-kit` v0.6 contract | UXUI-10 | ACTIVE | -| PVR-02 | Tokens/primitives/foundation refactor | PVR-00/01 | BLOCKED | -| PVR-03 | App shell + navigation visual refactor | PVR-02 | BLOCKED | -| PVR-04A | Overview + Find best setup + Campaign decision surfaces | PVR-02/03 | BLOCKED | -| PVR-04B | Test a model + Live Run + Run Detail | PVR-02/03 | BLOCKED | -| PVR-05 | Runs + Compare + benchmark/sample/case evidence surfaces | PVR-02/03 | BLOCKED | -| PVR-06 | Library + Settings secondary surfaces | PVR-02/03 | BLOCKED | +| PVR-01 | Visual direction + `brand-kit` v0.6 contract | UXUI-10 | DONE | +| PVR-02 | Tokens/primitives/foundation refactor | PVR-00/01 | DONE | +| PVR-03 | App shell + navigation visual refactor | PVR-02 | DONE | +| PVR-04A | Overview + Find best setup + Campaign decision surfaces | PVR-02/03 | ACTIVE | +| PVR-04B | Test a model + Live Run + Run Detail | PVR-02/03 | ACTIVE | +| PVR-05 | Runs + Compare + benchmark/sample/case evidence surfaces | PVR-02/03 | ACTIVE | +| PVR-06 | Library + Settings secondary surfaces | PVR-02/03 | ACTIVE | | PVR-07 | States, responsive polish, copy disclosure, accessibility hardening | PVR-04A/04B/05/06 | BLOCKED | | PVR-08 | New approved targets + bounded implementation goldens | PVR-07 | BLOCKED | | PVR-09 | PRE_REAL E2E + final human accessibility/usability acceptance | PVR-08 | BLOCKED | Allowed states: `READY`, `ACTIVE`, `BLOCKED`, `DONE`. +`DONE` for PVR-01..03 means the owned technical slice is complete and has current validation evidence inside the visual-refactor stack. It does **not** mean those draft PRs are independently merge/publication-ready: the accepted v0.5 pixel goldens intentionally remain the before-baseline until PVR-08. The stack remains not ready for publication while that deliberate visual mismatch exists. + +### Current stack evidence + +- PVR-01: `brand-kit` v0.6 contract + verifier ownership are implemented in draft PR #89 and passed repository-owned deterministic gates before the foundation changed. +- PVR-02: shared graphite foundation is in draft PR #90. Format/lint/typecheck/unit/build, Product E2E and Built Product/PRE_REAL J0-J9 passed; Browser Acceptance failed only the intentionally obsolete v0.5 Overview pixel golden. +- PVR-03: workspace-first shell is in draft PR #91 at exact head `d3bc4199c5047ba79c011052d48c2dbb5a67d898`. Repository Health, Repository Validation and Built Product/PRE_REAL are PASS. Browser Acceptance is 18/19 PASS with only the v0.5 Overview golden mismatch. +- PVR-04A/04B/05/06 started in parallel from that same validated PVR-03 head as draft PRs #92/#93/#94/#95. Shared tokens/primitives/AppShell are frozen across these branches. + ## PVR-00 — Baseline audit Audit basis: current PRE_REAL screenshots plus canonical shared styles/components and representative primary/secondary page styles (`AppShell`, `Metric`, `tokens`, `design-system`, `primitives`, Overview, Find best setup, Campaign, Run Detail and secondary/library surfaces). @@ -76,71 +85,75 @@ Audit basis: current PRE_REAL screenshots plus canonical shared styles/component ### Ownership conclusion -The visual debt is primarily shared-system debt, not independent page debt. PVR-02 must first replace the universal `surface_elevated + border + cyan` grammar with explicit surface depth, border strength, interaction and metric roles. Page slices must reuse that system rather than create local premium-looking cards. No new architecture or backend/read-model change is required by the audit. +The visual debt is primarily shared-system debt, not independent page debt. PVR-02 replaced the universal `surface_elevated + border + cyan` grammar with explicit surface depth, border strength, interaction and metric roles. Page slices must reuse that system rather than create local premium-looking cards. No new architecture or backend/read-model change is required by the audit. -Responsive behavior is structurally sound: compact breakpoints already collapse grids/navigation and long-content hardening exists. The refactor should preserve those behaviors and change content priority/composition rather than introduce a new mobile model. +Responsive behavior is structurally sound: compact breakpoints already collapse grids/navigation and long-content hardening exists. The refactor preserves those behaviors and changes content priority/composition rather than introducing a new mobile model. PVR-00 is complete. Current screenshots/goldens remain the intentional `before` reference and PRE_REAL remains the behavioral screenshot/trace owner during implementation. ## PVR-01 — Design contract v0.6 -Update `design/brand-kit.json` before implementation CSS. Preserve dark-only unless a separate product decision changes theme scope. +The v0.6 contract is implemented in `design/brand-kit.json` and synchronized semantic TypeScript tokens. Dark-only remains canonical. -Contract must define: +The contract defines: -- neutral canvas/surface/elevated/overlay hierarchy; -- subtle/strong border tokens rather than one universal border; +- neutral canvas/surface/elevated/raised hierarchy; +- subtle/default/strong border roles; - restrained accent plus semantic quality/performance/resources/status colors; - typography roles and weights, with tabular numerals for metrics; - compact control heights, radii and spacing rhythm; -- restrained multi-layer elevation for raised surfaces/overlays only; -- hover/focus/pressed/selected/disabled treatment; -- evidence-rail visual rules that never imply an invented normalized score; -- motion remains functional and reduced-motion safe; +- restrained elevation for raised surfaces/overlays only; +- interaction state rules; +- evidence visual-language constraints that forbid invented normalized scores; +- functional reduced-motion-safe motion; - no decorative gradients/glass/stock imagery in core workflows. -PVR-01 may proceed independently from the completed audit. PVR-02 does not start until the v0.6 contract is integrated. - ## PVR-02/03 — Shared foundation and shell -Primary owners: `frontend/src/design/tokens.css`, `design-system.css`, `primitives.css`, `foundation.css`, and canonical shared components (`Button`, `Metric`, `PageHeader`, `AppShell`, `Disclosure`, `DataTable`, status/feedback components). +PVR-02 owns `frontend/src/design/tokens.css`, `design-system.css`, `primitives.css`, `foundation.css` and canonical shared primitives. The v0.6 system now uses a neutral graphite canvas, quieter border hierarchy, compact controls, restrained accents and denser metric/table treatments. -Do not create page-specific replacements for semantic primitives already owned here. Shell refactor keeps routes and focus semantics unchanged while reducing sidebar prominence, removing repeated visual noise such as disabled `Pending` badges where a lower-noise treatment suffices, and making the workspace visually dominant. +PVR-03 owns `AppShell` and shell/navigation composition. Primary navigation remains always visible. Library and Settings use native progressive disclosure, are collapsed on primary workflows and auto-open on their active routes. Unimplemented secondary destinations remain visible and `aria-disabled`, but repeated visual `Pending` badges no longer compete with the workspace; unavailable reasons remain accessible. -## PVR-04..06 — Surface slices +Routes, skip navigation, route-focus behavior, secondary IA and domain semantics are unchanged. PVR-03 passed PRE_REAL J0-J9 and packaged J0/J1/J8/J9 before page slices started. -After PVR-02/03 integrate, these slices can proceed in parallel with non-overlapping page ownership. +## PVR-04..06 — Parallel surface slices -- **PVR-04A:** Overview, Find best setup, Campaign. Completed Campaign Results lead with the decision/best-fit evidence; progress dominates only while running. -- **PVR-04B:** Test a model, Live Run, Run Detail. Run Detail becomes an instrument panel: identity/status -> compact Q/P/R evidence -> evidence/configuration -> advanced detail. -- **PVR-05:** Runs, Compare, Benchmark Detail, Sample Evidence, Case Comparison. Exact evidence and compatibility remain stronger than decoration; tables win where exact comparison is the task. -- **PVR-06:** Library and Settings. Preserve secondary visual priority and progressive disclosure. +These branches all start from the same validated PVR-03 exact head and have disjoint page ownership. Shared design-system and shell owners are frozen unless a coordinated follow-up is explicitly required. + +- **PVR-04A / PR #92:** Overview, Find best setup, Campaign. Overview now gives tested-model evidence primary weight and recent runs secondary weight. Next: completed Campaign Results lead with decision/best-fit evidence; progress dominates only while running. +- **PVR-04B / PR #93:** Test a model, Live Run, Run Detail. Run Detail is being composed as an instrument panel: identity/status -> compact but separate Q/P/R evidence -> samples/evidence/configuration -> advanced reproducibility. +- **PVR-05 / PR #94:** Runs, Compare, Benchmark Detail, Sample Evidence, Case Comparison. Runs is becoming a compact technical evidence register. Exact evidence and compatibility stay stronger than decoration; tables win where exact comparison is the task. +- **PVR-06 / PR #95:** Library and Settings. Secondary pages use quieter canvas/table treatment and flatter advanced context while preserving secondary visual priority and progressive disclosure. ## Evidence language -Introduce a reusable visual treatment for evidence without changing semantics. A rail/marker may encode availability, trustworthy ranges, confidence or relative position only when the backend evidence supports that encoding. Unknown/unavailable/not-comparable never render as zero or as a shorter "bad" bar. Numeric comparison remains explicit. +A reusable evidence treatment may encode availability, trustworthy ranges, confidence or relative position only when backend evidence supports that encoding. Unknown/unavailable/not-comparable never render as zero or as a shorter "bad" bar. Numeric comparison remains explicit. No current page slice may invent a normalized cross-dimension score. ## PVR-07 — Premium-quality hardening Block completion on micro-polish that affects perceived quality and usability: accidental wrapping, inconsistent baselines, oversized CTAs, weak disabled states, noisy dividers, long-ID overflow, inconsistent disclosures, focus visibility, dense-table alignment, error/recovery, reduced motion and desktop adaptation. Add deterministic regression assertions when a defect is machine-checkable. +PVR-07 is also the reconciliation point for any page-specific visual pattern that appears in more than one parallel slice; shared ownership should be consolidated there rather than duplicated retroactively across active branches. + ## PVR-08/09 — Acceptance Do not incrementally bless intermediate screenshots as final goldens. Flow: -`current implementation -> before baseline -> approved v0.6 target -> implementation review -> accepted implementation golden`. +`v0.5 before baseline -> v0.6 implementation stack -> implementation review -> approved v0.6 target -> accepted implementation golden`. + +Keep the golden set bounded to high-value stable surfaces; J0-J9 PRE_REAL retains broader screenshot/trace coverage. PVR-08 is the first stage allowed to replace the accepted pixel goldens after the full v0.6 surface stack has been reviewed. -Keep the golden set bounded to high-value stable surfaces; J0-J9 PRE_REAL retains broader screenshot/trace coverage. Final acceptance requires current exact-head repository/browser/built-product gates, J0-J9 screenshot+trace evidence, packaged-product coverage, 1024/1280/1600 accessibility checks and representative-user review. Human/reference-grade claims remain pending until actually executed. +Final acceptance requires current exact-head repository/browser/built-product gates, J0-J9 screenshot+trace evidence, packaged-product coverage, 1024/1280/1600 accessibility checks and representative-user review. Human/reference-grade claims remain pending until actually executed. ## Integration strategy -1. Merge PVR-00 audit and PVR-01 visual contract; they own different artifacts and were developed in parallel. -2. PVR-02 changes shared design primitives only after the v0.6 contract is current on `dev`. -3. Merge PVR-02 then PVR-03 before page slices. -4. Run PVR-04A, PVR-04B, PVR-05 and PVR-06 in parallel with disjoint page ownership and shared primitives frozen unless a coordinated follow-up is required. -5. PVR-07 reconciles cross-surface polish and accessibility. -6. PVR-08 regenerates approved targets/goldens only from the final visual system. -7. PVR-09 reruns PRE_REAL and human acceptance, then transfers durable truth to `design/` and deletes this workstream by default. +1. PVR-00 is merged and owns the completed audit. +2. PVR-01, PVR-02 and PVR-03 are technically complete slices in one draft visual-refactor stack. They are not separately published while the accepted v0.5 pixel baseline intentionally disagrees with the v0.6 implementation. +3. PVR-04A, PVR-04B, PVR-05 and PVR-06 run in parallel from the same validated PVR-03 head with disjoint page ownership and shared primitives frozen. +4. PVR-07 reconciles the four page slices, owns cross-surface polish/accessibility and produces one coherent candidate implementation. +5. PVR-08 reviews that integrated implementation, records the approved v0.6 targets and replaces only the bounded pixel goldens that are intentionally obsolete. +6. Run `preflight-change` and all locally reproducible deterministic gates on the exact integrated head before making the stack publication-ready; CI confirms that evidence rather than discovering basic failures. +7. PVR-09 reruns PRE_REAL and human/reference-grade acceptance, transfers durable truth to `design/` / current-state docs and deletes this workstream by default when complete. ## Durable destinations @@ -152,4 +165,4 @@ Keep the golden set bounded to high-value stable surfaces; J0-J9 PRE_REAL retain ## Completion -DONE only when the product still answers the same evidence-backed decision correctly, the v0.6 visual system is consistently implemented, no page owns a competing design system, J0-J9 and packaged-product evidence remain green, accessibility/adaptive behavior agrees with the contract, and the final human review supports the premium/reference-grade claim. \ No newline at end of file +DONE only when the product still answers the same evidence-backed decision correctly, the v0.6 visual system is consistently implemented, no page owns a competing design system, J0-J9 and packaged-product evidence remain green, accessibility/adaptive behavior agrees with the contract, and the final human review supports the premium/reference-grade claim.