# Composition — Hierarchy

Every section of a page should answer four questions in order: **What kind of thing is this?** (eyebrow), **What is it called?** (headline), **What does it do or say?** (body), **What can I do next?** (action). Build sections in that order and the visual hierarchy follows automatically.

## Eyebrow → Headline → Body → Action

Use `SectionHeader` for section-level content, `Title` for page or block headings, plain paragraphs for body, and `ButtonGroup` (or `ButtonTray`) for actions.

```tsx
import {
  SectionHeader,
  Title,
  ButtonGroup,
  Button,
} from 'arrow-react-bootstrap';

<section>
  <SectionHeader
    eyebrow="Plans"
    headline="Choose your home internet"
    supportingText="Switch any time. No annual contracts."
  />
  <p>Pick a plan that fits your speed and price needs.</p>
  <ButtonGroup>
    <Button variant="primary">Choose plan</Button>
    <Button variant="tertiary">Compare plans</Button>
  </ButtonGroup>
</section>
```

For headings outside a SectionHeader, use `Title` with a `headline` prop (not children) and pick a `heading` level that matches the document outline.

```tsx
<Title headline="Account settings" heading="h2" hierarchy="primary" />
```

## Action emphasis

Use exactly three levels of action emphasis. Pick the lowest level that still communicates the action's importance.

| Variant | Use for | Frequency per visible section |
|---|---|---|
| `primary` | The single most important action — the one a user is most likely to take next. | **One** |
| `secondary` | Alternate or supporting action alongside the primary (e.g., Cancel next to Submit). | Zero or one |
| `tertiary` | Low-emphasis actions like "Learn more", "Skip", or inline navigation. | Multiple OK |

For link-styled actions inside body copy, use `Link`. For button-styled anchors, use `LinkStyledAsButton`.

### Only one primary button per visible section

Two primary buttons in the same viewport split the user's attention and dilute hierarchy. If two actions feel equally important, one of them is actually secondary — pick.

```tsx
// WRONG — two primaries compete
<ButtonGroup>
  <Button variant="primary">Save</Button>
  <Button variant="primary">Submit</Button>
</ButtonGroup>

// RIGHT — one primary, one secondary
<ButtonGroup>
  <Button variant="primary">Submit</Button>
  <Button variant="secondary">Save draft</Button>
</ButtonGroup>
```

The same rule applies across cards, banners, and modals stacked in the same viewport — count visible primaries together, not per component.

## Type scale

Arrow ships a fixed type scale. Use it via `Title` or the `tdds:text-*` utility classes; do not hand-tune font sizes.

- **Display / Title 1–4** — page-level and major section headings (use `Title` with `hierarchy="primary"` or `tdds:text-title-1` through `tdds:text-title-4`)
- **Headline / Subheadline** — block headings inside sections
- **Body** — paragraphs, descriptions, list content
- **Caption / Footnote** — metadata, fine print, labels

The `Title` component applies a responsive max-width (75% at 768px, 50% at 1024px) so primary titles do not stretch across full-width layouts. For full-bleed headings (hero banners, billboards), use a raw `<h1 className="tdds:text-title-1">` instead.

See `foundations/color.md` and the per-component file `guidelines/components/title.md` for the full scale and color tokens.

## Hierarchy checklist

- One primary action per visible section
- One H1 per page; nested sections use H2/H3
- Eyebrow text uses `SectionHeader` or `tag` props — never style your own
- Body copy uses paragraph elements, not styled headings
- Skip levels only when intentional and rare — usually `<h2>` follows `<h1>`
