Disciplines · Decisions (ADRs)

ADR-0066: OSHUN Disclosure And Synthetic Indicator UI Behavior

OSHUN already had roadmap and PRD requirements around explicit AI identity, memory-state visibility, disclosure overlays, and synthetic voice/avatar signaling, but the visual behavior was not yet governed by one shared contract:

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

Context#

OSHUN already had roadmap and PRD requirements around explicit AI identity, memory-state visibility, disclosure overlays, and synthetic voice/avatar signaling, but the visual behavior was not yet governed by one shared contract:

  • the global assistant shell did not expose a persistent disclosure grammar for AI identity and memory scope
  • synthetic voice and avatar surfaces had no shared shell-level indicator model
  • Studio design-language tooling could inspect core foundation tokens, domain accents, and grounded evidence behavior, but not disclosure behavior itself

The V1 TODO list explicitly requires the visual rules for disclosure and synthetic indicators to be defined, and the admin PRD requires users to always know when they are speaking with AI, what memory is active, and when voice or avatar output is synthetic.

Decision#

Publish one canonical disclosure-and-synthetic-indicator behavior contract from libs/oshun/design-tokens/src/tokens.ts and make the web shell consume it through tokenized CSS variables, disclosure helpers, Studio inspection surfaces, the global assistant shell, and representative avatar/text-to-speech governance surfaces.

The shell contract is:

  1. Explicit identity

    • every assistant or generated experience clearly states that the experience is AI-mediated before it can be mistaken for a human interaction

  2. Visible memory scope

    • disclosure copy always resolves memory to explicit states such as memory off, session memory, or profile memory

  3. Synthetic modality signals

    • synthetic voice, avatar, and generated-media states stay visible on the active surface rather than living only in settings or documentation

  4. Embodied-session escalation

    • voice and avatar sessions escalate from compact chips to persistent overlays because mistaken human attribution is a higher-risk failure mode

  5. Plain-language companion copy

    • compact indicators always pair with short readable text explaining what is synthetic and what memory scope is active

Consequences#

  • oshun-v1-foundation now includes a disclosure behavior contract in addition to the existing core, domain-accent, and grounded-evidence contracts.
  • apps/oshun/web/src/design-system/globals-v2.css now defines shared disclosure tones, indicator colors, persistent-strip, inline-chip, and session-overlay variables.
  • apps/oshun/web/src/design-system/disclosure.ts now provides the canonical web helper layer for disclosure labels, descriptions, and assistant disclosure state derivation.
  • Studio design-language tooling can now inspect disclosure indicators and role rules as first-class governed artifacts.
  • The global assistant shell and representative avatar/TTS Studio surfaces now consume the same disclosure grammar instead of styling disclosure locally or omitting it entirely.

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

Verification#

This slice is complete when:

  1. shared design-token tests pass
  2. targeted web disclosure, assistant, and Studio tests pass
  3. targeted eslint passes for the changed shared, web, and e2e files
  4. Playwright verifies Studio disclosure governance plus live assistant/avatar/TTS disclosure surfaces