# ISIS v2 WS11-001: Premium Creative-Suite Design Vision

## Scope

`WS11-001` defines the visual north star for the ISIS web app so subsequent UI
workstreams (`WS11-002` through `WS12`) ship against a shared, explicit design
language instead of ad hoc page styling.

This document is normative for:

- typography hierarchy and type usage rules,
- spacing rhythm and density rules,
- color language and semantic usage rules.

## Research and Existing Implementation Analysis

The vision is grounded in current implementation evidence and existing platform
design systems:

- Current ISIS surface baseline: `apps/isis/web/src/index.css`,
  `apps/isis/web/src/components/AppLayout.css`.
- Current UX gap evidence:
  `docs/domains/isis/remediation-v2/ISIS_V2_UX_INTERACTION_BENCHMARK.md`.
- Existing OSHUN design governance:
  `docs/adr/ADR-0014-oshun-studio-design-language-and-visual-identity.md`.
- Existing token patterns and typography scales:
  `libs/oshun/design-tokens/src/tokens.ts`,
  `apps/oshun/web/src/design-system/tokens.ts`.

Key findings from this analysis:

1. ISIS currently uses readable but generic operations-console styling, with
   limited semantic tokenization and no explicit creative-suite visual grammar.
2. OSHUN already defines a governance model and token discipline that ISIS can
   inherit for consistency and accessibility.
3. Creative workflows in ISIS require two density modes: high-density
   review/monitoring and focused authoring/composition.

## Vision Statement

ISIS must feel like a professional creative cockpit:

- precise enough for production operators,
- expressive enough for art directors and reviewers,
- stable enough for long sessions with minimal cognitive fatigue.

The UI should communicate "editorial control and production confidence," not
"generic admin dashboard."

## Design Language Contract

### 1) Typography Language

Typeface roles:

- Display/scene headers: `Space Grotesk`.
- Body/controls: `Manrope`.
- Data/code/provenance: `IBM Plex Mono`.

Type scale (authoritative tokens for ISIS web):

| Token                  | Size | Line Height | Weight | Primary Use          |
| ---------------------- | ---: | ----------: | -----: | -------------------- |
| `isis-type-display-xl` | 44px |        52px |    600 | Workspace hero/title |
| `isis-type-display-lg` | 36px |        44px |    600 | Page-level headings  |
| `isis-type-title-xl`   | 30px |        38px |    600 | Section framing      |
| `isis-type-title-lg`   | 24px |        32px |    600 | Panel headings       |
| `isis-type-title-md`   | 20px |        28px |    600 | Card/rail headings   |
| `isis-type-body-lg`    | 18px |        28px |    500 | Intro/assistive copy |
| `isis-type-body-md`    | 16px |        24px |    500 | Default UI body text |
| `isis-type-body-sm`    | 14px |        20px |    500 | Dense metadata       |
| `isis-type-label-md`   | 13px |        18px |    600 | Buttons/chips/tabs   |
| `isis-type-label-sm`   | 12px |        16px |    600 | Column labels        |
| `isis-type-mono-sm`    | 12px |        18px |    500 | IDs, metrics, hashes |

Typography rules:

- Never mix more than three text sizes in one panel header region.
- All critical workflow actions use `label-md` minimum.
- Numeric telemetry and run diagnostics default to mono styles for scan speed.
- Uppercase labels are reserved for state chips and compact timeline markers.

### 2) Spacing Language

Base grid:

- 4px base rhythm with 8px compositional cadence.

Canonical spacing tokens:

| Token           | Value | Use                            |
| --------------- | ----: | ------------------------------ |
| `isis-space-1`  |   4px | tight inline separation        |
| `isis-space-2`  |   8px | icon + label, chip gaps        |
| `isis-space-3`  |  12px | compact list row internals     |
| `isis-space-4`  |  16px | control group spacing          |
| `isis-space-5`  |  20px | section padding (compact)      |
| `isis-space-6`  |  24px | default card padding           |
| `isis-space-8`  |  32px | page section separation        |
| `isis-space-10` |  40px | major workspace boundaries     |
| `isis-space-12` |  48px | full-screen mode spacing       |
| `isis-space-16` |  64px | cinematic presentation headers |

Density modes:

- `dense` mode: operator consoles, parity tables, telemetry dashboards.
- `balanced` mode: authoring forms, workflow editors, run configuration pages.
- `focus` mode: review/comparison/timeline workspaces with fewer simultaneous
  controls and larger visual anchors.

Spacing rules:

- Components may only use tokens above, never arbitrary pixel values.
- Vertical rhythm between major sections is at least `isis-space-8`.
- Interactive hit areas must remain at least 40px even in dense mode.

### 3) Color Language

ISIS visual intent:

- neutral graphite/ink foundations for focus,
- cyan/teal guidance for primary action and active context,
- amber for caution/quality review attention,
- green/red for semantic success/failure only.

Core palette (v1):

| Token                    | Hex       | Role                       |
| ------------------------ | --------- | -------------------------- |
| `isis-color-ink-950`     | `#050914` | global shell background    |
| `isis-color-ink-900`     | `#0A1324` | elevated nav regions       |
| `isis-color-ink-800`     | `#13233A` | panels and cards           |
| `isis-color-mist-200`    | `#CFDDEE` | secondary text             |
| `isis-color-mist-50`     | `#F4F8FD` | high-contrast text on dark |
| `isis-color-cyan-500`    | `#26C6DA` | primary action/accent      |
| `isis-color-cyan-400`    | `#4FD7E6` | hover/active guidance      |
| `isis-color-amber-500`   | `#F2A93B` | warning/review attention   |
| `isis-color-success-500` | `#2AB673` | success states             |
| `isis-color-danger-500`  | `#D94B4B` | error/destructive states   |

Semantic mapping contract:

- `surface/base`, `surface/raised`, `surface/overlay`
- `text/primary`, `text/secondary`, `text/inverse`
- `action/primary`, `action/secondary`, `action/ghost`
- `status/success`, `status/warning`, `status/error`, `status/info`
- `focus/ring`, `border/subtle`, `border/strong`

Color rules:

- Domain accents can tint context markers, never override semantic status
  colors.
- Red and green are reserved for status semantics and destructive/positive
  confirmation only.
- Contrast targets: WCAG AA minimum 4.5:1 for body text, 3:1 for large text.

## Workspace Expression Model

Visual direction by workspace:

1. Catalog/Discovery: lighter density, stronger hierarchy, high scannability.
2. Authoring/Editor: balanced density, structured control grouping.
3. Review/Compare/Timeline: darker cinematic canvas with high-contrast artifacts
   and persistent context rail.
4. Operations/Parity: dense data-first layout with mono data typography and
   restrained chroma.

## Quality Bar and Exit Criteria for WS11-001

`WS11-001` is considered complete only when:

1. A normative design-vision document exists with explicit typography, spacing,
   and color contracts.
2. The vision is grounded in existing ISIS/OSHUN implementation evidence.
3. The contract is specific enough to drive token implementation in `WS11-002`
   without reinterpretation.
4. The artifact is referenced as proof in remediation tracking and compliance
   evidence.

## Implementation Follow-Through (Feeds WS11-002+)

This vision directly feeds:

- semantic token creation and theming (`WS11-002`),
- layout and navigation overhaul (`WS11-003`, `WS11-004`),
- advanced state quality (`WS11-005`),
- keyboard-first and responsive patterns (`WS11-006`, `WS11-007`).

## Verification Commands

```bash
node scripts/isis/generate-remediation-backlog-v2.mjs
node scripts/isis/validate-v2-compliance-gate.mjs
```
