# Skipped Heading Levels

**MUST** · **ID:** `content-rams-heading-levels` · **Category:** content
**Source:** [RAMS](https://www.rams.ai/)
**Interactive version:** https://ui-guides-agent-rules.netlify.app/principles/content-rams-heading-levels

> MUST: Heading levels must be hierarchical (h1-h6) without skipping levels. Never go from h1 to h3. Screen reader users navigate by headings; skipped levels break navigation.

Heading levels should not skip (e.g., h1 to h3 without h2)

Rams lists this as a Moderate ("consider fixing") check (WCAG 1.3.1) in its review table; the upstream skill is a checklist, so that terse row is the whole rule. Why it matters: headings create a document outline that screen reader users navigate by. Going from h1 to h3 suggests missing content. Keep the hierarchy sequential.

## Bad — do not do this

`content-rams-heading-levels-bad`

```tsx
export function RamsHeadingLevelsBad() {
  return (
    <div className="w-full max-w-sm space-y-4">
      <div className="bg-card border border-border rounded-lg p-4">
        <h4 className="font-medium mb-3">Skipped Heading Levels</h4>
        <div className="p-3 bg-muted rounded-lg space-y-2">
          <div className="text-lg font-semibold">h1: Page Title</div>
          <div className="pl-4 space-y-2">
            <div className="text-sm font-medium text-muted-foreground line-through">
              h2: (skipped!)
            </div>
            <div className="text-base font-medium">h3: Features</div>
            <div className="pl-4 space-y-1">
              <div className="text-sm font-medium text-muted-foreground line-through">
                h4: (skipped!)
              </div>
              <div className="text-xs font-medium">h5: Speed</div>
            </div>
          </div>
        </div>
        <div className="mt-3 bg-muted rounded p-2 font-mono text-xs">
          <code className="text-error">h1 → h3 → h5 (broken outline)</code>
        </div>
      </div>
      <p className="text-xs text-error">
        Broken document outline - users think content is missing
      </p>
    </div>
  );
}
```

## Good — do this

`content-rams-heading-levels-good`

```tsx
export function RamsHeadingLevelsGood() {
  return (
    <div className="w-full max-w-sm space-y-4">
      <div className="bg-card border border-border rounded-lg p-4">
        <h4 className="font-medium mb-3">Sequential Headings</h4>
        <div className="p-3 bg-muted rounded-lg space-y-2">
          <div className="text-lg font-semibold">h1: Page Title</div>
          <div className="pl-4 space-y-2">
            <div className="text-base font-medium">h2: Features</div>
            <div className="pl-4 space-y-1">
              <div className="text-sm font-medium">h3: Speed</div>
              <div className="text-sm font-medium">h3: Security</div>
            </div>
            <div className="text-base font-medium">h2: Pricing</div>
          </div>
        </div>
        <div className="mt-3 bg-muted rounded p-2 font-mono text-xs">
          <code>h1 → h2 → h3 (no skips)</code>
        </div>
      </div>
      <p className="text-xs text-success">
        Clear document outline for screen reader navigation
      </p>
    </div>
  );
}
```

## References

- [rams.md (skill source)](https://rams.ai/rams.md)
- [WCAG 1.3.1](https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships.html)