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

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
