# OSHUN Content Hierarchy and Readability Standards

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.

### 4.1 Recommended Text Styles

| 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.
