# OSHUN V1 Customer Visual Thesis

Status: Accepted v1.0  
Owner: OSHUN Design + Product + Engineering  
Last Updated: March 26, 2026  
Implements: `V1-UX-045`  
Related:

- `docs/releases/v1/design/ux-principles.md`
- `docs/releases/v1/design/brand-system.md`
- `docs/releases/v1/specs/product-brief.md`
- `docs/releases/v1/specs/personas.md`
- `docs/releases/v1/specs/web-app-admin-v1-prd.md`
- `docs/adr/ADR-0063-oshun-v1-foundation-token-system.md`
- `libs/oshun/design-tokens/src/tokens.ts`

## 1. Purpose

This document defines the canonical customer-product visual thesis for OSHUN V1
across:

- customer web and PWA shell
- customer mobile shell
- shared customer-facing domain surfaces
- launch-critical cross-domain journeys

This thesis is the visual decision filter for all customer redesign work. If a
customer surface looks polished but does not feel calm, premium, minimal,
embodied, and unmistakably non-generic, it is off-thesis.

## 2. Scope and Acceptance

This task is complete when all customer-facing OSHUN redesign work can answer
these questions with a clear yes:

- Does the first screen reduce noise instead of adding stimulation?
- Does the shell feel premium through restraint rather than ornament?
- Does the layout guide the body and attention, not just the eye?
- Does each domain feel distinct without fragmenting the shell?
- Would the interface still feel recognizably OSHUN if borders, shadows, and
  decorative effects were reduced further?

## 3. Inputs Reviewed

Internal implementation and product inputs reviewed before defining the thesis:

- `docs/releases/v1/design/ux-principles.md` for calm visual rhythm, trust,
  resilience, and cross-domain consistency
- `docs/releases/v1/design/brand-system.md` for typography, color, and shell
  baseline
- `docs/releases/v1/specs/personas.md` and
  `docs/releases/v1/specs/product-brief.md` for calm, low-friction, Tara-led
  customer posture
- `docs/releases/v1/specs/web-app-admin-v1-prd.md` for premium, coherent,
  cross-domain product expectations
- `libs/oshun/design-tokens/src/tokens.ts` and
  `apps/oshun/web/src/design-system/tokens.ts` for the live foundation bundle
- `apps/oshun/web/src/components/ShellLayout.tsx`,
  `apps/oshun/web/src/app/page.tsx`, and
  `apps/oshun/mobile/app/(tabs)/index.tsx` for the current shell and home
  implementation posture

Comparative reference patterns reviewed:

- Headspace: calm daily-practice orientation, low-friction guidance, and
  emotional regulation posture
- Calm: premium stillness, deliberate pacing, and lifestyle-grade polish

These references inform posture only. OSHUN must not imitate their branding,
illustration style, or wellness cliches.

## 4. Canonical Thesis

### 4.1 One-Sentence Thesis

OSHUN customer product should feel like a quiet observatory for inner life: calm
and premium at first glance, minimal in chrome, embodied in posture and motion,
and unmistakably non-generic in how each domain adds atmosphere without breaking
one shell.

### 4.2 Short Canonical Form

Use the following short form wherever a compact metadata field or governance
label is required:

> Calm, premium shells with embodied wayfinding, minimal chrome, and
> unmistakably non-generic domain atmosphere.

## 5. Core Experience Promises

### 5.1 Presence Before Throughput

The interface should settle the user before asking for decisions.

- The first screen should orient, not overwhelm.
- Primary actions should emerge from continuity and intent, not promotional
  urgency.
- Visual emphasis should feel earned, not constant.

### 5.2 Premium Through Restraint

OSHUN should feel high-end because it is composed, not because it is loud.

- Large, disciplined typography beats decorative chrome.
- Spacious rhythm beats dashboard density on customer surfaces.
- Richness should come from material contrast, motion cadence, and content
  confidence, not glossy effects.

### 5.3 Embodied Wayfinding

Customer movement through the shell should feel physical and grounded.

- The user should feel guided from center to action, not dumped into a tool.
- Motion should imply breath, settling, continuity, and return.
- Controls should respect hand reach, reading flow, and interruption recovery.

### 5.4 One Shell, Five Rooms

Tara, Veritas, Nyx, Arete, and Nisaba should feel like different rooms in one
home.

- Domain identity appears through accent, tone, imagery, and content posture.
- Navigation grammar, disclosure treatment, and shell structure remain shared.
- Domain color should act like light in the room, not paint on every surface.

### 5.5 Trust Without Bureaucratic Noise

Trust signals must be visible without making customer surfaces feel clinical.

- Evidence, provenance, disclosure, and continuity state should be legible.
- These signals should appear as integrated rails, labels, and secondary
  structures, not operator-style warning clutter.

## 6. Visual Grammar

### 6.1 Canvas

- Default shell mood: nocturnal, luminous, border-first, and calm.
- The canvas should feel deep enough to hold reflection, not flat and generic.
- Base surfaces should stay neutral so domain atmosphere can arrive in small,
  intentional doses.

### 6.2 Typography

- Typography is the main luxury signal on customer surfaces.
- Headlines should feel composed and grounded, never shouty.
- Dense label stacks, tiny pills, and cluttered metadata rows weaken the thesis.

### 6.3 Surfaces and Elevation

- Elevation should come from borders, contrast, and spacing before heavy shadow.
- Panels should read as quiet layers, not card mosaics.
- Customer surfaces should prefer sections, rails, and split layouts over
  repetitive boxed tiles.

### 6.4 Domain Atmosphere

- Domain accent should tint focus areas, local rails, progress, and emphasis.
- Full-surface domain tinting is prohibited for shell canvases and navigation.
- Domain identity should be felt through local mood, not through visual
  fragmentation.

### 6.5 Imagery

- Imagery must support presence, ritual, study, or wonder.
- Decorative abstract gradients alone are not enough to carry premium tone.
- If a hero or landing surface has no meaningful visual anchor, it will feel
  generic even with strong tokens.

### 6.6 Motion

- Motion should feel like settling, handoff, reveal, or continuity.
- Customer motion should never feel hyperactive, game-like, or ornamental.
- When motion is removed, the screen should still read clearly and remain
  premium.

## 7. Domain Translation

### 7.1 Tara

- Softest and most centering posture.
- Warmth and breath over gadgetry.
- The default emotional anchor for the broader shell.

### 7.2 Veritas

- Most explicit trust and evidence posture.
- Calm rigor, not newsroom anxiety or enterprise severity.
- Evidence should sharpen confidence without cooling the shell into a sterile
  dashboard.

### 7.3 Nyx

- Wonder, scale, and perspective.
- Darkness should feel expansive and precise, not sci-fi noisy.
- The domain may be the most visually atmospheric, but still shares the shell's
  restraint.

### 7.4 Arete

- Forward momentum, discipline, and clarity.
- Progress cues should feel motivating, not gamified or punitive.
- Energy comes from crisp hierarchy and motion discipline, not badges
  everywhere.

### 7.5 Nisaba

- Scholarship, continuity, and reverence for text.
- Reading surfaces should feel editorial and durable.
- Ornament must never interfere with measure, annotation clarity, or evidence
  traceability.

## 8. Anti-Goals

The following are explicitly off-thesis:

- generic SaaS card-grid homepages
- wellness-app cliches built from pastel blobs and inspirational filler copy
- luxury-signaling through glassmorphism, excessive blur, or metallic gimmicks
- per-domain visual fragmentation that makes the product feel like five apps
- busy dashboards with multiple simultaneous "primary" actions
- decorative motion that competes with reading or orientation
- pseudo-spiritual visual language that weakens trust, rigor, or seriousness

## 9. Review Questions

Any customer redesign should be reviewed against these checks:

- Is the first screen quieter and more intentional than the user's surrounding
  environment?
- Is there one dominant action or takeaway per viewport?
- Does the surface feel designed around the user's body, attention, and return
  path?
- Is domain identity present as atmosphere and content posture rather than
  chrome?
- If brand accents were reduced by 20%, would the screen still feel premium and
  unmistakably OSHUN?

## 10. Implementation Contract

The short canonical form in section 4.2 must stay synchronized with:

- `libs/oshun/design-tokens/src/tokens.ts`
- any Studio or shell metadata surface that exposes the V1 foundation bundle

If the thesis changes, the token metadata and this document must be updated in
the same change.
