Disciplines · Decisions (ADRs)

ADR-0069: OSHUN Assistant Persona Switching UI Behavior

OSHUN already had disclosure rules for AI identity, memory state, and synthetic voice/avatar indicators, plus a continuity rail for assistant handoff.

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

Context#

OSHUN already had disclosure rules for AI identity, memory state, and synthetic voice/avatar indicators, plus a continuity rail for assistant handoff. It did not yet have one shared rule set for how persona switching itself should read across the assistant shell and Studio governance previews.

That gap created three risks:

  • persona identity could be implied by tone or domain badge instead of stated explicitly
  • persona selection could be confused with disclosure or memory-state visibility
  • preview or restricted personas could disappear silently instead of explaining why they are gated

The V1 TODO list explicitly requires the visual rules for assistant persona switching to be defined. Research into current assistant control patterns also showed a stable expectation: the active mode or guide should remain visible, alternatives should stay inspectable, and unavailable choices should explain their gate rather than behaving like broken controls.

Decision#

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

The shell contract is:

  1. Active identity stays visible

    • the current persona remains visible in the assistant header or summary surface at all times

  2. Continuity is preserved by default

    • persona switching keeps the current thread, disclosure strip, and memory scope unless a later policy/runtime layer explicitly requires a break

  3. Persona is not disclosure

    • persona choice is a guidance lens and must not replace AI identity, memory-state, or synthetic modality indicators

  4. Domain affinity guides but does not lock

    • the current domain can elevate a recommended persona, but the broader catalog stays visible so the user knows a deliberate switch is happening

  5. Gated states need reasons

    • preview and restricted personas must explain why they are limited or unavailable in the current surface

Consequences#

  • oshun-v1-foundation now includes an assistant-persona-switching behavior contract alongside the existing domain-accent, grounded-evidence, disclosure, trust-signal, and admin-state contracts.
  • apps/oshun/web/src/design-system/globals-v2.css now defines shared persona tones plus switcher-rail, persona-card, compact-chip, active-summary, continuity-note, state-badge, and accent-bar variables.
  • apps/oshun/web/src/design-system/assistant-persona-switching.ts now provides the canonical web helper layer for default persona resolution, state mapping, and continuity-safe switcher summaries.
  • apps/oshun/web/src/components/assistant/AssistantPanel.tsx now keeps the active persona explicit while rendering recommended, preview, and restricted persona options inside the global assistant shell.
  • Studio design-language and Isis text-to-speech workspaces now expose the same governed persona grammar for review rather than inventing local persona cards.

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/assistant-persona-switching.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__/assistant-persona-switching.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
  • 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__/StudioIsisTextToSpeechWorkspace.integration.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

Verification#

This slice is complete when:

  1. shared design-token tests pass
  2. targeted web persona-switching, assistant-shell, and Studio tests pass
  3. targeted eslint passes for the changed shared and web source files
  4. Playwright verifies assistant persona switching plus Studio design-language and text-to-speech governance previews