# ADR-0071: OSHUN Review And Approval State UI Behavior

- 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