PillHeader

Hero example

When to use

Reach for PillHeader at the top of marketing How-It-Works sections — each major section opens with a PillHeader showing the lifecycle stage label on the left and the primary CTA + Docs link on the right. The visual identity is "glass pill spans the full content width." The pattern reads as a section anchor: it tells the reader which phase they're looking at and gives them a way to act on it (try the dashboard) or read more (docs).

Don't reach for PillHeader inside the dashboard — the marketing-tier glass-pill geometry doesn't fit a dense product surface. For dashboard section headers use DisplayHeading + a buttons row. Don't use PillHeader for navigation either; it's structural, not navigational.

Anatomy

Two structural regions inside a <div class="glass m-pill-header">:

1. Label region (.m-pill-header__label). Optional icon prop (typically a lifecycle dot — peach for Create, amber for Manage, lavender for Exit) + label text.
2. Actions region (.m-pill-header__actions). Primary CTA (<a class="btn btn--pri btn--sm-pill">) + Docs link (<a class="btn btn--ghost btn--sm-pill"> with a trailing ↗ glyph).

The whole pill sits on the Glass material — the marketing-page bloom backdrop provides the saturation that makes the refraction land.

Props

primaryHref and docsHref default to "#" — the design-site preview uses these to render without consumer wiring. In production, both are required.

States

Density

Density-agnostic — PillHeader is marketing-tier. The Glass material and CTA geometry stay fixed.

Themes

Tokens consumed

Surface reads --surface-glass. Primary CTA reads --action-primary. Ghost CTA reads --fg-muted with --ink-6 hover.

Accessibility

• Keyboard interactions. Tab → primary CTA → Docs link. Enter activates the focused link.
• ARIA roles and properties. No role override on the pill. CTAs are <a> elements with implicit link role. The lifecycle-dot icon (if passed) carries aria-hidden.
• Focus order. DOM order: primary CTA first, Docs second.
• Screen-reader expectations. Reading order: label text, "{primaryLabel}, link", "Docs, link." The trailing ↗ glyph is aria-hidden.
• Reduced motion. Hover lift collapses to opacity.
• Forced colors. Glass → Canvas with ButtonBorder. CTAs → ButtonFace / ButtonText.
• WIG rules. Real <a> for navigation (link-vs-button rule). Decorative ↗ glyph carries aria-hidden (decorative-icon rule). :focus-visible ring on each link.

Do / Don't

Recipes

This component appears in:

• The marketing site's How-It-Works section.
• Lifecycle-phase landing pages.

Code example

import { PillHeader } from "@matter/components";

export function CreateSectionHeader() {
  return (
    <PillHeader
      icon={<LifecycleDot phase="create" />}
      label="Create"
      primaryLabel="Try Create"
      primaryHref="/get-started/create"
      docsHref="/docs/lifecycle/create"
    />
  );
}

Source