# Heading Sizes Descend with Level
**MUST** · **ID:** `content-heading-size-descends` · **Category:** content
**Source:** [jakubkrehel](https://github.com/jakubkrehel/skills)
**Interactive version:** https://ui-guides-agent-rules.netlify.app/principles/content-heading-size-descends
> MUST: Pick the heading tag from the document outline and the size from a DESCENDING step of the type scale — a lower level must never render larger than a higher one on the same page. Never reach for a tag because it "looks right". Adjacent levels may share a size at the small end if weight or spacing keeps them distinct; a line that must be the loudest thing on the card without owning a rank is a `` at display size. Distinct from `content-rams-heading-levels`, which is about SKIPPING levels (a11y outline) — here the tags are sequential and lint passes, but the render contradicts them.
Map every heading level to a descending step of the scale so a lower level never renders larger than a higher one
This is a different failure from content-rams-heading-levels, and worth separating carefully. That rule is about SKIPPING levels — h1 straight to h3 — which lint catches and WCAG 1.3.1 names. This one is the inverse-SIZE failure, and every tag in it is sequential, so the lint passes: an `
` set at `text-base` because it looked right in the card, wrapping an `` at `text-2xl` because that was the line the designer wanted read first. The tags are legal; the render contradicts them. A screen reader navigates the outline and hears "Revenue up 12%" as subordinate to "Q3 report"; the page says the opposite, in twice the pixels. Whenever a child level renders larger than its parent, the tag was picked for its default size instead of from the document structure. Take the tag from the outline, take the size from a descending step of the scale, and when a line genuinely needs to be the loudest thing on the card without owning a rank, make it a `
` at display size — it can be as big as it likes and it stays out of the outline entirely.
## Bad — do not do this
`content-heading-size-descends-bad`
```tsx
/**
* Bad: the tags are sequential (h2 → h3, nothing skipped), so the usual heading
* lint passes. The SIZES run backwards: the h2 was set at `text-base` because it
* "looked right" in the card, and the h3 inside it is `text-2xl` because that is
* the line the designer wanted people to read first.
*
* The outline panel on the right is what a screen reader navigates by. Compare it
* with the card: the two orders disagree.
*
* (The heading tags are rendered as labelled divs so this demo does not inject
* headings into the page's own outline. The class names are the real ones.)
*/
export function HeadingSizeDescendsBad() {
return (
What the eye sees
{/*
*/}
Q3 report
{/* — a level DOWN, rendered twice the size */}
Revenue up 12%
Growth came almost entirely from renewals in the enterprise tier.
What the screen reader announces
-
h2
Q3 report
16px
-
h3
Revenue up 12%
24px
The outline says “Revenue up 12%” is subordinate to “Q3 report”.
The page says the opposite, in 8 extra pixels. A child level rendering larger than its
parent means the tag was picked for its default size, not from the outline.
);
}
```
## Good — do this
`content-heading-size-descends-good`
```tsx
/**
* Good: the tag comes from the document outline, the size comes from a descending
* step of the type scale. h2 (24px) > h3 (16px), and the visual order now agrees
* with the order a screen reader reads out.
*
* The "big line" the designer wanted is still there — it is just not a heading. A
* display-size `` carries the emphasis without claiming a rank in the outline.
*
* (The heading tags are rendered as labelled divs so this demo does not inject
* headings into the page's own outline. The class names are the real ones.)
*/
export function HeadingSizeDescendsGood() {
return (
What the eye sees
{/*
— highest level on the card, largest step */}
Q3 report
{/* Not a heading at all: a display-size paragraph. It can be as loud as it likes. */}
Revenue up 12%
{/*
— one level down, one step down the scale */}
Enterprise renewals
Growth came almost entirely from renewals in the enterprise tier.
What the screen reader announces
-
h2
Q3 report
24px
-
h3
Enterprise renewals
16px
Sizes descend with the level, so the outline and the page tell the same story. The subtitle
is loud and still not in the list — because it is a <p>, styled with
CSS, not an h3 borrowed for its size.
);
}
```
## References
- [jakubkrehel — better-typography SKILL.md](https://raw.githubusercontent.com/jakubkrehel/skills/main/skills/better-typography/SKILL.md)
- [jakubkrehel — spacing-and-sizing.md](https://raw.githubusercontent.com/jakubkrehel/skills/main/skills/better-typography/spacing-and-sizing.md)
- [MDN — Heading elements](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/Heading_Elements)