Pivot Docs

    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-tag controls semantics only — it does not affect visual styling.


    Usage Guidance

    Do

    • Use pivot-title for all headings and display text to ensure correct typography tokens are applied.
    • Use pivot-tag to match the rendered heading level to the content’s position in the document hierarchy.
    • Use pivot-on-dark whenever the title appears on a dark or colored background.
    • Reserve display-* sizes for prominent hero and marketing moments; use headline-* sizes for page structure headings.

    Don’t

    • Don’t use pivot-title for body copy or paragraphs — use pivot-text instead.
    • Don’t rely on visual size alone to choose a pivot-tag value — 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-size and pivot-on-dark to stay consistent with design tokens.
    • Don’t skip heading levels in the document outline (e.g., jumping from h1 to h3), 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-title for headings and display text and pivot-text for paragraphs and body copy; the two share the same pivot-tag / pivot-on-dark pattern but render different typography scales.

    References


    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.