# PageHeader

> The top of a page: its title, a line about it and its main actions.

- **Level**: molecule · **Status**: stable · **Role**: surface
- **Import**: `import { PageHeader } from "@rrios-forge/ui/molecules/page-header";`
- **Source**: `packages/ui/src/molecules/page-header`

**Purpose.** Orient the user at the top of a view. Composes breadcrumb, eyebrow, title (h1 by default), badge, description, actions and an optional Tabs row below. Renders a `<header>` landmark.

**Size axis** (validated under `Foundations/Identity/Display Hierarchy`, Heading mapping per ADR-006):

| Size | Title size | When to use |
|---|---|---|
| `sm` | Heading.md (24 px) | Settings sub-page where the breadcrumb already names the location. Title is technical, calm, secondary to the breadcrumb. |
| `md` | Heading.lg (30 px) | **Default app page** — the consumer landed here directly; the title leads the page without shouting. Members, Deployments overview, Inbox. |
| `lg` | Heading.display (48 px) | **Hero / product / marketing page** — landing surfaces, product overview, empty page top. Reserved; reach for it only when the title is meant to dominate. |

**Composition slots** (rendered in this order, each optional except `title`): `breadcrumb` → `eyebrow` → `title` (+ optional `badge` inline) → `description` → `actions` (right-aligned) → `tabs` (below).

**Patterns consulted**: `Patterns/Page Shells · PageHeader`, `Patterns/Navigation · BreadcrumbForLocation + TabsForLocalContext`, `Patterns/Information Architecture · MetadataAndActions`, `Patterns/Visual Priority · ActionHierarchy`.

## Use it for

- Page header / section title → `PageHeader` / `SectionHeader`
- Controls that must stay in reach while the screen scrolls (filters, search, a view switch, section tabs) — or a selection's / a form's actions → `PageShell.StickyBar` (ADR-045) under the `PageHeader`, `edge="bottom"` for actions: at rest part of the page; pinned, it condenses onto glass and carries the page title small. One bar per edge; never hides focus

## Axes

| Axis | Part | Values | Default | Meaning |
|---|---|---|---|---|
| `size` | — | `sm` `md` `lg` | `md` | Ergonomic scale, in three families (control, text, container). |
| `presentation` | — | `editorial` `title` | `editorial` | How the same thing is staged. |

## Stories

- [Playground](/?path=/story/components-molecules-pageheader--playground) · frame: `/iframe.html?id=components-molecules-pageheader--playground&viewMode=story`
- [With breadcrumb](/?path=/story/components-molecules-pageheader--with-breadcrumb) · frame: `/iframe.html?id=components-molecules-pageheader--with-breadcrumb&viewMode=story`
- [With actions](/?path=/story/components-molecules-pageheader--with-actions) · frame: `/iframe.html?id=components-molecules-pageheader--with-actions&viewMode=story`
- [With tabs](/?path=/story/components-molecules-pageheader--with-tabs) · frame: `/iframe.html?id=components-molecules-pageheader--with-tabs&viewMode=story`
- [Dense](/?path=/story/components-molecules-pageheader--dense) · frame: `/iframe.html?id=components-molecules-pageheader--dense&viewMode=story`
- [Product page](/?path=/story/components-molecules-pageheader--product-page) · frame: `/iframe.html?id=components-molecules-pageheader--product-page&viewMode=story`
- [Settings page](/?path=/story/components-molecules-pageheader--settings-page) · frame: `/iframe.html?id=components-molecules-pageheader--settings-page&viewMode=story`

## Decisions that name it

- ADR-008 — Layout layer: refined `Grid` + new `Container`
- ADR-009 — Editorial Frame: PageShell v3 + new `TopBar` molecule
- ADR-010 — PageShell v4: bottom dock + mobile floating bubble
- ADR-014 — PageShell: Apple Mail / macOS Big Sur visual register
- ADR-016 — NotificationCenter v2: Popover → Drawer + Provider/Hooks
- ADR-022 — The material family: `solid` and `vibrant`
- ADR-029 — The page gutter belongs outside the frame
- ADR-044 — Navigation is a rail that peeks
- ADR-045 — A screen's controls pin and condense

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