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:
- ISIS currently uses readable but generic operations-console styling, with limited semantic tokenization and no explicit creative-suite visual grammar.
- OSHUN already defines a governance model and token discipline that ISIS can inherit for consistency and accessibility.
- 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-mdminimum. - 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:
densemode: operator consoles, parity tables, telemetry dashboards.balancedmode: authoring forms, workflow editors, run configuration pages.focusmode: 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/overlaytext/primary,text/secondary,text/inverseaction/primary,action/secondary,action/ghoststatus/success,status/warning,status/error,status/infofocus/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:
- Catalog/Discovery: lighter density, stronger hierarchy, high scannability.
- Authoring/Editor: balanced density, structured control grouping.
- Review/Compare/Timeline: darker cinematic canvas with high-contrast artifacts and persistent context rail.
- 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:
- A normative design-vision document exists with explicit typography, spacing, and color contracts.
- The vision is grounded in existing ISIS/OSHUN implementation evidence.
- The contract is specific enough to drive token implementation in
WS11-002without reinterpretation. - 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#
node scripts/isis/generate-remediation-backlog-v2.mjs
node scripts/isis/validate-v2-compliance-gate.mjs