Disciplines · Decisions (ADRs)

ADR-0064: OSHUN Shell Domain Accent Behavior

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:

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