Title
pivot-title is a typographic heading component that renders display and headline text using a configurable HTML tag. It is the correct component for all headings, hero titles, and section labels — not for body copy (use pivot-text for that).
Quick Start
<!-- Default — display-3xl, renders as <h1> -->
<pivot-title>Page Title</pivot-title>
<!-- Specific display size on a semantic h2 -->
<pivot-title pivot-size="display-xl" pivot-tag="h2"
>Section Heading</pivot-title
>
<!-- Headline size -->
<pivot-title pivot-size="headline-lg" pivot-tag="h3">Subsection</pivot-title>
<!-- On a dark background -->
<pivot-title pivot-on-dark>Title on Dark</pivot-title>
<!-- Display title with emphasis -->
<pivot-title pivot-size="display-2xl"
>Build <em>something great</em></pivot-title
>Using the default slot
The default (unnamed) slot holds the title’s text content. It accepts plain text and inline markup — most notably <em>, which pivot-title styles specially:
- On
display-*size variants, slotted<em>elements receive a brand emphasis color and the browser’s default italic style is suppressed — emphasis is conveyed through color alone. - On
headline-*size variants, slotted<em>elements receive no special styling; they render with normal browser italics and no color change.
<pivot-title pivot-size="display-2xl">
Build <em>something great</em>
</pivot-title>When pivot-on-dark is also set, the emphasis color switches to its on-dark token counterpart automatically:
<div style="background: #1a1a1a; padding: 16px;">
<pivot-title pivot-size="display-2xl" pivot-on-dark>
Build <em>something great</em>
</pivot-title>
</div>Note: Emphasis color styling does not apply to
headline-*sizes.
Display Sizes
The display scale is designed for hero sections, banners, and large typographic moments. Nine steps are available from largest to smallest.
<pivot-title pivot-size="display-4xl">display-4xl</pivot-title>
<pivot-title pivot-size="display-3xl">display-3xl (default)</pivot-title>
<pivot-title pivot-size="display-2xl">display-2xl</pivot-title>
<pivot-title pivot-size="display-xl">display-xl</pivot-title>
<pivot-title pivot-size="display-lg">display-lg</pivot-title>
<pivot-title pivot-size="display-md">display-md</pivot-title>
<pivot-title pivot-size="display-sm">display-sm</pivot-title>
<pivot-title pivot-size="display-xs">display-xs</pivot-title>
<pivot-title pivot-size="display-2xs">display-2xs</pivot-title>Headline Sizes
The headline scale is designed for page and section headings. Seven steps are available.
<pivot-title pivot-size="headline-3xl">headline-3xl</pivot-title>
<pivot-title pivot-size="headline-2xl">headline-2xl</pivot-title>
<pivot-title pivot-size="headline-xl">headline-xl</pivot-title>
<pivot-title pivot-size="headline-lg">headline-lg</pivot-title>
<pivot-title pivot-size="headline-md">headline-md</pivot-title>
<pivot-title pivot-size="headline-sm">headline-sm</pivot-title>
<pivot-title pivot-size="headline-xs">headline-xs</pivot-title>On Dark
Use pivot-on-dark when pivot-title sits on a dark background. This switches both the base text color and the <em> emphasis color (for display sizes) to their on-dark token counterparts.
<div style="background: #1a1a1a; padding: 16px;">
<pivot-title pivot-on-dark>Title on dark surface</pivot-title>
<pivot-title pivot-size="display-2xl" pivot-on-dark>
Build <em>something great</em>
</pivot-title>
</div>Semantic Tag (pivot-tag)
By default, pivot-title renders an <h1> inside the shadow DOM. Use pivot-tag to render a different heading level or <span> without changing the visual style. Always choose the tag that reflects the content’s position in the document outline — the visual size chosen via pivot-size is completely independent of this and has no bearing on the outline.
<!-- h1 is the default -->
<pivot-title>Page title</pivot-title>
<!-- Render as h2 for a section heading -->
<pivot-title pivot-tag="h2" pivot-size="display-xl"
>Section heading</pivot-title
>
<!-- Render as span for non-heading contexts -->
<pivot-title pivot-tag="span" pivot-size="headline-lg"
>Decorative label text</pivot-title
>Allowed values for pivot-tag: h1, h2, h3, h4, h5, h6, span. Any other value falls back to <h1>.
Note:
pivot-tagcontrols semantics only — it does not affect visual styling.
Usage Guidance
Do
- Use
pivot-titlefor all headings and display text to ensure correct typography tokens are applied. - Use
pivot-tagto match the rendered heading level to the content’s position in the document hierarchy. - Use
pivot-on-darkwhenever the title appears on a dark or colored background. - Reserve
display-*sizes for prominent hero and marketing moments; useheadline-*sizes for page structure headings.
Don’t
- Don’t use
pivot-titlefor body copy or paragraphs — usepivot-textinstead. - Don’t rely on visual size alone to choose a
pivot-tagvalue — choose the level that is semantically correct for the document outline. - Don’t set font size or color directly via inline styles or utility classes; use
pivot-sizeandpivot-on-darkto stay consistent with design tokens. - Don’t skip heading levels in the document outline (e.g., jumping from
h1toh3), as this degrades screen reader navigation.
Accessibility
pivot-title’s accessible semantics come entirely from the rendered HTML tag set via pivot-tag — the component itself contributes no ARIA role, state, or property of its own.
Screen Reader Behavior
Because pivot-title renders a native <h1>–<h6> element (or <span>) directly — not a custom role — screen readers expose it with the implicit heading role and level that tag carries, and build the page outline from that (h1 → h2 → h3 …). The visual size chosen via pivot-size has no effect on this outline; only pivot-tag does. Always pair the two intentionally:
| Use case | Recommended pivot-tag |
|---|---|
| Primary page title | h1 (default) |
| Section heading | h2 |
| Subsection heading | h3–h6 matching document level |
| Non-heading decorative label | span |
When pivot-tag="span", no heading is exposed at all — screen reader users cannot jump to that content with heading-navigation shortcuts, so reserve span for content that is genuinely not a heading in the document outline.
Keyboard Navigation
pivot-title does not attach any keyboard handlers. When rendered as a heading tag, it is navigable via each screen reader’s heading-navigation shortcut (e.g., H / Shift+H in NVDA and JAWS, or the VoiceOver rotor). When rendered as <span>, it has no such navigation shortcut.
Focus Management
pivot-title itself is not focusable — it sets no tabindex and has no interactive role. It has no keyboard interaction of its own.
On Dark and Color Contrast
When using pivot-on-dark, verify that the background color meets the WCAG 2.2 minimum contrast ratio of 4.5:1 for normal text and 3:1 for large text (AA). The <em> emphasis color must also meet contrast requirements against the background.
Related Components
- Text — the companion body-copy component. Use
pivot-titlefor headings and display text andpivot-textfor paragraphs and body copy; the two share the samepivot-tag/pivot-on-darkpattern but render different typography scales.
References
- MDN — HTML heading elements
<h1>–<h6> - WCAG 2.2 — 1.3.1 Info and Relationships
- WCAG 2.2 — 1.4.3 Contrast (Minimum)
- WCAG 2.2 — 2.4.6 Headings and Labels
- ARIA Authoring Practices — Headings
API Reference
Props
| Name | Type | Default | Description |
|---|---|---|---|
pivot-size |
string |
"display-3xl" |
This will create an attribute: pivot-size="value" |
pivot-tag |
string |
"h1" |
This will create an attribute: pivot-tag="value" |
pivot-on-dark |
boolean |
false |
Presence of attribute means true: <pivot-text pivot-on-dark>...</pivot-text> |
Slots
| Name | Description |
|---|---|
default |
The title content to display. Slotted `<em>` elements receive emphasis color styling. |
figma_link: https://www.figma.com/design/10MEdQAgIyfij054E7CGV1/Pivot-Design-System–%E2%AD%90%EF%B8%8F?node-id=25377-88212
Display — light surface
<pivot-title pivot-size="display-4xl"
>display-4xl with <em>emphasis</em></pivot-title
>
<pivot-title pivot-size="display-3xl"
>display-3xl with <em>emphasis</em></pivot-title
>
<pivot-title pivot-size="display-2xl"
>display-2xl with <em>emphasis</em></pivot-title
>
<pivot-title pivot-size="display-xl"
>display-xl with <em>emphasis</em></pivot-title
>
<pivot-title pivot-size="display-lg"
>display-lg with <em>emphasis</em></pivot-title
>
<pivot-title pivot-size="display-md"
>display-md with <em>emphasis</em></pivot-title
>
<pivot-title pivot-size="display-sm"
>display-sm with <em>emphasis</em></pivot-title
>
<pivot-title pivot-size="display-xs"
>display-xs with <em>emphasis</em></pivot-title
>
<pivot-title pivot-size="display-2xs"
>display-2xs with <em>emphasis</em></pivot-title
>Headline — light surface
<pivot-title pivot-size="headline-3xl">headline-3xl</pivot-title>
<pivot-title pivot-size="headline-2xl">headline-2xl</pivot-title>
<pivot-title pivot-size="headline-xl">headline-xl</pivot-title>
<pivot-title pivot-size="headline-lg">headline-lg</pivot-title>
<pivot-title pivot-size="headline-md">headline-md</pivot-title>
<pivot-title pivot-size="headline-sm">headline-sm</pivot-title>
<pivot-title pivot-size="headline-xs">headline-xs</pivot-title>Display — dark surface
<pivot-title pivot-size="display-4xl" pivot-on-dark
>display-4xl with <em>emphasis</em></pivot-title
>
<pivot-title pivot-size="display-3xl" pivot-on-dark
>display-3xl with <em>emphasis</em></pivot-title
>
<pivot-title pivot-size="display-2xl" pivot-on-dark
>display-2xl with <em>emphasis</em></pivot-title
>
<pivot-title pivot-size="display-xl" pivot-on-dark
>display-xl with <em>emphasis</em></pivot-title
>
<pivot-title pivot-size="display-lg" pivot-on-dark
>display-lg with <em>emphasis</em></pivot-title
>
<pivot-title pivot-size="display-md" pivot-on-dark
>display-md with <em>emphasis</em></pivot-title
>
<pivot-title pivot-size="display-sm" pivot-on-dark
>display-sm with <em>emphasis</em></pivot-title
>
<pivot-title pivot-size="display-xs" pivot-on-dark
>display-xs with <em>emphasis</em></pivot-title
>
<pivot-title pivot-size="display-2xs" pivot-on-dark
>display-2xs with <em>emphasis</em></pivot-title
>Headline — dark surface
<pivot-title pivot-size="headline-3xl" pivot-on-dark>headline-3xl</pivot-title>
<pivot-title pivot-size="headline-2xl" pivot-on-dark>headline-2xl</pivot-title>
<pivot-title pivot-size="headline-xl" pivot-on-dark>headline-xl</pivot-title>
<pivot-title pivot-size="headline-lg" pivot-on-dark>headline-lg</pivot-title>
<pivot-title pivot-size="headline-md" pivot-on-dark>headline-md</pivot-title>
<pivot-title pivot-size="headline-sm" pivot-on-dark>headline-sm</pivot-title>
<pivot-title pivot-size="headline-xs" pivot-on-dark>headline-xs</pivot-title>Emphasis behavior of slotted <em> (display vs. headline)
Slotted <em> content is styled differently depending on the size category. On display-* sizes, <em> receives the brand emphasis color and its default italic style is suppressed. On headline-* sizes, <em> receives no special styling — it renders with plain browser italics and no color change.
<pivot-title pivot-size="display-lg"
>Display sizes show <em>emphasis</em> in brand color, without
italics</pivot-title
>
<pivot-title pivot-size="headline-lg"
>Headline sizes show <em>emphasis</em> in plain italics, without
color</pivot-title
>Semantic tag (pivot-tag)
<pivot-title pivot-tag="h1">h1 • display-3xl (default)</pivot-title>
<pivot-title pivot-tag="h2" pivot-size="display-2xl"
>h2 • display-2xl</pivot-title
>
<pivot-title pivot-tag="h3" pivot-size="display-xl"
>h3 • display-xl</pivot-title
>
<pivot-title pivot-tag="h4" pivot-size="display-lg"
>h4 • display-lg</pivot-title
>
<pivot-title pivot-tag="h5" pivot-size="headline-xl"
>h5 • headline-xl</pivot-title
>
<pivot-title pivot-tag="h6" pivot-size="headline-lg"
>h6 • headline-lg</pivot-title
>
<pivot-title pivot-tag="span" pivot-size="headline-md"
>span • headline-md</pivot-title
>