Eve library

OSHUN UX Principles

Guide

Revision 1

On this page

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.