Status: Draft v1.0 Owner: OSHUN Product Design + Mobile/Web Engineering Last Updated: February 16, 2026 Related:
docs/releases/v1/design/ux-principles.mddocs/releases/v1/design/ergonomics-requirements.mddocs/releases/v1/design/motion-language.mdapps/tara/mobile/src/theme/index.tsapps/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:
16logical px minimum. - Body line height:
1.45to1.7ratio. - Touch-context text controls must remain legible at arm-length viewing distance.
- Text contrast: WCAG AA minimum (
4.5:1normal text,3:1large 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:
14minimum. - Core reading text:
16default, may scale up. - Avoid using
12for 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-42characters per line. - Long-form mobile reading mode: target
30-45characters 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
8spacing 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
320pxwidth 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.