Content hierarchy
Help the user make the page's primary decision. Inventory real content before deciding which blocks the page should contain.
Work
- Name the user, page purpose, and next useful action. For a reading page, comprehension may be the main job rather than conversion.
- Rank essential decision information, supporting explanation, and incidental metadata. Keep consequences near consequential actions.
- Establish a descriptive title, meaningful section headings, and reading order. Do not use visual size to choose semantic heading levels.
- Reduce competing emphasis through grouping, position, and copy before adding borders or cards.
- State what moves or collapses on narrow screens and how users retrieve it. Essential content must remain available.
- For existing pages, identify keep, rewrite, move, and remove decisions with reasons. Do not fabricate proof, customer quotes, or product capabilities to make a layout convincing.
Deliver
A ranked content outline with sample copy where useful, action labels, responsive order, and one observable acceptance condition. Keep the response proportional to the page.
Follow this shape:
Page purpose: ...
Primary decision: ... H1: ...
Primary: ...
Secondary: ...
Tertiary: ...
Actions: Primary / Secondary / Destructive
Responsive priority: ...
Move / defer / remove: ...
Accessibility notes: ...
Example: an invitation screen needs recipient, organization, role, and access consequence before “Send invitation.” A decorative illustration is secondary; the role explanation is not.
Check that the first visible information answers the user's immediate question, that heading/keyboard order matches the visual sequence, and that text expansion does not bury the action. Use $layout for region sizing; $craft for a rendered composition and visual refinement.
Worked example
Page purpose: Convince a visiting foreman to start a free trial.
Primary decision: Start free trial. H1: Know where your crew is this week.
Primary: 3-step explanation (schedule → assign → notify); screenshot of the weekly board.
Secondary: feature bullets (offline mode, SMS notifications); customer quote.
Tertiary: pricing link, FAQ link, legal links.
Actions: Primary — Start free trial; Secondary — See pricing; Destructive — none.
Responsive priority: H1 → CTA → screenshot → steps → features.
Move / defer / remove: Move deep-dives to a features page; remove the second hero CTA.
Accessibility notes: single h1; h2 per section; CTA is a real link.
Gotchas
- Do not choose heading levels by visual size; keep semantic order aligned with visual and keyboard sequence.
- Do not add cards, borders, or emphasis to fix competition; regroup, reposition, and rewrite copy first.
- Do not fabricate quotes, metrics, or capabilities to fill a thin page.
- Do not hide essential content on narrow screens without a retrieval path.
- Do not separate consequential actions from their consequence explanation.
Boundaries
- Do not use when region sizing or page shell is the question — use
$layout instead.
- Do not use when whole-site navigation is undecided — use
$sitemap instead.
1---2name: hierarchy3description: Rank a screen’s information and actions; improve headings, decision support, and narrow-screen priority. Use when planning what belongs on a page before layout, visual design, or implementation.4---56# Content hierarchy78Help the user make the page's primary decision. Inventory real content before deciding which blocks the page should contain.910## Work1112- Name the user, page purpose, and next useful action. For a reading page, comprehension may be the main job rather than conversion.13- Rank essential decision information, supporting explanation, and incidental metadata. Keep consequences near consequential actions.14- Establish a descriptive title, meaningful section headings, and reading order. Do not use visual size to choose semantic heading levels.15- Reduce competing emphasis through grouping, position, and copy before adding borders or cards.16- State what moves or collapses on narrow screens and how users retrieve it. Essential content must remain available.17- For existing pages, identify keep, rewrite, move, and remove decisions with reasons. Do not fabricate proof, customer quotes, or product capabilities to make a layout convincing.1819## Deliver2021A ranked content outline with sample copy where useful, action labels, responsive order, and one observable acceptance condition. Keep the response proportional to the page.2223Follow this shape:2425**Page purpose:** ...26**Primary decision:** ... **H1:** ...27Primary: ...28Secondary: ...29Tertiary: ...30Actions: Primary / Secondary / Destructive31Responsive priority: ...32Move / defer / remove: ...33Accessibility notes: ...3435Example: an invitation screen needs recipient, organization, role, and access consequence before “Send invitation.” A decorative illustration is secondary; the role explanation is not.3637Check that the first visible information answers the user's immediate question, that heading/keyboard order matches the visual sequence, and that text expansion does not bury the action. Use `$layout` for region sizing; `$craft` for a rendered composition and visual refinement.3839## Worked example4041**Page purpose:** Convince a visiting foreman to start a free trial.42**Primary decision:** Start free trial. **H1:** Know where your crew is this week.43Primary: 3-step explanation (schedule → assign → notify); screenshot of the weekly board.44Secondary: feature bullets (offline mode, SMS notifications); customer quote.45Tertiary: pricing link, FAQ link, legal links.46Actions: Primary — Start free trial; Secondary — See pricing; Destructive — none.47Responsive priority: H1 → CTA → screenshot → steps → features.48Move / defer / remove: Move deep-dives to a features page; remove the second hero CTA.49Accessibility notes: single h1; h2 per section; CTA is a real link.5051## Gotchas5253- Do not choose heading levels by visual size; keep semantic order aligned with visual and keyboard sequence.54- Do not add cards, borders, or emphasis to fix competition; regroup, reposition, and rewrite copy first.55- Do not fabricate quotes, metrics, or capabilities to fill a thin page.56- Do not hide essential content on narrow screens without a retrieval path.57- Do not separate consequential actions from their consequence explanation.5859## Boundaries6061- Do not use when region sizing or page shell is the question — use `$layout` instead.62- Do not use when whole-site navigation is undecided — use `$sitemap` instead.
mattjmdesign