Eve library

OSHUN V1 Typography Measure, Line-Length, and Reading-Rhythm Rules

Guide

Revision 1

On this page

Status: Accepted v1.0
Owner: OSHUN Design + Product + Engineering
Last Updated: March 26, 2026
Implements: V1-UX-057
Related:

  • docs/releases/v1/design/readability-standards.md
  • docs/releases/v1/scope/grid-gutter-max-width-rules.md
  • docs/releases/v1/scope/scan-first-content-hierarchy-rules.md
  • docs/releases/v1/specs/layout-density-tiers.md
  • docs/releases/v1/specs/studio-typography-dependency-and-data-contract-map.md
  • libs/oshun/design-tokens/src/tokens.ts
  • apps/oshun/web/src/design-system/tokens.ts
  • apps/oshun/web/src/components/legal/LegalPageShell.tsx
  • apps/oshun/web/src/components/domains/veritas/VeritasArticleReader.tsx
  • docs/releases/v1/specs/todos.md

1. Purpose#

This document defines the canonical typography measure, line-length, and reading-rhythm rules for OSHUN V1 across ritual, story, evidence, and study-heavy surfaces.

OSHUN already has three useful signals in the repo:

  • docs/releases/v1/design/readability-standards.md defines the baseline body-size and long-form readability floor
  • libs/oshun/design-tokens/src/tokens.ts defines the shared typography ramp
  • current surfaces such as VeritasArticleReader and LegalPageShell already imply distinct prose modes

What is still missing is one canonical model for how different kinds of reading should feel. Without that model, the product drifts between contemplative copy, editorial prose, evidence-heavy reading, and study workflows without clear rules for measure or rhythm.

2. Current Repo Signals And Drift#

Current implementation evidence shows both strengths and drift:

  • READABILITY_STANDARDS.md already sets the right floor: 16px minimum body text and 60-75ch prose caps on web/PWA
  • VeritasArticleReader.tsx already uses a dedicated serif reading lane and a calmer 1.7 line height for long-form reading
  • Studio typography governance already models readability validation with longFormMeasurePass and clippingRegressionPass
  • LegalPageShell.tsx still uses 13px article body text, which is a useful implementation signal for narrative structure but falls below the canonical V1 body-size floor

This document resolves those conflicts. Existing local implementations should converge on these rules rather than be treated as independent precedent.

3. Core Doctrine#

3.1 Reading Is Not One Mode#

OSHUN has at least four distinct reading postures:

  • ritual
  • story
  • evidence
  • study-heavy

They should not share one generic text container.

3.2 Width Must Protect Comprehension#

Wider screens should create:

  • calmer margins
  • preserved reading lanes
  • side context
  • compare structures

They should not create billboard-width paragraphs.

3.3 Small Text Is Never A Shortcut For Density#

Dense information is allowed on evidence and operator-adjacent research surfaces, but core reading text still respects the readability floor.

bodySm, caption, and other compact styles are for metadata, not sustained paragraph reading.

3.4 Rhythm Matters As Much As Font Size#

Readable typography is not only about size. It also depends on:

  • paragraph length
  • line count per paragraph
  • spacing between blocks
  • how metadata interrupts prose
  • whether citations and notes feel adjacent without choking the reading lane

4. Canonical Reading Profiles#

Profile Primary job Emotional posture Default body token posture Typical surfaces
ritual settle, breathe, follow one reflective instruction set calm, spacious, unhurried bodyLg first, bodyMd only for secondary copy Tara guidance, restorative onboarding, grounding moments, reflective assistant copy
story read continuous editorial or narrative prose immersive, composed bodyLg or strong bodyMd with generous spacing welcome/editorial pages, long-form explainers, legal or trust pages, domain storytelling
evidence assess claims, read excerpts, and preserve trust cues precise, serious bodyMd for prose, bodySm for metadata only Veritas articles, grounded answers, claim review, source excerpts
study-heavy compare passages, commentary, notes, and source context scholarly, cumulative bodyMd primary, bodyLg allowed for primary passage text Nisaba passage reading, comparative study, notebooks, commentary flows

5. Token Usage Rules#

Use the shared ramp in libs/oshun/design-tokens/src/tokens.ts as the starting point.

5.1 Allowed Defaults#

Role Canonical token use
Orientation headline headingXl or headingLg; displayLg only for deliberate hero or ritual moments
Section headline inside reading headingMd or headingSm
Sustained ritual or story prose bodyLg preferred
Sustained evidence or study prose bodyMd preferred
Metadata, provenance, timestamps bodySm or caption
Dense codes, references, IDs monoSm or equivalent mono token

5.2 Forbidden Defaults#

  • bodySm as the default paragraph style for sustained reading
  • caption or smaller tokens for core prose
  • display styles inside dense evidence or study surfaces
  • mixing more than two text families in one reading lane

6. Canonical Measure Rules#

Measure targets below define the intended reading lane, not the full viewport or container width.

6.1 Mobile Measure Targets#

Profile Mobile target measure Notes
ritual 26-38 characters shorter lines preserve calm and reduce scan pressure
story 30-42 characters can run a little wider than ritual without becoming dense
evidence 28-38 characters narrow enough to keep claims and citations scannable
study-heavy 30-40 characters allows passage reading and annotation context without crowding

Rules:

  • Mobile reading remains one dominant lane.
  • Paragraphs that run longer than roughly 5 lines on common phones should be split unless deliberate long-form cadence is required.
  • Inline citations or annotation markers must not collapse the reading lane so aggressively that prose wraps into staccato fragments.

6.2 Tablet, Laptop, And Desktop Measure Targets#

Profile Primary reading lane target Secondary or compare lane target Notes
ritual 36-52ch none by default ritual surfaces should not become side-by-side prose on desktop
story 55-68ch 36-44ch optional side note rail good for continuous narrative reading
evidence 50-62ch 24-34ch metadata or evidence rail primary claim reading stays dominant; rails hold provenance and actions
study-heavy 52-66ch single lane 36-48ch per compare lane parallel passage or commentary views may split only when each lane stays readable

Rules:

  • Narrative and editorial reading should generally stay below 68ch.
  • Evidence reading should usually stay below 62ch because trust metadata and excerpt markers already increase cognitive load.
  • Study compare lanes must not drop below roughly 36ch on laptop or desktop.
  • If a compare or evidence surface cannot preserve readable lane widths, it should stack instead of forcing cramped side-by-side columns.

7. Line-Height Rules#

Profile Canonical body line-height Rationale
ritual 1.65-1.85 supports breath, pause, and calm pacing
story 1.6-1.75 supports continuous reading without feeling academic
evidence 1.55-1.7 preserves density while keeping excerpts and annotations legible
study-heavy 1.65-1.8 supports passage reading, commentary, and note comparison

Rules:

  • Do not go below 1.45 for sustained reading text.
  • Evidence metadata clusters may use tighter spacing, but the main prose lane should not inherit metadata line heights.
  • Passage text, quotations, and commentary are allowed to separate through spacing and indentation before relying on extra font changes.

8. Reading-Rhythm Rules#

8.1 Ritual Rhythm#

  • Keep paragraphs short, often 1-3 sentences.
  • Use visible breathing room between text blocks.
  • Avoid dense inline metadata inside the main reading lane.
  • If the surface includes guidance steps, each step should feel like a distinct breath, not one long instruction wall.

8.2 Story Rhythm#

  • Use paragraphs of roughly 2-4 sentences.
  • Preserve strong heading-to-body spacing so the prose feels intentional rather than document-like.
  • Decorative pull quotes or callouts are allowed only if they deepen narrative structure and do not interrupt every scroll segment.

8.3 Evidence Rhythm#

  • One claim, one reasoning unit, or one supporting excerpt per paragraph is the default.
  • Metadata should cluster before or beside the prose, not be injected between every sentence.
  • Citations and provenance should feel adjacent, but they must remain visually subordinate to the claim or excerpt being evaluated.

8.4 Study-Heavy Rhythm#

  • Distinguish passage, commentary, and notebook response through spacing before changing fonts or colors.
  • Preserve obvious separation between source text and user-authored notes.
  • Compare views should align passage blocks semantically where possible instead of forcing arbitrary same-height columns.

9. Viewport Behavior#

These rules build on docs/releases/v1/scope/grid-gutter-max-width-rules.md.

9.1 Mobile#

  • One primary reading lane only.
  • Long metadata rows should wrap below the title rather than squeeze the prose width.
  • Annotation or citation tools should collapse into expandable layers before they reduce the main reading lane.

9.2 Tablet#

  • Tablet may introduce side context, but the reading lane still stays primary.
  • Do not import laptop-grade dual reading columns onto tablet unless the lane widths remain within canonical measure.
  • Study-heavy surfaces should usually stack passage and notes on tablet.

9.3 Laptop#

  • Laptop is the first breakpoint where durable split reading is allowed.
  • This is the breakpoint most likely to expose cramped compare layouts, so it should be treated as the hard acceptance width.
  • If evidence rails or annotations consume too much width at laptop sizes, they should collapse or dock.

9.4 Desktop#

  • Extra width should become calmer margins, evidence rails, or secondary note context.
  • Do not widen the main prose lane just because desktop space exists.
  • Wide desktop compare views should still preserve readable per-column measure.

10. Surface Mapping#

Surface family Canonical profile
Tara instruction, restorative onboarding, calm empty states ritual
Welcome/editorial, long-form explainers, trust/legal reading story
Veritas article reading, grounded answer review, claim analysis evidence
Nisaba passages, notebooks, commentary, comparative reading study-heavy

Mixed surfaces should still choose one dominant reading profile. For example:

  • a Veritas page may include one story-like introduction, but the dominant profile remains evidence
  • a Nisaba study flow may include a ritual reflection block, but the dominant profile remains study-heavy

11. Anti-Patterns#

The following are non-canonical for OSHUN V1:

  • full-width desktop paragraphs in a 1200px container with no internal lane
  • metadata rows that visually outweigh the article or passage title
  • 13px or smaller default body text for sustained reading
  • study or evidence layouts that place two cramped text columns side by side on tablet
  • paragraph stacks broken by decorative cards every few sentences
  • citation badges, note dots, or helper chips that fragment each line of prose

12. Acceptance Standard#

A redesigned reading surface satisfies V1-UX-057 only when all are true:

  • it maps to one dominant reading profile
  • its sustained prose uses approved body tokens and respects the 16px body floor
  • its reading lane measure stays within the canonical range for that profile
  • its rhythm supports scanning and comprehension instead of incidental density
  • mobile, tablet, laptop, and desktop captures confirm that widening the viewport does not simply widen paragraphs