# Heading

> The title ramp, from section headings to the display serif.

- **Level**: atom · **Status**: stable · **Role**: content
- **Import**: `import { Heading } from "@rrios-forge/ui/atoms/heading";`
- **Source**: `packages/ui/src/atoms/heading`

**Purpose.** Section / page title. `as` (h1-h6) is **required** — Heading refuses to guess a document outline level. Visual `size` (sm | md | lg | display) is independent of the rendered HTML level. Pick the level for the outline; pick the size for the visual rhythm.

**Size guidance** (validated by `Foundations/Identity/Display Hierarchy`):

| Size | font-size | tracking | When to use |
|---|---|---|---|
| `sm` | 20 px | tight (-0.01em) | Card titles, in-page section heads, dense content groups |
| `md` | 24 px | compact (-0.015em) | Sub-section heads, MetricCard values, settings sub-pages where breadcrumb already locates the user |
| `lg` | 30 px | snug (-0.022em) | **Default app page lead** — Settings overview, Dashboard, content section pages |
| `display` | 48 px | hero (-0.03em) | **Empty pages, marketing surfaces, hero / lead areas** where the heading is the protagonist |

**Why no `6xl` (60 px).** Tested against three real surfaces (Settings header, Empty page, Dashboard lead) under `Foundations/Identity/Display Hierarchy` and rejected — no real surface needed it. The ramp is deliberately short. Extend the surrounding composition before reaching for a bigger size.

**Related**: `Foundations/Identity/Overview`, ADR-006.

## Use it for

- Text / heading / helper / code / shortcut → `Text` / `Heading` / `Description` / `Code` / `Kbd`

## Axes

| Axis | Part | Values | Default | Meaning |
|---|---|---|---|---|
| `size` | — | `sm` `md` `lg` `display` | `md` | Ergonomic scale, in three families (control, text, container). |
| `weight` | — | `regular` `medium` `semibold` | `semibold` | Type weight within the ramp. |
| `tone` | — | `neutral` `muted` `inverse` `danger` | `neutral` | Which semantic colour family the element speaks in. |

## Stories

- [Playground](/?path=/story/components-atoms-heading--playground) · frame: `/iframe.html?id=components-atoms-heading--playground&viewMode=story`
- [Sizes](/?path=/story/components-atoms-heading--sizes) · frame: `/iframe.html?id=components-atoms-heading--sizes&viewMode=story`
- [Levels](/?path=/story/components-atoms-heading--levels) · frame: `/iframe.html?id=components-atoms-heading--levels&viewMode=story`
- [Tones](/?path=/story/components-atoms-heading--tones) · frame: `/iframe.html?id=components-atoms-heading--tones&viewMode=story`
- [In context](/?path=/story/components-atoms-heading--in-context) · frame: `/iframe.html?id=components-atoms-heading--in-context&viewMode=story`

## Decisions that name it

- ADR-005 — Visual operational rules: surfaces, interaction, motion
- ADR-006 — Geometry and typography signature
- ADR-014 — PageShell: Apple Mail / macOS Big Sur visual register
- ADR-046 — Markdown is painted with atoms, and apps fill its slots

## Always

- Tokens only (R04); variants are semantic axes, never appearance (R02).
- Typography and actions are Poesía atoms, never raw HTML with utilities.
- Vibrant panes need a ground and never nest (ADR-027).