# OSHUN UX Principles

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.
