Status: Accepted v1.0
Owner: OSHUN Design + Product + Engineering
Last Updated: March 26, 2026
Implements: V1-UX-055
Related:
docs/releases/v1/specs/surface-redesign-ranking.mddocs/releases/v1/specs/experience-scorecards.mddocs/releases/v1/scope/minimal-chrome-rules.mddocs/releases/v1/specs/layout-density-tiers.mddocs/releases/v1/scope/scan-first-content-hierarchy-rules.mddocs/releases/v1/specs/todos.md
1. Purpose#
This document defines the redesign sequencing plan for OSHUN V1 so the highest-impact UI overhauls ship before lower-value polish.
The principle is simple:
- do shared launch-critical rules before route-specific redesign
- do shared primitives before duplicating route-local UI
- do
P0surfaces beforeP1polish - do audits only after the thing being audited actually exists
Numeric backlog order is not sufficient on its own. The remaining UX work needs wave ordering.
2. What Is Already Complete#
The current foundation layer is already in place:
V1-UX-011throughV1-UX-019V1-UX-045throughV1-UX-054
That means the program now has:
- token foundations
- domain accent behavior
- grounded evidence, disclosure, trust, queue, persona, avatar, and review state rules
- customer and admin visual theses
- surface inventory, ranking, scorecards
- minimal chrome, density, hierarchy, ergonomics, and posture rules
The redesign sequence below starts from that completed baseline.
3. Canonical Sequencing Rule#
Follow this order:
- launch guardrails
- shared primitives
P0customer and admin surface redesignsP1and specialist polish- audit, QA, and release gates
Any task that does not help one of those phases should not jump ahead of a blocked earlier phase.
4. Wave Plan#
4.1 Wave 1: Launch Guardrails And Structural Rules#
Objective:
- finish the remaining shared rules that every redesign wave depends on
Tasks:
V1-UX-020partial failure and degraded modeV1-UX-056grid, gutter, max-width behaviorV1-UX-057typography measure and reading rhythmV1-UX-058imagery, illustration, texture, ambient media rulesV1-UX-059card-avoidance rulesV1-UX-060motion hierarchyV1-UX-061loading, skeleton, empty, offline, and error statesV1-UX-062action-placement rulesV1-UX-063interaction-feedback rulesV1-UX-034accessibility standards for shared componentsV1-UX-035reduced-motion behaviorV1-UX-068contrast and focus-indicator rulesV1-UX-073mandatory design-review checklistV1-UX-074Playwright-backed visual QA checklist
Why this wave comes first:
- customer and admin overhauls should not start before layout, state, motion, action-placement, and QA rules exist
- these tasks prevent route-local redesign drift
- they also define the acceptance bar for later implementation
4.2 Wave 2: Shared Launch-Critical Primitives#
Objective:
- build the reusable components that unlock multiple
P0surfaces at once
Tasks:
V1-UX-021domain switcher componentsV1-UX-023evidence card and evidence sidebarV1-UX-026assistant disclosure and memory-state componentsV1-UX-028admin queue row and queue filter componentsV1-UX-029incident severity and SLA timer componentsV1-UX-030review decision controls
Second-tier primitives inside the same phase, after the first group is stable:
V1-UX-022continuity cardsV1-UX-024claim, source, and passage list itemsV1-UX-025notebook and collection componentsV1-UX-027provenance badgesV1-UX-031policy-edit and policy-diff componentsV1-UX-032avatar and voice pack cardsV1-UX-033rights and license summary components
Why this wave comes second:
- the
P0shell, home, evidence, assistant, queue, incident, and approval redesigns all depend on these primitives - building them once avoids route-local duplication and inconsistent QA burden
4.3 Wave 3: P0 Customer Surface Overhauls#
Objective:
- redesign the highest-impact customer experience surfaces first
Primary surfaces:
- shared shell chrome and persistent overlays
- home dashboard
- onboarding
- domain route experience
- assistant, continuity, and disclosure surfaces
- global loading, degraded, error, and not-found states
Secondary P0 customer surface in the same wave once the above are stabilizing:
- explore and discovery
Why this order:
- shell, home, onboarding, domain route, and assistant posture define the core customer experience
- global degraded/error behavior must land during the same wave, not after
- explore is critical, but it benefits from the shell and state rules settling first
4.4 Wave 4: P0 Admin Cockpit Overhauls#
Objective:
- raise the operator cockpit to launch-grade after the shared operator primitives exist
Primary surfaces:
- explicit admin shell boundary and operator chrome
- Studio root cockpit directory
- identity, access, and policy cluster
- review, audit, notification, and retention cluster
- reliability, incident, and launch-readiness cluster
Why this is after Wave 2:
- these surfaces depend directly on queue rows, incident severity, review controls, policy diffing, and shared feedback/state rules
- admin quality should be built on reusable operator primitives, not bespoke cockpit fragments
4.5 Wave 5: P1 Surfaces, Tone, And Specialist Ergonomics#
Objective:
- complete the second layer of quality once the launch-critical surfaces are structurally correct
Tasks:
V1-UX-036Tara-led content tone standardsV1-UX-037Veritas grounded tone standardsV1-UX-038Nisaba scholarly tone standardsV1-UX-039AI disclosure copy guidanceV1-UX-040error and fallback copy guidanceV1-UX-064one-handed mobile ergonomics rulesV1-UX-065dense-data ergonomics for admin tables and compare viewsV1-UX-066form-entry ergonomicsV1-UX-067copy-compression rules
Surface polish focus:
- search
- activity
- library
- profile
- public domain marketing
- download/install
- integration and composition admin cluster
- design-system and navigation-governance specialist workspaces
Why this wave is later:
- these tasks matter, but they should refine a stable core rather than define it
- tone and specialist ergonomics are most valuable after the primary surface model exists
4.6 Wave 6: Audits, QA, And Launch Signoff#
Objective:
- prove the redesign actually meets the bar
Tasks:
V1-UX-041two-taps-to-value auditV1-UX-042one-handed reachability auditV1-UX-043calm visual rhythm auditV1-UX-044keyboard and focus-path auditV1-UX-069dashboard-card sprawl auditV1-UX-070long-form readability auditV1-UX-071viewport-fit auditV1-UX-072progressive disclosure audit
Persistent release controls from earlier wave outputs:
V1-UX-073design-review checklistV1-UX-074Playwright-backed visual QA checklist
Why this is last:
- audits should validate implemented redesigns, not placeholders
- these tasks become the launch gate once the major surfaces are redesigned
5. Explicit Priority Rules#
5.1 Do Not Jump Ahead To Polish#
These should not move ahead of launch-critical surface work:
- specialist imagery polish
- secondary profile or library refinement
- late specialist admin family polish
- audit-only work before the redesigned surfaces exist
5.2 Do Not Build Primitives Before Their Rule Set#
Component work should not start before its rule layer is available.
Examples:
- queue-row primitives should follow action-placement, interaction-feedback, and degraded-state rules
- domain switchers should follow grid, chrome, and hierarchy rules
- evidence and notebook primitives should follow reading-rhythm and density guidance
5.3 Do Not Audit The Old Product And Call It Done#
Audit tasks are not substitutes for redesign implementation.
The required sequence is:
- define the rule
- build the primitive
- redesign the surface
- audit and verify it
6. Dependency View#
| Depends on | Enables |
|---|---|
V1-UX-020, 056-063, 034-035, 068, 073-074 |
all major customer and admin redesign waves |
V1-UX-021, 023, 026, 028-030 |
shell, evidence, assistant, queue, incident, and approval redesigns |
completed V1-UX-045-054 foundation docs |
all remaining UX implementation and audit work |
P0 customer/admin redesign implementation |
meaningful completion of audit tasks 041-044, 069-072 |
7. Recommended Execution Order From Today#
From the current backlog state, the recommended next-order execution is:
V1-UX-020V1-UX-056throughV1-UX-063V1-UX-034,V1-UX-035,V1-UX-068,V1-UX-073,V1-UX-074V1-UX-021,V1-UX-023,V1-UX-026,V1-UX-028,V1-UX-029,V1-UX-030P0customer surface redesign implementationP0admin surface redesign implementation- remaining reusable components and
P1surface refinement - audit and launch signoff tasks
8. Exit Standard#
The sequence is being followed correctly only when:
- shared rules appear before shared primitives
- shared primitives appear before route-local duplication
P0shells and core surfaces land beforeP1polish- audits are used as signoff, not as delay camouflage
If the team is polishing a lower-value surface while a P0 shell, queue,
assistant, onboarding, or degraded-state dependency remains unresolved, the
sequence has broken.