# ADR-0065: OSHUN Grounded Evidence UI Behavior

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

## Context

OSHUN already had typed Sophia-backed evidence contracts, citation trails, claim
checks, and grounded-answer style surfaces, but the visual behavior of grounded
evidence was still mostly implicit:

- Veritas RAG and claim-inspection surfaces were styling evidence states locally
- quoted passages, citation cards, and evidence summaries did not share one
  governed shell grammar
- Studio could inspect foundation tokens and domain accents, but not the visual
  rules for grounded evidence itself

The V1 TODO list explicitly requires the visual rules for grounded evidence UI
to be defined. Existing shell governance already requires semantic-first truth
signals, restrained use of domain accent, and reusable behavior across
customer-shell and governance surfaces.

## Decision

Publish one canonical grounded-evidence UI behavior contract from
`libs/oshun/design-tokens/src/tokens.ts` and make the web shell consume it
through tokenized CSS variables, grounded-evidence helpers, Studio inspection
surfaces, and the current Veritas grounded-evidence flows.

The shell contract is:

1. Semantic truth signals first
   - grounded, partially grounded, unsupported, and conflicting states use
     semantic tones before any domain accent

2. Neutral evidence shells
   - evidence summaries, citation cards, and claim evidence containers stay on
     neutral surfaces; tone arrives through restrained washes, borders, rails,
     and pills

3. Source-anchored excerpts
   - quoted passages must read as anchored evidence through a compact excerpt
     surface, visible rail, and adjacent source metadata

4. Compact metadata hierarchy
   - source type, chronology, and evidence counts stay visually secondary so
     claims and excerpts remain the primary reading layer

5. Cross-domain reuse
   - the same evidence grammar must work for Veritas claim inspection,
     citation-backed assistant answers, Nisaba grounded reading, and Studio
     evidence review surfaces

## Consequences

- `oshun-v1-foundation` now includes a grounded-evidence behavior contract in
  addition to core color, typography, spacing, elevation, motion, and
  domain-accent behavior.
- `apps/oshun/web/src/design-system/globals-v2.css` now defines shared
  evidence-tone, stance, summary-surface, excerpt-rail, citation-index, and
  metadata-dot variables.
- `apps/oshun/web/src/design-system/grounded-evidence.ts` now provides the
  canonical web helper layer for evidence-status labels and derived grounding
  state.
- Studio design-language tooling can now inspect grounded-evidence statuses,
  stances, and role rules as live governed artifacts.
- Veritas grounded-answer and claim-check flows now consume the same shell
  contract instead of hand-rolling local evidence-state styling.

## 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/grounded-evidence.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__/grounded-evidence.test.ts`
- Web grounded-evidence surfaces:
  - `apps/oshun/web/src/components/domains/veritas/VeritasRAG.tsx`
  - `apps/oshun/web/src/components/domains/veritas/VeritasClaimChecker.tsx`
  - `apps/oshun/web/src/components/domains/veritas/__tests__/VeritasClaimBias.test.tsx`
  - `apps/oshun/web/src/components/domains/veritas/__tests__/VeritasRemainingModules.test.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/veritas-full-journey.spec.ts`

## Verification

This slice is complete when:

1. shared design-token tests pass
2. targeted web grounded-evidence, Veritas, and Studio tests pass
3. targeted eslint passes for the changed shared, web, and e2e files
4. Playwright verifies both Studio grounded-evidence governance previews and the
   live Veritas grounded-evidence journey