Eve library

OSHUN V1 Admin Visual Thesis

Guide

Revision 1

On this page

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.