Status: Draft v1.0 Owner: OSHUN Design + Product + Engineering Last Updated:
March 22, 2026 Related: docs/releases/v1/specs/product-brief.md,
docs/releases/v1/specs/personas.md, docs/releases/v1/scope/mvp-scope.md,
docs/releases/v1/specs/program-charter.md,
docs/releases/v1/design/customer-visual-thesis.md
Purpose#
This document defines the core UX principles that govern OSHUN across mobile, web, and PWA surfaces.
These principles are decision filters. If a feature conflicts with them, the feature or implementation should be changed.
Principles#
1. Instant Value Over Navigation Depth#
Users should reach meaningful action quickly.
- Intent: reduce time-to-first-value in every primary journey.
- Standard: critical domain entry actions should be reachable in <= 2 taps from Home.
- Anti-pattern: burying common actions behind multi-level menus.
2. One Shell, One Mental Model#
Cross-domain movement should feel like changing rooms in one home, not jumping between disconnected apps.
- Intent: eliminate context switching friction.
- Standard: shared patterns for navigation, search, save, activity, and settings across Tara, Arete, Veritas, Nyx, and Nisaba.
- Anti-pattern: each domain using unique interaction language for core actions.
3. Clarity Before Density#
Every screen must make the next best action obvious before exposing advanced controls.
- Intent: reduce decision fatigue and increase completion rates.
- Standard: primary CTA and state should be visually unambiguous at first scan.
- Anti-pattern: multiple competing primary actions on the same viewport.
4. Trust Through Transparency#
Information quality and system confidence must be visible where users make choices.
- Intent: strengthen confidence in outcomes, especially for Veritas and recommendations.
- Standard: show confidence/evidence/explanation signals where claims or suggestions appear.
- Anti-pattern: opaque ranking or unverifiable assertions in high-stakes views.
5. Resilience Is Part of UX#
Failure states must preserve user progress and provide clear recovery paths.
- Intent: prevent frustration during network/API instability.
- Standard: all critical flows define loading, empty, offline, and error states.
- Anti-pattern: dead-end errors without retry, fallback, or recovery guidance.
6. Calm, Focused Visual Rhythm#
The interface should feel composed and intentional, not noisy.
- Intent: support emotional regulation and sustained attention.
- Standard: strict visual hierarchy, limited simultaneous emphasis, meaningful motion.
- Anti-pattern: decorative motion, excessive visual contrast, constant badges.
7. Accessibility Is Default, Not Enhancement#
Core journeys must be fully usable with assistive technologies and diverse user needs.
- Intent: ensure equitable access and improve overall interface quality.
- Standard: semantic labels, keyboard/focus paths, readable contrast, scalable typography on all key flows.
- Anti-pattern: shipping core experiences that require visual precision or fine motor control to complete.
8. Momentum Over Perfection#
Progress cues should encourage users to continue, recover, and return.
- Intent: increase habit continuity and long-term retention.
- Standard: design for recoverability after misses and celebrate meaningful progress without manipulation.
- Anti-pattern: punitive streak logic, guilt-based copy, or progress loss by minor interruption.
Principle Review Checklist#
Before merging significant UX changes, verify:
- Does this reduce time-to-value for at least one P1 persona?
- Does this preserve cross-domain consistency for core actions?
- Does this improve or maintain trust and transparency?
- Does this include robust failure and recovery states?
- Does this remain accessible in primary flows?
Governance#
- UX principles should be reviewed monthly with product and engineering leads.
- Any intentional principle exception must be documented in the related PR/ADR.