# OSHUN V1 Redesign Sequencing Plan

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.md`
- `docs/releases/v1/specs/experience-scorecards.md`
- `docs/releases/v1/scope/minimal-chrome-rules.md`
- `docs/releases/v1/specs/layout-density-tiers.md`
- `docs/releases/v1/scope/scan-first-content-hierarchy-rules.md`
- `docs/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 `P0` surfaces before `P1` polish
- 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-011` through `V1-UX-019`
- `V1-UX-045` through `V1-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:

1. launch guardrails
2. shared primitives
3. `P0` customer and admin surface redesigns
4. `P1` and specialist polish
5. 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-020` partial failure and degraded mode
- `V1-UX-056` grid, gutter, max-width behavior
- `V1-UX-057` typography measure and reading rhythm
- `V1-UX-058` imagery, illustration, texture, ambient media rules
- `V1-UX-059` card-avoidance rules
- `V1-UX-060` motion hierarchy
- `V1-UX-061` loading, skeleton, empty, offline, and error states
- `V1-UX-062` action-placement rules
- `V1-UX-063` interaction-feedback rules
- `V1-UX-034` accessibility standards for shared components
- `V1-UX-035` reduced-motion behavior
- `V1-UX-068` contrast and focus-indicator rules
- `V1-UX-073` mandatory design-review checklist
- `V1-UX-074` Playwright-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 `P0` surfaces at once

Tasks:

- `V1-UX-021` domain switcher components
- `V1-UX-023` evidence card and evidence sidebar
- `V1-UX-026` assistant disclosure and memory-state components
- `V1-UX-028` admin queue row and queue filter components
- `V1-UX-029` incident severity and SLA timer components
- `V1-UX-030` review decision controls

Second-tier primitives inside the same phase, after the first group is stable:

- `V1-UX-022` continuity cards
- `V1-UX-024` claim, source, and passage list items
- `V1-UX-025` notebook and collection components
- `V1-UX-027` provenance badges
- `V1-UX-031` policy-edit and policy-diff components
- `V1-UX-032` avatar and voice pack cards
- `V1-UX-033` rights and license summary components

Why this wave comes second:

- the `P0` shell, 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-036` Tara-led content tone standards
- `V1-UX-037` Veritas grounded tone standards
- `V1-UX-038` Nisaba scholarly tone standards
- `V1-UX-039` AI disclosure copy guidance
- `V1-UX-040` error and fallback copy guidance
- `V1-UX-064` one-handed mobile ergonomics rules
- `V1-UX-065` dense-data ergonomics for admin tables and compare views
- `V1-UX-066` form-entry ergonomics
- `V1-UX-067` copy-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-041` two-taps-to-value audit
- `V1-UX-042` one-handed reachability audit
- `V1-UX-043` calm visual rhythm audit
- `V1-UX-044` keyboard and focus-path audit
- `V1-UX-069` dashboard-card sprawl audit
- `V1-UX-070` long-form readability audit
- `V1-UX-071` viewport-fit audit
- `V1-UX-072` progressive disclosure audit

Persistent release controls from earlier wave outputs:

- `V1-UX-073` design-review checklist
- `V1-UX-074` Playwright-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:

1. define the rule
2. build the primitive
3. redesign the surface
4. 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:

1. `V1-UX-020`
2. `V1-UX-056` through `V1-UX-063`
3. `V1-UX-034`, `V1-UX-035`, `V1-UX-068`, `V1-UX-073`, `V1-UX-074`
4. `V1-UX-021`, `V1-UX-023`, `V1-UX-026`, `V1-UX-028`, `V1-UX-029`, `V1-UX-030`
5. `P0` customer surface redesign implementation
6. `P0` admin surface redesign implementation
7. remaining reusable components and `P1` surface refinement
8. 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
- `P0` shells and core surfaces land before `P1` polish
- 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.
