Status: Accepted v1.0
Owner: OSHUN Design + Product + Engineering
Last Updated: March 26, 2026
Implements: V1-UX-054
Related:
docs/releases/v1/design/customer-visual-thesis.mddocs/releases/v1/design/admin-visual-thesis.mddocs/releases/v1/scope/minimal-chrome-rules.mddocs/releases/v1/specs/layout-density-tiers.mddocs/releases/v1/specs/web-app-admin-v1-prd.mddocs/releases/v1/specs/todos.md
1. Purpose#
This document defines when OSHUN surfaces should feel immersive versus utilitarian across Tara, Arete, Veritas, Nyx, Nisaba, and admin contexts.
The goal is to stop posture drift.
OSHUN should not make everything:
- cinematic
- meditative
- dashboard-like
- operator-like
Each surface should feel appropriate to the job the user is doing.
2. Definitions#
2.1 Immersive#
An immersive surface reduces chrome, narrows attention, and uses atmosphere to help the user stay with one subject, ritual, medium, or guided sequence.
Immersive does not mean ornamental.
It means:
- one dominant focus
- fewer visible controls
- slower and quieter pacing
- stronger atmosphere or environmental framing
- reduced decision branching in the active moment
2.2 Utilitarian#
A utilitarian surface prioritizes scan speed, explicit control, decision clarity, and reliable recovery.
Utilitarian does not mean visually dull.
It means:
- clear structure
- visible state
- direct actions
- compressed but legible metadata
- minimal ambiguity
3. Canonical Decision Rule#
Use immersive posture when the user benefits from staying with one thing.
Use utilitarian posture when the user benefits from quickly understanding and acting on many things.
Short test:
- if branching and scan speed matter more, choose utilitarian
- if sustained focus and emotional regulation matter more, choose immersive
4. Global Rules#
4.1 Immersion Is Earned#
Immersion is appropriate only when atmosphere measurably improves the task.
Valid reasons:
- guided practice
- observational focus
- deep reading
- narrative or ritual continuity
- first-run emotional orientation
Invalid reasons:
- hiding weak information architecture
- compensating for generic layouts
- making ordinary settings or queue screens feel "special"
4.2 Utility Owns High-Stakes Decisions#
Any surface involving one or more of the following defaults to utilitarian:
- approval
- moderation
- evidence review
- policy
- privacy
- reliability
- support
- configuration
- queue management
- incident response
4.3 Posture Can Shift Inside One Journey#
One route may move between postures if the job changes.
Valid pattern:
- immersive entry or focus state
- utilitarian controls for save/share/manage/recover
Invalid pattern:
- immersive shell
- immersive settings
- immersive filters
- immersive error handling
Once the job becomes operational, the posture must become utilitarian.
5. Domain Matrix#
| Context | Default posture | Immersive allowed when | Utilitarian required when |
|---|---|---|---|
Tara |
immersive-leaning | ritual start, guided session, reflection, emotional reset, recovery states | settings, history, permissions, scheduling, saves, troubleshooting |
Arete |
balanced but utility-leaning | reflection prompts, milestone celebration, focused journaling, coaching moments | goal setup, habit logging, reminders, progress review, accountability controls |
Veritas |
utilitarian | rare article or story reading moments only if evidence visibility remains intact | search, claim review, source comparison, confidence, save/follow, fact-check workflows |
Nyx |
mixed | sky viewing, live event focus, observatory or celestial exploration, night-mode observation | alerts, filters, planning, observation logs, settings, event management |
Nisaba |
research-immersive hybrid | focused reading, passage comparison, translation or annotation immersion, study continuity | citations, notebook management, exports, search/filter, workspace organization |
Admin |
utilitarian | almost never; only isolated inspection or simulation moments where focus aids comprehension | shells, queues, approvals, policies, incidents, audits, configuration, observability, support |
6. Tara Rules#
Tara may be the most immersive customer domain, but only where that posture reduces stress and improves presence.
Immersive Tara surfaces:
- active guided session
- pre-session settling state
- post-session reflection
- calm recovery or degraded fallback
Utilitarian Tara surfaces:
- session selection lists
- streak/history and library management
- audio/output settings
- permissions and device controls
- billing or profile crossover
Tara must never hide practical controls behind mood when the user is trying to manage continuity or recover from failure.
7. Arete Rules#
Arete supports behavior change, so it should feel more structured than Tara.
Immersive Arete is appropriate for:
- focused journaling
- reflective prompt completion
- milestone or momentum acknowledgment
Utilitarian Arete is required for:
- check-ins
- habit toggles
- reminder settings
- goal editing
- accountability review
Arete should feel encouraging, but not dreamy. Action clarity outranks atmosphere in most of the domain.
8. Veritas Rules#
Veritas is trust-critical and therefore utilitarian by default.
Immersive posture is allowed only in narrow reading contexts where it supports:
- concentration on one article or claim
- careful reading of a passage
- reduced interruption during evidence consumption
Even in those moments:
- source visibility stays explicit
- confidence and provenance stay legible
- atmosphere must not suggest certainty beyond the evidence
Veritas must never become visually lush at the cost of verification clarity.
9. Nyx Rules#
Nyx can legitimately move between immersive wonder and utilitarian control.
Immersive Nyx surfaces:
- celestial viewing
- night-sky exploration
- event-focus moments
- full-attention observation states
Utilitarian Nyx surfaces:
- filter and planning tools
- event logs
- reminder management
- equipment or settings controls
- fallback and troubleshooting states
Nyx is allowed more environmental framing than the other domains, but not when the user is trying to plan, filter, or recover.
10. Nisaba Rules#
Nisaba is not cinematic. Its immersive posture comes from study concentration, not atmosphere-heavy visuals.
Immersive Nisaba surfaces:
- focused reading
- compare mode when text remains primary
- annotation flow with low chrome
- continuity into saved study work
Utilitarian Nisaba surfaces:
- library and notebook management
- citation and export control
- search and filtering
- workspace selection
- metadata-heavy compare setup
Nisaba immersion should feel scholarly and quiet, never theatrical.
11. Admin Rules#
Admin posture is utilitarian by default and should remain that way.
Admin surfaces exist for:
- queue triage
- review and approval
- reliability and incidents
- policy and configuration
- evidence and audit
- support and privacy operations
Immersive posture is allowed only in rare focused-inspection moments such as:
- side-by-side artifact inspection
- simulation playback
- dense evidence review where lowering chrome improves comprehension
Even then:
- navigation remains obvious
- state stays explicit
- next actions remain visible
The admin shell must never chase "mood." It must preserve command confidence.
12. Posture Signals#
12.1 Signals Of Immersive Posture#
- fewer visible controls
- slower transitions
- larger visual anchor or content plane
- reduced metadata at first glance
- stronger atmosphere, texture, or environmental cues
- one dominant action
12.2 Signals Of Utilitarian Posture#
- explicit state labels
- denser but orderly metadata
- direct toolbars or filters
- compact spacing where scan speed matters
- faster interaction feedback
- clear secondary and recovery actions
13. Transition Rules#
When shifting from immersive to utilitarian:
- keep the object or context visible
- reveal more chrome progressively
- speed up the interaction cadence
- move from atmosphere cues to explicit labels and status
When shifting from utilitarian to immersive:
- reduce visible branching
- quiet secondary actions
- remove unnecessary status clutter
- preserve one easy recovery path back to utilitarian controls
14. Explicit Anti-Patterns#
These are non-canonical:
- immersive admin dashboards
- immersive privacy or policy screens
- mood-heavy Veritas evidence views
- Tara operational controls hidden behind ritual framing
- Nyx planning tools that behave like theatrical scene reveals
- Nisaba reading surfaces that look like marketing pages
- atmospheric error states that obscure what to do next
15. Implementation Contract#
These posture rules should guide current and future domain surfaces, including:
apps/oshun/web/src/components/DomainRouteExperience.tsxapps/oshun/mobile/app/domain/[domainId].tsxapps/oshun/web/src/components/ShellLayout.tsxapps/oshun/web/src/components/search/SearchResultsView.tsxapps/oshun/web/src/components/studio/*
Each redesign should explicitly declare which posture it is using and why.
16. Exit Standard#
A surface has the correct posture only when:
- the emotional tone matches the task
- controls are as visible as the task requires
- atmosphere improves focus instead of hiding structure
- moving the surface more immersive or more utilitarian would clearly make it worse
If the posture choice feels cosmetic, it is the wrong choice.