# ADR-0064: OSHUN Shell Domain Accent Behavior

- Status: Accepted
- Date: 2026-03-24

## Context

OSHUN already had canonical domain accent seeds for Tara, Arete, Veritas, Nyx,
and Nisaba, but the way those accents appeared in the shell was still mostly
implicit:

- some components mixed accent fills and borders locally
- Nisaba was missing from the core CSS domain-override layer
- Studio could inspect the V1 foundation bundle, but not the shell's domain
  accent rules

The V1 TODO list explicitly requires domain accent behavior to be defined inside
one shell. Existing brand and color-system governance already require shared
shell grammar, semantic-first status signaling, and restrained use of domain
identity.

## Decision

Publish one canonical shell domain-accent behavior contract from
`libs/oshun/design-tokens/src/tokens.ts` and make the web shell consume that
contract through tokenized CSS variables, shared primitives, and Studio
inspection surfaces.

The shell contract is:

1. Shared grammar first
   - domain accents travel through muted washes, context chips, accent edges,
     active tab underlines, and temporary transition atmosphere
   - structural shell chrome stays neutral

2. Semantic status first
   - domain accents never replace semantic success, warning, danger, or info in
     critical states

3. One restrained accent system across all five domains
   - Tara, Arete, Veritas, Nyx, and Nisaba all inherit the same shell behavior
     model and differ only by domain seed color

4. Nisaba is first-class
   - every shell-level domain override and reusable primitive must support
     Nisaba the same way it supports Tara, Arete, Veritas, and Nyx

## Consequences

- `oshun-v1-foundation` now includes a domain-accent behavior contract in
  addition to core color, typography, spacing, elevation, and motion tokens.
- `apps/oshun/web/src/design-system/globals-v2.css` now defines one derived set
  of shell accent variables for any `[data-domain]` surface, including Nisaba.
- Shared web primitives now consume the contract instead of hand-rolling accent
  percentages:
  - `Card`
  - `DomainPill`
  - `Tabs`
  - `DomainSurfaceLayout`
  - `Sidebar`
  - `Badge`
  - `EmptyState`
  - domain transitions and domain-styled actions
- Studio design-language tooling can now inspect domain accent behavior as a
  live governed artifact, not just infer it from component code.

## Implementation

- Shared accent 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/globals-v2.css`
  - `apps/oshun/web/src/design-system/__tests__/tokens.test.ts`
- Web primitives:
  - `apps/oshun/web/src/design-system/components/Card.tsx`
  - `apps/oshun/web/src/design-system/components/DomainPill.tsx`
  - `apps/oshun/web/src/design-system/components/Tabs.tsx`
  - `apps/oshun/web/src/design-system/components/DomainSurfaceLayout.tsx`
  - `apps/oshun/web/src/design-system/components/Sidebar.tsx`
  - `apps/oshun/web/src/design-system/components/Badge.tsx`
  - `apps/oshun/web/src/design-system/components/EmptyState.tsx`
  - `apps/oshun/web/src/components/DomainTransition.tsx`
- Studio inspection surface:
  - `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`

## Verification

This slice is complete when:

1. shared design-token tests pass
2. targeted web design-system and Studio tests pass
3. targeted eslint passes for the changed shared and web files
4. Playwright verifies `/studio/design-language` renders the live domain accent
   behavior preview and governance flows