Disciplines · Decisions (ADRs)

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

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.

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