Disciplines · Decisions (ADRs)

ADR-0071: OSHUN Review And Approval State UI Behavior

OSHUN Studio already had deterministic review and approval workflow logic, but its visual treatment was still fragmented.

5sections3 minread
Markdown source
On this page
  • Status: Accepted
  • Date: 2026-03-26

Context#

OSHUN Studio already had deterministic review and approval workflow logic, but its visual treatment was still fragmented. Review-package cards, Bellona collaboration approvals, and production signoff surfaces were using local copy and ad-hoc status styling rather than one shared rule set.

That created three practical risks:

  • pending, in-review, changes-requested, rejected, escalated, and approved exception states could collapse into ambiguous local badges
  • clean approvals could look too similar to escalations or exception-based waivers
  • authority, rationale, waiver evidence, or governance tagging could drift away from the visible state and become audit-only metadata

The V1 TODO list explicitly requires the visual rules for review and approval states to be defined. Existing implementation review and external governance patterns also pointed to one stable requirement: workflow posture must stay visually distinct from final decision, and exception/escalation states must not read like clean approvals.

Decision#

Publish one canonical review-and-approval behavior contract from libs/oshun/design-tokens/src/tokens.ts and make the web shell consume it through shared CSS variables, a shared normalization helper, representative Studio governance previews, the review/approval workspace, and Bellona collaboration/signoff surfaces.

The shell contract is:

  1. Workflow posture stays separate from decision

    • pending and in-review describe queue posture; approved, changes requested, rejected, and approved exception describe explicit outcomes

  2. Authority and evidence stay adjacent

    • owner, requester, CAB/waiver context, governance tagging, or rationale stay on the same surface as the state

  3. Changes requested stays recoverable

    • remediation states must read as explicit rework, not silent failure or hidden metadata

  4. Escalation and exception stay distinct

    • escalated and approved-exception states use visibly different treatment from clean approvals so authority transfer and waivers remain obvious

  5. Final decision remains visible

    • once a decision exists, it stays visible on cards and signoff summaries instead of disappearing into audit history

Consequences#

  • oshun-v1-foundation now includes a review-and-approval behavior contract alongside the existing domain-accent, grounded-evidence, disclosure, assistant-persona-switching, avatar/voice-identity, trust-signal, and admin-state contracts.
  • apps/oshun/web/src/design-system/globals-v2.css now defines shared review/approval tones plus summary-strip, state-chip, decision-chip, lifecycle-card, evidence-note, and timeline-rail variables.
  • apps/oshun/web/src/design-system/review-approval-states.ts now provides the canonical web helper layer for state labels, descriptions, tone mapping, and normalization of workflow posture versus final decision.
  • apps/oshun/web/src/components/studio/StudioReviewApprovalWorkflowsWorkspace.tsx now renders selected-package summaries plus tokenized lifecycle cards and adjacent governance evidence instead of local inline chip styling.
  • apps/oshun/web/src/components/studio/StudioBellonaRenderQueueManagementWorkspace.tsx now renders collaboration approval and production signoff through the same governed review/approval grammar.
  • apps/oshun/web/src/components/studio/StudioDesignLanguageWorkspace.tsx now exposes the full review/approval state gallery and role summary for design governance review.

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/review-approval-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__/review-approval-states.test.ts
  • Representative Studio surfaces:
    • apps/oshun/web/src/components/studio/StudioDesignLanguageWorkspace.tsx
    • apps/oshun/web/src/components/studio/StudioReviewApprovalWorkflowsWorkspace.tsx
    • apps/oshun/web/src/components/studio/StudioBellonaRenderQueueManagementWorkspace.tsx
  • Web and browser verification:
    • apps/oshun/web/src/components/__tests__/StudioDesignLanguageWorkspace.test.tsx
    • apps/oshun/web/src/components/__tests__/StudioReviewApprovalWorkflowsWorkspace.test.tsx
    • apps/oshun/web/src/components/__tests__/StudioBellonaRenderQueueManagementWorkspace.test.tsx
    • apps/oshun/web/e2e/studio-design-language-smoke.spec.ts
    • apps/oshun/web/e2e/studio-review-approval-workflows-smoke.spec.ts
    • apps/oshun/web/e2e/studio-bellona-render-queue-management-smoke.spec.ts

Verification#

This slice is complete when:

  1. shared design-token tests pass
  2. targeted web review/approval helper and Studio tests pass
  3. targeted eslint passes for the changed shared and web source files
  4. Playwright verifies design-language, review/approval, and Bellona signoff surfaces with the shared review/approval grammar