Preview

The default form: a page-title-scale heading with an actions slot. The container is neutral and transparent; color is the consumer’s job.

<PageHeader title="Requirements">
  <EsaButton slot="actions" variant="primary" icon="plus">New requirement</EsaButton>
</PageHeader>

There is no description slot

This component takes no lede, subtitle, or description. A page header carries the page’s name and its actions; a sentence explaining the page to its reader is text about the page rather than of it, and the page’s own data and structure are what say what it is.

Identifying facts go in meta, which takes labeled pairs rather than free text (see below). A figure the page exists to report is a stat, so put it in an esa-stat under the header, where it reads at stat scale.

Meta pairs

Each entry in meta is a { label, value } pair: the label is the field's name in the record, the value is what is stored there. Both parts are required.

That is why it is a prop and not a slot. A slot takes anything, and what it took was a row of facts glued together with separators, like SFO, Shoreline Protection Program, Beacon compliance platform. A client, a program and a platform are three different kinds of thing, and nothing on that line says which is which. A pair cannot be written that way.

A period pair states the calendar it counts by. This domain runs fiscal years and water years alongside calendar ones, and a compliance figure means a different span under each.

<PageHeader
  title="Quarterly Compliance Summary"
  meta={[
    { label: 'Project', value: 'Delta Conveyance Project' },
    { label: 'Reporting period', value: 'Calendar Q2 2026' },
    { label: 'Lead agency', value: 'DWR' },
  ]}>
  <EsaButton slot="actions" variant="ghost" appearance="outline" icon="download">Export</EsaButton>
</PageHeader>

Eyebrow + display prominence (hero)

For a landing or hero, add an eyebrow (with an optional leading icon) and bump the title to the display role with prominence="display". The actions here are link-buttons — esa-button with an href.

<PageHeader
  eyebrow="Annual Report"
  icon="award"
  prominence="display"
  title="2026 in Review">
  <EsaButton slot="actions" variant="primary" href="/report">Read the report</EsaButton>
  <EsaButton slot="actions" variant="ghost" appearance="outline" href="/data">View the data</EsaButton>
</PageHeader>

With breadcrumbs

Host an esa-breadcrumbs in the breadcrumbs slot for a record or nested page.

<PageHeader title="Permit #4471" eyebrow="Filed 12 days ago">
  <nav slot="breadcrumbs">Permits / Active / #4471</nav>
  <EsaButton slot="actions" variant="ghost" appearance="outline" icon="pencil">Edit</EsaButton>
</PageHeader>

API

Slots

Accessibility

• The title is the page <h1> — there should be exactly one per page; keep heading order sensible below it.
• The host defaults to a <header> landmark; use as="div" when the header is nested inside another landmark.
• The eyebrow icon is decorative (rendered via esa-icon, aria-hidden) — the eyebrow text carries the meaning.

Theming surface

Every public token this component reads, extracted from its source at build time, split by blast radius: the hooks that belong to this component, then the shared and system tokens it consumes alongside everything else. The Resolves to column walks each token's real lineage — component → semantic → primitive → raw value — so you can see exactly where re-pointing it lands. A spoke re-skins by overriding these in its theme-<slug>.css; component internals are never edited. No hook for what you need? File it with /request-lego.

Type roles it names

This component does not set a size, weight, face or tracking of its own — it names a composite, and the composite carries all five. A composite is a class rather than a token, so none of it appears in the tables below; re-theme text by re-pointing the token family, not by editing the component.

Wired to this component

None. This component has no hooks of its own — it themes entirely through the shared tokens below, so every override here also moves its siblings.

Shared tokens it reads

Owned by a family or by the semantic layer. Still overridable — but scope the override (esa-foo { --form-border-color: … }) unless you mean to move everything that reads it. Reach says what else that is.