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.mddocs/releases/v1/scope/grid-gutter-max-width-rules.mddocs/releases/v1/scope/scan-first-content-hierarchy-rules.mddocs/releases/v1/specs/layout-density-tiers.mddocs/releases/v1/specs/studio-typography-dependency-and-data-contract-map.mdlibs/oshun/design-tokens/src/tokens.tsapps/oshun/web/src/design-system/tokens.tsapps/oshun/web/src/components/legal/LegalPageShell.tsxapps/oshun/web/src/components/domains/veritas/VeritasArticleReader.tsxdocs/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.mddefines the baseline body-size and long-form readability floorlibs/oshun/design-tokens/src/tokens.tsdefines the shared typography ramp- current surfaces such as
VeritasArticleReaderandLegalPageShellalready 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.mdalready sets the right floor:16pxminimum body text and60-75chprose caps on web/PWAVeritasArticleReader.tsxalready uses a dedicated serif reading lane and a calmer1.7line height for long-form reading- Studio typography governance already models readability validation with
longFormMeasurePassandclippingRegressionPass LegalPageShell.tsxstill uses13pxarticle 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#
bodySmas the default paragraph style for sustained readingcaptionor smaller tokens for core prosedisplaystyles 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
5lines 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
62chbecause trust metadata and excerpt markers already increase cognitive load. - Study compare lanes must not drop below roughly
36chon 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.45for 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-3sentences. - 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-4sentences. - 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
1200pxcontainer with no internal lane - metadata rows that visually outweigh the article or passage title
13pxor 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
16pxbody 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