# ADR-0070: OSHUN Avatar And Voice Identity Indicator UI Behavior

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

## Context

OSHUN already had disclosure rules that mark AI identity, memory state, and
synthetic voice/avatar presence, plus persona-switching rules that keep the
active guide visible. It did not yet have one shared rule set for how the named
voice profile or avatar pack itself should stay visible once embodied media is
linked, previewed, or live.

That gap created three risks:

- disclosure could say synthetic voice or synthetic avatar without naming which
  synthetic asset is active
- persona name, voice profile, and avatar pack could collapse into one ambiguous
  label with no modality or readiness context
- live, preview, partial-pack, and blocked embodied states could look too
  similar even though attribution and readiness risk differ

The V1 TODO list explicitly requires the visual rules for avatar/voice identity
indicators to be defined. Review of current live-voice and avatar product
patterns also showed a stable expectation: named synthetic identity stays on the
active surface, live sessions escalate that identity signal, and
rollout/readiness context remains adjacent instead of hidden in settings.

## Decision

Publish one canonical avatar-and-voice-identity behavior contract from
`libs/oshun/design-tokens/src/tokens.ts` and make the web shell consume it
through shared CSS variables, a shared identity helper, representative
assistant-shell UI, and Studio governance previews.

The shell contract is:

1. Named synthetic identity stays visible
   - the surface names the actual voice profile or avatar pack in use rather
     than relying on generic synthetic-media language alone

2. Persona and asset stay paired
   - the linked persona label stays adjacent to the voice/avatar asset label so
     users and operators can see whose embodied pack is active

3. Live sessions escalate identity
   - active voice or avatar sessions promote identity into a persistent summary
     strip or live pill because mistaken human attribution risk rises while the
     medium is active

4. Readiness stays adjacent
   - language, quality, preview scope, partial-pack state, or block reason stay
     on the same surface as the identity label

5. Disclosure remains a companion signal
   - identity indicators complement AI/synthetic disclosure and do not replace
     it

## Consequences

- `oshun-v1-foundation` now includes an avatar-and-voice-identity behavior
  contract alongside the existing domain-accent, grounded-evidence, disclosure,
  assistant-persona-switching, trust-signal, and admin-state contracts.
- `apps/oshun/web/src/design-system/globals-v2.css` now defines shared
  identity-indicator tones plus summary-strip, identity-chip, live-pill,
  asset-card, lineage-note, and marker variables.
- `apps/oshun/web/src/design-system/avatar-voice-identity.ts` now provides the
  canonical web helper layer for named voice/avatar identity collections, shared
  state labels, live-state escalation, and assistant voice resolution.
- `apps/oshun/web/src/components/assistant/AssistantPanel.tsx` now keeps the
  named synthetic voice identity visible next to disclosure and persona state.
- Studio design-language, Isis text-to-speech, and Aja avatar-preview workspaces
  now expose the same governed identity grammar for review rather than inventing
  local pack/voice badges.

## 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/avatar-voice-identity.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__/avatar-voice-identity.test.ts`
- Representative assistant and Studio surfaces:
  - `apps/oshun/web/src/components/assistant/AssistantPanel.tsx`
  - `apps/oshun/web/src/components/studio/StudioDesignLanguageWorkspace.tsx`
  - `apps/oshun/web/src/components/studio/StudioIsisTextToSpeechWorkspace.tsx`
  - `apps/oshun/web/src/components/studio/StudioAjaAvatarPreviewUiWorkspace.tsx`
- Web and browser verification:
  - `apps/oshun/web/src/components/assistant/__tests__/AssistantPanel.test.tsx`
  - `apps/oshun/web/src/components/__tests__/StudioDesignLanguageWorkspace.test.tsx`
  - `apps/oshun/web/src/components/__tests__/StudioIsisTextToSpeechWorkspace.test.tsx`
  - `apps/oshun/web/src/components/__tests__/StudioAjaAvatarPreviewUiWorkspace.test.tsx`
  - `apps/oshun/web/e2e/assistant-continuity-journey.spec.ts`
  - `apps/oshun/web/e2e/studio-design-language-smoke.spec.ts`
  - `apps/oshun/web/e2e/studio-isis-text-to-speech-smoke.spec.ts`
  - `apps/oshun/web/e2e/studio-aja-avatar-preview-ui-smoke.spec.ts`

## Verification

This slice is complete when:

1. shared design-token tests pass
2. targeted web identity-helper, assistant-shell, and Studio tests pass
3. targeted eslint passes for the changed shared and web source files
4. Playwright verifies assistant continuity plus Studio design-language,
   text-to-speech, and avatar-preview identity governance surfaces