# Hierarchy

> 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.

- Skill: `mattjmdesign/hierarchy` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add mattjmdesign/hierarchy`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mattjmdesign/hierarchy/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: mattjmdesign (https://skillmd.com/u/mattjmdesign)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mattjmdesign/hierarchy

---


# 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.