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.mddocs/releases/v1/design/brand-system.mddocs/releases/v1/specs/product-brief.mddocs/releases/v1/specs/personas.mddocs/releases/v1/specs/web-app-admin-v1-prd.mddocs/adr/ADR-0063-oshun-v1-foundation-token-system.mdlibs/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.mdfor calm visual rhythm, trust, resilience, and cross-domain consistencydocs/releases/v1/design/brand-system.mdfor typography, color, and shell baselinedocs/releases/v1/specs/personas.mdanddocs/releases/v1/specs/product-brief.mdfor calm, low-friction, Tara-led customer posturedocs/releases/v1/specs/web-app-admin-v1-prd.mdfor premium, coherent, cross-domain product expectationslibs/oshun/design-tokens/src/tokens.tsandapps/oshun/web/src/design-system/tokens.tsfor the live foundation bundleapps/oshun/web/src/components/ShellLayout.tsx,apps/oshun/web/src/app/page.tsx, andapps/oshun/mobile/app/(tabs)/index.tsxfor 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.