open-design/craft/typography-hierarchy.md

Typography hierarchy craft rules

Shared hierarchy contracts that layer on top of typography.md. This file does not repeat scale ranges or tracking values — those live in typography.md. This file defines how hierarchy behaves: entry points, rhythm, tension, and the conditions under which controlled violations are allowed. This contract applies per-surface (a page with multiple pacing resets may establish new primaries at intentional intervals), not globally.

Opt in via od.craft.requires: [typography, typography-hierarchy]. Aesthetic-specific variants (e.g. typography-hierarchy-editorial) extend this.

---

The core contract

Every typographic surface must satisfy all three:

1. One dominant entry point. The eye needs a place to start. One element wins the hierarchy — not two, not three. If everything competes, nothing leads.
2. Intentional rhythm between levels. Hierarchy is not a list of sizes. It is the contrast between them. Adjacent levels that are too close in scale, weight, or spacing produce a flat, undifferentiated surface.
3. Recoverable information flow. Hierarchy may be inverted, collapsed, or disrupted — but a reader must still be able to reconstruct the content structure without re-reading. If they can't, it's chaos, not tension.

---

Hierarchy vectors

Scale is one lever. Use all five.

Vector	What it controls	Hierarchy direction
Scale	Size contrast between levels	Large → small reads as primary → secondary
Weight	Mass contrast between levels	Heavier reads as primary (see Controlled violations for weight inversion)
Spacing	Breathing room around an element	More space = more visual importance
Tracking	Tension and velocity	Tighter = faster; wider = ceremonial, slower
Alignment	Relationship to the grid/edge	Breaking alignment signals importance

No single vector is required. A heading may lead through spacing alone if scale is deliberately suppressed. A pull quote may lead through alignment break. Identify which vectors are active and make sure at least two are working in the same direction for the dominant element.

---

Semantic role ≠ visual role

Allowed. Not an error. Not a lint violation.

An <h1> may render visually quieter than a nearby <p> if the composition requires it. Body copy may behave like display typography. A label may visually outrank a heading.

The condition: information flow must remain intact. A user who reads linearly must still understand what is important, what supports it, and what is incidental — regardless of which element "wins" visually.

---

Hierarchy rhythm — the two failure modes

Flat hierarchy

Everything lands at roughly the same visual weight. The surface reads as a wall. Usually caused by:

• Scale steps that are too close (e.g. 18 / 20 / 22 px for three levels)
• Weight used only once (everything is regular, or everything is medium)
• Uniform spacing between all elements

Fix: increase contrast between levels. Use at least two vectors simultaneously.

Noise hierarchy

Too many elements fighting for dominance. Everything is bold, large, or accented. The eye has no resting point and no path.

Fix: promote one element deliberately. Demote everything else — including things that feel important. Hierarchy is relative, not absolute.

---

Controlled violations

The following are explicitly allowed when the three core contracts are met:

Violation	Allowed when
Body copy at display scale	It is the intended entry point and nothing else competes
Heading rendered lighter than body	Intentional visual inversion with intact information flow
Zero scale contrast between levels	Hierarchy is carried entirely by spacing or tracking
No heading-level element visible	Hierarchy is emergent from layout/spacing alone
Primary-level spacing applied to secondary element	Creates deliberate tension while maintaining information flow

"Information flow remains intact" safeguards:

• DOM/reading order still matches content meaning (no layout inversion breaks narrative)
• Proximity groups the inverted element with its parent/context
• Only one primary exists in the visual region (no competing co-primaries)
• A quick scan can identify entry point / support / incidental roles without rereading

---

Spacing as hierarchy

Spacing is a full hierarchy vector. A typographic level can be elevated entirely through surrounding whitespace without changing its size or weight.

Rules:

• Space above an element signals its relationship to what came before.
• Space below an element signals its relationship to what follows.
• An isolated element with large surrounding space reads as display-level regardless of its font size.
• Uniform spacing between all elements destroys spatial hierarchy.

---

Three-level working model

Most surfaces can be mapped to three functional levels:

Level	Role	Typical vectors
Primary	Entry point. One at a time per visual region; long-form surfaces may re-establish at intentional pacing resets.	Scale, spacing, or alignment break
Secondary	Structure. Subdivides or supports primary.	Weight, scale step, or tracking shift
Tertiary	Incidental. Labels, captions, metadata.	Scale reduction, weight reduction, or positive tracking

More than three visible levels above the fold is usually a composition problem, not a hierarchy opportunity. Collapse or demote before adding a fourth level.

Long-form surfaces: May re-establish a primary at intentional pacing resets (e.g. a new section with its own headline and breathing room). Never maintain two simultaneous primaries within the same visual region.

---

Anti-patterns

• Graduated weight ladder — regular → medium → semibold → bold → extrabold, each level one step heavier. Reads as a default scale, not authored hierarchy. Weight should jump, not step.
• Uniform section spacing — every section gap is the same value. No hierarchy information is carried by spacing. Vary it deliberately.
• Heading as the only hierarchy vector — the heading is large and bold; everything else is flat. The heading does all the work. This is a sign that spacing and tracking are not being used as vectors.
• Symmetrical emphasis — two elements receive equal visual weight as co-primaries. Pick one. The other becomes secondary.
• Size-only hierarchy — all contrast is in font size alone. Weight, spacing, tracking, and alignment are uniform across levels. Fragile — any layout constraint that collapses the size contrast destroys the hierarchy.

---

Lint

• One element is unambiguously dominant above the fold.
• At least two hierarchy vectors are active on the dominant element.
• No two adjacent levels share the same scale, weight, AND spacing.
• Spacing between levels varies — at least one gap is ≥1.5× the others or represents one typographic scale step (e.g. one token unit like gap-md vs gap-sm). (guidance)
• Semantic/visual role inversions remain structurally readable.
• Flat hierarchy: scale steps between levels are ≥1.25× apart OR compensated by a weight or spacing jump. (guidance)
• Noise hierarchy: no more than one element reads as primary above the fold.