Disciplines · Decisions (ADRs)

ADR-0065: OSHUN Grounded Evidence UI Behavior

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:

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