Disciplines · Decisions (ADRs)

ADR-0063: OSHUN V1 Foundation Token System

OSHUN already had two overlapping visual-token layers:

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