Status: Draft v1.0 Owner: OSHUN Design + OSHUN Engineering Last Updated: March
22, 2026 Related: docs/releases/v1/design/ux-principles.md,
docs/releases/v1/design/readability-standards.md,
docs/releases/v1/design/customer-visual-thesis.md,
libs/oshun/design-tokens/src/tokens.ts,
docs/releases/v1/specs/program-charter.md
1. Purpose#
This document defines the foundational visual language for OSHUN across:
- Mobile shell (
apps/oshun/mobile) - Web/PWA shell (
apps/oshun/web) - Shared UI primitives (
libs/oshun/ui)
The system favors calm clarity with high information legibility and explicit domain differentiation for Tara, Arete, Veritas, Nyx, and Nisaba.
2. Brand Expression#
2.1 Character#
- Calm, precise, and trustworthy.
- Premium but not ornamental.
- Technical confidence with human warmth.
2.2 Design Principles#
- Contrast with restraint: one strong focal accent per screen.
- Domain identity without fragmentation: domain accents never replace shared shell grammar.
- Accessibility-first hierarchy: readable at a glance, scalable under large text modes.
3. Color System#
3.1 Core Brand Palette#
| Token | Hex | Purpose |
|---|---|---|
ink-950 |
#040B16 |
App chrome, dark anchors |
ink-900 |
#0B1728 |
Elevated dark surfaces |
ink-700 |
#22334D |
Dividers on dark |
fog-300 |
#C8D5E8 |
Secondary text on dark |
fog-100 |
#EAF0F8 |
Light-mode backgrounds |
white |
#FFFFFF |
Light surfaces and contrast text |
aqua-500 |
#20C9D8 |
Primary OSHUN accent |
amber-500 |
#F4A524 |
Highlight/warning emphasis |
success-500 |
#2AB673 |
Success/positive state |
danger-500 |
#E24D4D |
Error/destructive state |
3.2 Domain Accent Palette#
| Domain | Token | Hex |
|---|---|---|
| Tara | domain-tara |
#2BC6B4 |
| Arete | domain-arete |
#3AC77B |
| Veritas | domain-veritas |
#27A3F3 |
| Nyx | domain-nyx |
#7D7CFF |
| Nisaba | domain-nisaba |
#C88B2C |
3.3 Semantic Color Roles#
surface/base: canvas background.surface/raised: cards and sheets.surface/overlay: modals and top layers.text/primary: default body and title text.text/secondary: metadata and supporting copy.action/primary: main CTA.status/{success|warning|error|info}: feedback messaging.
3.4 Gradients and Atmosphere#
Primary shell gradient:
- Start:
#08152A - Mid:
#0A2036 - End:
#040B16
Domain glows are additive overlays (10-18% opacity), never full-screen color replacements.
4. Typography System#
4.1 Font Families#
- Display/headline:
Space Grotesk - Body/UI:
Manrope - Monospace/data:
IBM Plex Mono
Fallback stacks:
- Sans:
"Manrope", "Avenir Next", "Segoe UI", sans-serif - Display:
"Space Grotesk", "Manrope", "Segoe UI", sans-serif - Mono:
"IBM Plex Mono", "SFMono-Regular", "Menlo", monospace
4.2 Type Scale#
| Token | Size | Line Height | Weight | Use |
|---|---|---|---|---|
display-xl |
48 | 56 | 600 | Hero titles |
display-lg |
40 | 48 | 600 | Feature headers |
title-xl |
32 | 40 | 600 | Screen titles |
title-lg |
28 | 36 | 600 | Section titles |
title-md |
24 | 32 | 600 | Card titles |
body-lg |
18 | 28 | 500 | Lead paragraph |
body-md |
16 | 24 | 500 | Default body |
body-sm |
14 | 20 | 500 | Secondary text |
label-md |
13 | 18 | 600 | Buttons, chips |
label-sm |
12 | 16 | 600 | Metadata labels |
mono-sm |
12 | 18 | 500 | Technical values |
5. Iconography System#
5.1 Icon Family#
- Primary icon set: Phosphor (or equivalent geometric stroke family).
- Baseline stroke width: 1.75px at 24px size.
- Corner style: rounded joins to match shell softness.
5.2 Size Rules#
16px: inline indicators.20px: dense list rows.24px: default interactive icon.28px: prominent nav controls.
5.3 Domain Symbol Mapping#
- Tara: lotus / breath / wave motifs.
- Veritas: shield / check / document motifs.
- Nyx: moon / star / telescope motifs.
- Arete: spark / target / path motifs.
Domain symbols can tint by domain accent, but structural navigation icons remain neutral.
6. Spacing and Layout Rhythm#
6.1 Spacing Scale#
4pt base grid:
space-1= 4space-2= 8space-3= 12space-4= 16space-5= 20space-6= 24space-8= 32space-10= 40space-12= 48space-16= 64
6.2 Radius Scale#
radius-sm= 8radius-md= 12radius-lg= 16radius-xl= 24radius-pill= 999
6.3 Elevation#
- Level 0: flat surface.
- Level 1: card (subtle shadow + border).
- Level 2: sheet/modal (stronger shadow, limited blur).
- Level 3: transient overlay (popover/toast).
7. Component-Level Brand Rules#
- Primary actions use OSHUN aqua; only one primary action per viewport.
- Domain cards include domain accent top-edge or icon fill, not full card tint.
- Status banners use semantic status colors with icon + heading + next action.
- Navigation bars use neutral surfaces to avoid brand noise.
8. Accessibility and Contrast Baseline#
- Body text contrast target: WCAG AA minimum 4.5:1.
- Large text contrast target: 3:1 minimum.
- Interactive focus ring: minimum 2px visible outline with
aqua-500or high-contrast equivalent. - Color is never the sole state indicator; pair with icon or text.
9. Implementation Contract#
The following must stay synchronized with this document:
libs/oshun/design-tokens/src/tokens.tslibs/oshun/ui/src/theme/index.ts- OSHUN shell styles in mobile and web apps
Any deviation requires an explicit update in this document and a matching token-level change.