# ADR-0068: OSHUN Admin Severity And Queue State UI Behavior

- Status: Accepted
- Date: 2026-03-26

## Context

OSHUN Studio already exposed severity-oriented labels and queue status labels
across release governance, render-queue management, and background-job
operations, but those signals were not governed by one shared shell contract:

- launch-readiness dashboards styled blocker and incident severity locally
  instead of through one canonical severity grammar
- render-queue and background-job workspaces mixed queue posture, work progress,
  and escalation urgency into ad hoc pills
- the shell had no explicit rule preventing operators from collapsing severity
  and queue motion into one ambiguous label

The V1 TODO list explicitly requires the visual rules for admin severity and
queue states to be defined, and the Studio cockpit needs dense operational
signals to remain readable without turning every warning state into a dominant
banner.

## Decision

Publish one canonical admin-state behavior contract from
`libs/oshun/design-tokens/src/tokens.ts` and make the web shell consume it
through tokenized CSS variables, shared helper mappings, Studio inspection
surfaces, and representative governance and queue-management workspaces.

The shell contract is:

1. Separate impact from motion
   - severity communicates escalation impact and urgency, while queue state
     communicates operational posture and work progression

2. Label-first dense operator signaling
   - semantic color supports explicit language such as "Critical severity" or
     "Blocked queue" rather than replacing it

3. Restrained operational chrome
   - high-risk states can draw attention through rails, badges, and timer pills
     without flooding dense Studio surfaces with heavy fills

4. Blocking states require action language
   - blocked, failed, and critical states must read as intervention-oriented
     signals, not passive metadata

5. Success and terminal states stay subdued
   - healthy, completed, and canceled states should remain legible without
     competing with urgent operational work

## Consequences

- `oshun-v1-foundation` now includes an admin severity and queue-state behavior
  contract in addition to the existing core, domain-accent, grounded-evidence,
  disclosure, and trust-signal contracts.
- `apps/oshun/web/src/design-system/globals-v2.css` now defines shared admin
  tones plus summary-strip, inline-badge, row-rail, metric-pill, status-dot, and
  timer-pill variables.
- `apps/oshun/web/src/design-system/admin-states.ts` now provides the canonical
  web helper layer for severity normalization, queue-state normalization, and
  readable state summaries.
- Studio design-language tooling can now inspect severity states, queue states,
  and admin-surface role rules as first-class governed artifacts.
- Launch-readiness, render-queue, and background-job workspaces now consume one
  shell grammar instead of styling severity and queue indicators locally.

## Implementation

- Shared contract:
  - `libs/oshun/design-tokens/src/tokens.ts`
  - `libs/oshun/design-tokens/src/tokens.test.ts`
- Web adapter and CSS:
  - `apps/oshun/web/src/design-system/tokens.ts`
  - `apps/oshun/web/src/design-system/index.ts`
  - `apps/oshun/web/src/design-system/admin-states.ts`
  - `apps/oshun/web/src/design-system/globals-v2.css`
  - `apps/oshun/web/src/design-system/__tests__/tokens.test.ts`
  - `apps/oshun/web/src/design-system/__tests__/admin-states.test.ts`
- Representative Studio and governance surfaces:
  - `apps/oshun/web/src/components/studio/StudioDesignLanguageWorkspace.tsx`
  - `apps/oshun/web/src/components/studio/StudioLaunchReadinessGovernanceDashboard.tsx`
  - `apps/oshun/web/src/components/studio/StudioBellonaRenderQueueManagementWorkspace.tsx`
  - `apps/oshun/web/src/components/studio/StudioBackgroundJobsProgressUxWorkspace.tsx`
- Studio and browser verification:
  - `apps/oshun/web/src/components/__tests__/StudioDesignLanguageWorkspace.test.tsx`
  - `apps/oshun/web/src/components/__tests__/StudioLaunchReadinessGovernanceWorkspace.test.tsx`
  - `apps/oshun/web/src/components/__tests__/StudioBellonaRenderQueueManagementWorkspace.test.tsx`
  - `apps/oshun/web/src/components/__tests__/StudioBellonaRenderQueueManagementWorkspace.integration.test.tsx`
  - `apps/oshun/web/src/components/__tests__/StudioBackgroundJobsProgressUxWorkspace.test.tsx`
  - `apps/oshun/web/e2e/studio-design-language-smoke.spec.ts`
  - `apps/oshun/web/e2e/studio-launch-readiness-governance-smoke.spec.ts`
  - `apps/oshun/web/e2e/studio-bellona-render-queue-management-smoke.spec.ts`
  - `apps/oshun/web/e2e/studio-background-jobs-progress-ux-smoke.spec.ts`

## Verification

This slice is complete when:

1. shared design-token tests pass
2. targeted web admin-state helper, Studio, and queue/governance tests pass
3. targeted eslint passes for the changed shared, web, and e2e files
4. Playwright verifies Studio admin-state governance plus live launch,
   render-queue, and background-job surfaces