# OSHUN Brand System

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.
