Eve library

OSHUN Content Hierarchy and Readability Standards

Guide

Revision 1

On this page

Status: Draft v1.0 Owner: OSHUN Product Design + Mobile/Web Engineering Last Updated: February 16, 2026 Related:

  • docs/releases/v1/design/ux-principles.md
  • docs/releases/v1/design/ergonomics-requirements.md
  • docs/releases/v1/design/motion-language.md
  • apps/tara/mobile/src/theme/index.ts
  • apps/tara/mobile/src/utils/accessibility.ts

1. Purpose#

Define consistent content hierarchy and readability rules for OSHUN across:

  • iOS (React Native)
  • Android (React Native)
  • website and PWA (web)

This document is optimized for small screens first, then scales up.

2. Readability Baseline#

All core OSHUN experiences must satisfy these baseline requirements:

  • Body text default: 16 logical px minimum.
  • Body line height: 1.45 to 1.7 ratio.
  • Touch-context text controls must remain legible at arm-length viewing distance.
  • Text contrast: WCAG AA minimum (4.5:1 normal text, 3:1 large text).
  • Dynamic type/text scaling must be supported without clipping.
  • Never require horizontal scrolling for prose or critical data labels.

3. Content Hierarchy Model#

Use a 6-level hierarchy across all shells and domain surfaces.

3.1 Levels and Intent#

Level Role Typical Use Max Emphasis Count Per Screen
L0 Primary orientation Screen title, current journey anchor 1
L1 Primary decision headline Main card title, featured item 2-4
L2 Supporting context Subtitle, summary, evidence label 4-8
L3 Metadata Time, source, status, streak, duration many, de-emphasized
L4 Action label Button text, segmented controls, chips many, concise
L5 Assistive/help text Error guidance, legal/support, hints as needed

3.2 Hierarchy Rules#

  • Every screen must present exactly one L0 anchor.
  • L1 elements must be visually stronger than L2/L3 in size, weight, or contrast.
  • L3 metadata must not compete with L1/L2 for first visual attention.
  • L5 text must be readable but never dominant unless it is a blocking error state.
  • If more than 2 elements compete for emphasis, reduce one level of hierarchy.

4. Typography Standards for Small Screens#

These values align with existing Tara mobile scaling and accessible theme patterns.

Token Size (dp/pt/px) Line Height Weight Usage
display-sm 28 34 700 Rare hero moments, no dense paragraphs
title-lg 24 30 700 L0 screen title
title-md 20 26 600 L1 major cards/sections
title-sm 18 24 600 L1/L2 compact card heading
body-lg 16 24 400-500 Primary body copy
body-md 15 22 400 Dense but important support copy
body-sm 14 20 400-500 Metadata with medium importance
caption 12 16 400-500 Non-critical supportive text only

4.2 Hard Minimums#

  • Critical interactive labels: 14 minimum.
  • Core reading text: 16 default, may scale up.
  • Avoid using 12 for actionable controls.
  • Do not place more than two font weights in a single compact card.

4.3 Line Length and Measure#

  • Mobile cards and summaries: target 28-42 characters per line.
  • Long-form mobile reading mode: target 30-45 characters per line.
  • Web/PWA reading containers: cap prose width at 60-75ch.
  • Do not allow full-width long-form text blocks on large desktop screens.

5. Small-Screen Content Density Rules#

5.1 Card Density#

  • Card headline: clamp to 2 lines.
  • Card support text: clamp to 2-3 lines.
  • Show at most 1 primary CTA and 1 secondary CTA per card in feed contexts.
  • Metadata rows should use concise separators and avoid sentence-form labels.

5.2 List Density#

  • Maintain at least 8 spacing between stacked text lines in dense lists.
  • Group related metadata into one line before adding a new row.
  • Insert section headers for every 6-10 items to preserve scannability.

5.3 Paragraph Rules#

  • Feed/support paragraphs: 2-4 sentences max.
  • Long-form text: use paragraph breaks every 3-5 lines on mobile.
  • Avoid center alignment for paragraphs longer than 2 lines.

6. Domain-Aware Hierarchy Guidance#

6.1 Tara#

  • Prioritize calm scannability: sequence = title, duration, guide, action.
  • Breath/session instructions must remain readable at elevated font scales.

6.2 Veritas#

  • Prioritize trust and evidence: sequence = claim headline, confidence/evidence, source, action.
  • Source attribution and confidence indicators must never be visually hidden below decorative elements.

6.3 Nyx#

  • Prioritize low-light readability with strong text/background separation.
  • Preserve legibility under reduced screen brightness and outdoor glare variability.

6.4 Arete#

  • Prioritize quick completion: sequence = prompt, progress context, primary check-in action.
  • Daily check-in copy must stay concise enough for <= 60 second completion flow.

7. Dynamic Type and Reflow Standards#

  • Respect user-selected text scaling from platform settings and in-app preferences.
  • Support scaling range up to at least 200% equivalent for core journeys.
  • Use fluid containers; avoid fixed heights around text blocks.
  • Truncation at larger text sizes must have explicit expand affordances.
  • When text scale increases, preserve action reachability from ergonomics standards.

Implementation note:

  • Reuse the scaling model from apps/tara/mobile/src/utils/accessibility.ts (scaleFontSize, createScaledTextStyle) when building OSHUN shell typography utilities.

8. Multilingual and Localization Readability#

  • Allow 30-50% text expansion in labels and buttons for localization.
  • Do not encode meaning using color alone; keep explicit labels.
  • Ensure bi-directional text readiness for future RTL locales.
  • Date/time and numeric formats should use locale-aware rendering in constrained spaces.

9. Error, Empty, and Loading Readability#

  • Error title: short diagnostic statement (L1).
  • Error body: actionable next step in one sentence (L2/L5).
  • Empty states: one-line explanation + one clear action.
  • Skeleton loading must preserve likely text structure to reduce layout shift.

10. Accessibility and QA Acceptance Criteria#

A feature that introduces or changes text UI is not complete until:

  • It passes AA contrast checks for all text states.
  • It is validated at largest supported platform text size on iOS and Android.
  • No clipped text appears in core shell flows (Home, Explore, Activity, Profile).
  • Web/PWA content remains readable from 320px width upward.
  • Screen reader labels reflect visible information hierarchy.

11. Delivery Checklist for Coding Agents#

For each new OSHUN surface:

  • Define L0-L5 mapping in design spec and component props.
  • Bind styles to semantic typography tokens, not ad hoc numbers.
  • Add line-clamp behavior with explicit expansion where required.
  • Run text-scale screenshots at normal and max accessibility sizes.
  • Validate small-screen readability in light and dark themes.
  • Add regression tests for text clipping and overflow on key cards.