Disciplines · Decisions (ADRs)

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

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:

5sections3 minread
Markdown source
On this page
  • 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