Eve library

OSHUN Brand System

Guide

Revision 1

On this page

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#

  • 16 px: inline indicators.
  • 20 px: dense list rows.
  • 24 px: default interactive icon.
  • 28 px: 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 = 4
  • space-2 = 8
  • space-3 = 12
  • space-4 = 16
  • space-5 = 20
  • space-6 = 24
  • space-8 = 32
  • space-10 = 40
  • space-12 = 48
  • space-16 = 64

6.2 Radius Scale#

  • radius-sm = 8
  • radius-md = 12
  • radius-lg = 16
  • radius-xl = 24
  • radius-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-500 or 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.ts
  • libs/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.