Eve library

OSHUN V1 Customer Visual Thesis

Guide

Revision 1

On this page

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.