# OSHUN V1 Admin Visual Thesis

Status: Accepted v1.0  
Owner: OSHUN Design + Product + Engineering  
Last Updated: March 26, 2026  
Implements: `V1-UX-046`  
Related:

- `docs/releases/v1/specs/web-app-admin-v1-prd.md`
- `docs/releases/v1/specs/program-charter.md`
- `docs/releases/v1/specs/studio-design-language-user-journeys-and-edge-cases.md`
- `docs/releases/v1/specs/studio-spacing-layout-user-journeys-and-edge-cases.md`
- `libs/oshun/navigation/src/platform-shells.ts`
- `libs/oshun/design-tokens/src/tokens.ts`
- `apps/oshun/web/src/design-system/admin-states.ts`

## 1. Purpose

This document defines the canonical visual thesis for OSHUN Admin across:

- admin web and Studio workspaces
- privileged review, governance, and operations surfaces
- admin mobile urgent-action posture
- queue, incident, policy, and evidence-heavy workflows

This thesis is the operator-side design filter for OSHUN V1. If an admin surface
looks modern but does not feel operator-grade, information-dense, low-noise,
ergonomic, and trustworthy under long sessions, it is off-thesis.

## 2. Scope and Acceptance

This task is complete when all admin redesign work can answer these questions
with a clear yes:

- Can an operator scan the screen and understand state, urgency, and next action
  in seconds?
- Does the layout hold dense evidence without collapsing into clutter?
- Can the operator remain in context instead of opening a chain of secondary
  views to understand one decision?
- Does urgency read clearly without turning the entire interface into alarm
  chrome?
- Would the workspace still feel credible and efficient after hours of use?

## 3. Inputs Reviewed

Internal implementation and product inputs reviewed before defining the thesis:

- `docs/releases/v1/specs/web-app-admin-v1-prd.md` for the admin web cockpit and
  admin mobile urgent-actions model
- `docs/releases/v1/specs/program-charter.md` for admin launch-critical posture
  and keyboard-first operator expectations
- `docs/releases/v1/specs/studio-design-language-user-journeys-and-edge-cases.md`
  for reviewable, auditable visual-governance workflows
- `docs/releases/v1/specs/studio-spacing-layout-user-journeys-and-edge-cases.md`
  for dense operational ergonomics and deterministic responsive behavior
- `libs/oshun/navigation/src/platform-shells.ts` for the explicit admin-shell
  boundary and operator-cockpit role
- `apps/oshun/web/src/components/studio/StudioInformationArchitectureWorkspace.tsx`
  and `apps/oshun/web/src/components/studio/StudioDesignLanguageWorkspace.tsx`
  for the current Studio execution and governance posture
- `apps/oshun/web/src/design-system/admin-states.ts` and
  `libs/oshun/design-tokens/src/tokens.ts` for shared severity, queue, and
  governance signal grammar

Comparative operator reference patterns reviewed:

- Linear: keyboard-first navigation, fast list scanning, quick preview, and
  low-noise sidebar command structure
- Stripe Dashboard and Workbench: embedded diagnostics, resize/minimize flows,
  evidence-rich logs, and operator tooling that stays inside one cockpit

These references inform interaction posture and density discipline only. OSHUN
must not copy their brand, layout cosmetics, or product metaphors.

## 4. Canonical Thesis

### 4.1 One-Sentence Thesis

OSHUN Admin should feel like an air-traffic control room for governed
intelligence work: operator-grade and information-dense, but calm enough to
support judgment, low-noise enough to preserve scan speed, ergonomic enough for
long sessions, and trustworthy because evidence and authority stay visible.

### 4.2 Short Canonical Form

Use the following short form wherever a compact metadata field, design-system
constant, or governance label is required:

> Operator-grade, low-noise cockpits with dense evidence, durable context, and
> keyboard-first ergonomics.

## 5. Core Experience Promises

### 5.1 Evidence Before Action

Admin surfaces should let operators act with context, not memory.

- Every high-impact action should sit near the evidence that justifies it.
- Approval, escalation, and rollback flows should keep rationale, provenance,
  and policy posture in view.
- Operators should not have to reconstruct history from multiple tabs.

### 5.2 Density Without Clutter

Admin surfaces must carry more information than customer surfaces without
looking messy.

- Density comes from structured hierarchy, not tiny text everywhere.
- Tables, split panes, queue rows, and side inspectors should compress well.
- Repetition of cards, banners, and decorative containers weakens scan speed.

### 5.3 Calm Urgency

Admin work includes failure, risk, and escalation, but the workspace must not
feel like a permanent incident page.

- Color should identify severity, not flood the canvas.
- Critical states should be unmistakable and local, not atmospheric.
- Operators should be able to stay in judgment mode during sustained workload.

### 5.4 Durable Context

The operator should always know what artifact, policy, queue, or incident they
are acting on.

- Primary context should remain pinned in headers, inspectors, or sticky rails.
- Cross-domain dependencies should be visible as linked system context, not
  hidden implementation trivia.
- Handoffs and delegated approvals should preserve state and ownership.

### 5.5 Long-Session Ergonomics

Admin sessions are often extended and repetitive.

- Keyboard-first flows should exist for navigation, triage, search, and action.
- Repeated actions should minimize pointer travel and avoid modal thrash.
- Visual rhythm should reduce fatigue across long review sessions.

## 6. Visual Grammar

### 6.1 Canvas

- Default admin mood: neutral, disciplined, operational, and stable.
- The canvas should feel lighter and flatter than customer atmosphere-heavy
  shells.
- Background treatment must support focus, not identity signaling.

### 6.2 Hierarchy

- Use strong section titles, utility copy, and persistent metadata runs.
- Summaries should front-load state, owner, queue posture, time risk, and next
  action.
- Long-detail surfaces should separate overview, evidence, and controls without
  forcing page hopping.

### 6.3 Surfaces and Layout

- Prefer split panes, queue rows, inspectors, sticky summaries, and evidence
  rails over dashboard-card mosaics.
- Cards are allowed when the card itself is the unit of review or action.
- Repetitive boxed tiles for routine admin metrics are off-thesis unless each
  tile carries a genuinely different decision job.

### 6.4 Color and State

- Color is primarily for queue state, severity, blockers, trust, and completion.
- Severity should read from controlled accents, pills, rails, and focused bands.
- Full-screen warning color, especially red, is prohibited except in explicit
  takeover states.

### 6.5 Typography

- Typography should prioritize speed, comparability, and legibility.
- Dense operational views may use smaller type than customer surfaces, but not
  at the cost of fatigue or ambiguity.
- Headings must orient. Labels must disambiguate. Metadata must stay readable.

### 6.6 Motion

- Motion should confirm state transitions, expansion, handoff, and recovery.
- Admin motion must be shorter and drier than customer motion.
- Decorative entrances and theatrical transitions are off-thesis on operator
  surfaces.

## 7. Admin Mobile Posture

Admin mobile is not a miniature desktop cockpit. It is the urgent-action
companion.

- Surface only the highest-priority approvals, escalations, and incident
  updates.
- Lead with severity, owner, due window, and recommended action.
- Defer deep evidence exploration to web when that preserves accuracy and speed.
- Mobile layouts should assume interruption, on-call context, and one-handed
  operation.

## 8. Anti-Goals

The following are explicitly off-thesis:

- consumer-style hero banners on operator surfaces
- dashboard-card sprawl used where rows, panes, or inspectors would scan faster
- permanent red/orange atmosphere that induces alert fatigue
- hidden critical context behind several clicks or collapsible traps
- oversaturated accent systems that compete with severity and queue state
- glossy motion, parallax, or ornamental gradients in routine workflows
- modal-heavy workflows that fragment review context and force repeated
  reorientation

## 9. Review Questions

Any admin redesign should be reviewed against these checks:

- Can an experienced operator complete the top three actions from keyboard and
  pointer without hunting?
- Is the loudest thing on screen the most operationally important thing?
- Does the surface preserve evidence, ownership, and timing context near the
  decision?
- Are severity and queue signals visible without polluting unrelated regions?
- After ten minutes in the workspace, does the interface still feel stable and
  trustworthy rather than busy?

## 10. Implementation Contract

The short canonical form in section 4.2 must stay synchronized with:

- `libs/oshun/design-tokens/src/tokens.ts`
- any shared design-system exports that expose the admin thesis to Studio or web
  implementation layers

If the thesis changes, the constant and this document must be updated in the
same change.
