# ADR-0063: OSHUN V1 Foundation Token System

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

## Context

OSHUN already had two overlapping visual-token layers:

- `libs/oshun/design-tokens` defined the shared theme primitives
- `apps/oshun/web/src/design-system/tokens.ts` redefined richer web-specific
  spacing, typography, motion, and elevation values

That split made the product look coherent in practice, but it left the V1 visual
system under-specified. The TODO list explicitly requires one V1 token
definition for color, typography, spacing, elevation, and motion. The product
brief also requires one consistent design language across customer and admin
surfaces.

## Decision

Publish one canonical V1 foundation token bundle from
`libs/oshun/design-tokens/src/tokens.ts` and make the web design system consume
that shared bundle instead of re-inventing the same primitives locally.

The V1 foundation includes:

1. Color foundations
   - neutral `ink` and `fog` scales
   - shared signal and status scales
   - canonical domain seed accents

2. Typography foundations
   - display, body, and mono families
   - explicit `regular`, `medium`, `semibold`, `bold`, and `extrabold` weights
   - numeric editorial scale for shared theme contracts
   - fluid ramp for web rendering

3. Spacing foundations
   - one 4px-derived spacing scale from `0` through `96`
   - alias steps (`xxs` through `3xl`) preserved for shared-theme compatibility

4. Elevation foundations
   - canonical shadow ladder from `none` through `xl`
   - border-first dark-surface elevation rather than card-heavy chrome

5. Motion foundations
   - canonical duration ladder from `instant` through `slower`
   - standard, entrance, exit, spring, emphasized, and linear easing tokens
   - travel-distance and scale tokens used by shared motion helpers

## Consequences

- `libs/oshun/design-tokens` becomes the source of truth for the V1 foundation.
- `apps/oshun/web/src/design-system/tokens.ts` becomes an adapter layer instead
  of a second foundation definition.
- Studio design-language tooling can inspect the actual live bundle, including
  bundle id, visual thesis, semantic roles, type ramp, spacing, elevation, and
  motion cadence.
- `libs/oshun/ui/src/motion/transitions.ts` now consumes tokenized motion travel
  and scale values instead of hardcoded distances.

## Implementation

- Shared bundle:
  - `libs/oshun/design-tokens/src/tokens.ts`
- Shared bundle verification:
  - `libs/oshun/design-tokens/src/tokens.test.ts`
  - `libs/oshun/design-tokens/src/theme-regression.test.ts`
- Shared motion helper consumption:
  - `libs/oshun/ui/src/motion/transitions.ts`
  - `libs/oshun/ui/src/motion/transitions.test.ts`
- Web adapter:
  - `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`
- 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 token-library tests pass.
2. Shared UI motion-library tests pass.
3. Web design-language and token-adapter tests pass.
4. Playwright verifies `/studio/design-language` renders the V1 foundation
   preview and governance controls.