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

## 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`).

2. 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`).

3. Wired theme initialization in app bootstrap:

- `apps/isis/web/src/main.tsx`

4. 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.

5. 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).
