Eve library

ISIS v2 WS11-002: Tokenized Design System, Semantic Theming, and Motion Primitives

Guide

Revision 1

On this page

Scope#

WS11-002 introduces a first-class ISIS web design-system layer with:

  • centralized design tokens (typography, spacing, radius, motion, elevation),
  • semantic light/dark themes,
  • runtime CSS custom-property hydration,
  • motion primitives consumed by core UI styles.

Research and Existing Implementation Alignment#

Implementation was aligned to:

  • current ISIS shell styling baseline: apps/isis/web/src/index.css, apps/isis/web/src/components/AppLayout.css;
  • WS11-001 design vision contract: docs/domains/isis/remediation-v2/ISIS_V2_PREMIUM_CREATIVE_SUITE_DESIGN_VISION.md;
  • existing token governance patterns in OSHUN: libs/oshun/design-tokens/src/tokens.ts, apps/oshun/web/src/design-system/tokens.ts.

Deliverables#

  1. Added token and theme source of truth:
  • apps/isis/web/src/design-system/tokens.ts

Includes:

  • typography tokens (display/body/mono families, scale, line-height, weight),
  • spacing and radius scales,
  • motion primitives (durations + easings),
  • semantic dark and light themes for surfaces, text, borders, actions, status, and feedback states,
  • CSS variable generator (createIsisCssVariables).
  1. Added runtime theme application:
  • apps/isis/web/src/design-system/theme.ts

Includes:

  • initial theme resolution from persisted preference and system mode,
  • CSS variable application onto document root,
  • persisted theme switching (setIsisTheme),
  • initialization hook used at app startup (initializeIsisTheme).
  1. Wired theme initialization in app bootstrap:
  • apps/isis/web/src/main.tsx
  1. Refactored core web CSS to consume semantic token variables:
  • apps/isis/web/src/index.css
  • apps/isis/web/src/components/AppLayout.css

Key outcomes:

  • raw hard-coded palette usage in primary shell styles replaced with semantic token references,
  • motion transitions and skeleton animation durations now reference motion primitives,
  • forms/buttons/panels now use semantic action/surface/border tokens,
  • typography and mono data surfaces are token-driven.
  1. Added focused tests for token and theme behavior:
  • apps/isis/web/src/design-system/tokens.spec.ts
  • apps/isis/web/src/design-system/theme.spec.ts

Verification Commands#

bash
pnpm --filter @isis/web exec vitest run src/design-system/tokens.spec.ts src/design-system/theme.spec.ts src/components/AppLayout.spec.tsx --reporter=dot
pnpm --filter @isis/web run typecheck

Verification Notes#

  • Targeted design-system + layout tests pass.
  • typecheck currently reports pre-existing workspace issues unrelated to WS11-002 implementation (existing RunPodPage nullability and cross-package @isis/client / rootDir typing constraints).