Pivot Docs

    Text

    pivot-text is a typographic body copy component that renders configurable HTML tags with design token–driven size and weight variants. It supports light and dark surface modes.


    Quick Start

    <!-- Default — body-md, regular weight, renders as <p> -->
    <pivot-text>The quick brown fox jumps over the lazy dog.</pivot-text>

    <!-- Larger size with bold weight -->
    <pivot-text pivot-size="body-xl" pivot-weight="bold">
    Bold extra-large body copy.
    </pivot-text>

    <!-- On a dark background -->
    <pivot-text pivot-on-dark>Light-colored text for dark surfaces.</pivot-text>

    Size and Weight Variants

    Four body text sizes are available, each mapping to a typography design token.

    <pivot-text pivot-size="body-xl">body-xl — extra large body copy</pivot-text>
    <pivot-text pivot-size="body-lg">body-lg — large body copy</pivot-text>
    <pivot-text pivot-size="body-md"
    >
    body-md — medium body copy (default)</pivot-text
    >

    <pivot-text pivot-size="body-sm">body-sm — small body copy</pivot-text>

    Four font weights are available and can be combined with any size.

    <pivot-text pivot-weight="regular">Regular — 400</pivot-text>
    <pivot-text pivot-weight="medium">Medium — 500</pivot-text>
    <pivot-text pivot-weight="semibold">Semibold — 600</pivot-text>
    <pivot-text pivot-weight="bold">Bold — 700</pivot-text>

    On Dark Surfaces

    Use pivot-on-dark when pivot-text sits on a dark background. This switches the text color to the on-dark token set (--global-color-text-on-dark-light).

    <div style="background: #1a1a1a; padding: 16px;">
    <pivot-text pivot-on-dark>Light-colored text for dark surfaces.</pivot-text>
    </div>

    pivot-on-dark also propagates dark link colors to any pivot-link elements slotted inside — pivot-on-dark does not need to be set separately on the link. Internally, pivot-text[pivot-on-dark] sets the --__link-color, --__link-color-hover, and --__link-color-visited custom properties (sourced from --global-color-text-on-dark-link-color, --global-color-text-on-dark-link-hover-color, and --global-color-text-on-dark-link-visited-color); these inherit down the DOM and are read by any slotted pivot-link’s own styles, overriding its default on-light link colors. See the pivot-link documentation for how the link consumes them.


    Semantic Element (pivot-tag)

    By default, pivot-text renders a <p> internally. Use pivot-tag to render a different semantic element without changing the visual style. This is useful for applying body text styling to heading elements or inline spans.

    <!-- Render as a heading for correct document outline, with body-md styling -->
    <pivot-text pivot-tag="h2" pivot-size="body-md">
    A heading that looks like body text
    </pivot-text>

    <!-- Render as a span for inline contexts -->
    <pivot-text pivot-tag="span" pivot-size="body-sm">
    Inline body-sm text
    </pivot-text>

    Allowed values for pivot-tag: p, span, h1, h2, h3, h4, h5, h6. Any other value falls back to <p> — this validation happens on every render, against a fixed allowlist checked in render(), so an invalid attribute value never reaches the DOM as an arbitrary tag.

    pivot-tag controls semantics only — it does not affect visual styling, which is driven entirely by pivot-size and pivot-weight. Choose the tag that best reflects the content’s role in the document outline; see Accessibility below for how this choice affects screen reader navigation.


    Usage Guidance

    Do

    • Use pivot-text for all body copy to ensure consistent typography tokens are applied.
    • Use pivot-tag to match the semantic HTML element to the content’s role — for example, pivot-tag="h2" for a section heading that happens to use body text sizing.
    • Use pivot-on-dark whenever text appears on a dark or colored background.
    • Use pivot-inline on child pivot-link elements to embed links naturally within body text.

    Don’t

    • Don’t use pivot-text for headings or display text — use the appropriate heading component instead.
    • Don’t set font size or color directly on pivot-text using inline styles or utility classes; use pivot-size and pivot-on-dark instead to stay consistent with design tokens.
    • Don’t nest block-level tags inside a <span> pivot-tag. For example, avoid pivot-tag="span" wrapping <p> content.

    Accessibility

    pivot-text has no inherent ARIA role of its own — it renders no wrapper element and no part; its accessible semantics come entirely from whichever tag pivot-tag selects (p, span, or h1–h6). Choosing pivot-tag correctly is the primary accessibility concern for this component (WCAG 2.2 — 1.3.1 Info and Relationships).

    Use case Recommended pivot-tag
    Standard body paragraph p (default)
    Inline text fragment span
    Heading in document outline h1–h6 matching the correct level

    Screen Reader Behavior

    Screen readers use the heading level hierarchy (h1 → h2 → h3…) to build a page outline and to let users jump between headings. When pivot-tag is set to a heading level, pivot-text is announced and navigable as a heading at that level (WCAG 2.2 — 2.4.6 Headings and Labels); when it’s p or span, it’s read as plain flow content with no heading semantics and no outline entry. Setting pivot-tag to a heading purely for its visual size — or skipping levels (e.g. h2 directly to h4) — degrades navigation for screen reader users, since the rendered tag is the only source of that structure; pivot-text does not add any ARIA role to compensate for a mismatched tag choice.

    Keyboard Navigation

    pivot-text defines no keyboard handlers. p, span, and heading elements are not natively interactive, so pivot-text itself never appears in the tab order regardless of the chosen pivot-tag. Interactive elements slotted inside (such as pivot-link) manage their own keyboard behavior — see its README for details.

    Focus Management

    pivot-text is never focusable and sets no tabindex — this holds for every pivot-tag value, including headings, which are not focusable by default in HTML. It does not call .focus()/.blur() and does not trap or manage focus. Interactive elements inside the slot (such as pivot-link) manage their own focus.

    Color Contrast

    When using pivot-on-dark, verify that the background color in use meets the WCAG 2.2 minimum contrast ratio of 4.5:1 for normal text and 3:1 for large text (AA) — pivot-text switches to the on-dark token set but cannot guarantee contrast against a background color/image it doesn’t control.


    Related Components

    • Link — pivot-link is the component the pivot-on-dark link-color propagation described above is designed for. Slot a pivot-link inside a pivot-text (with pivot-inline on the link) to embed a link naturally in body copy; when the parent pivot-text has pivot-on-dark set, the link’s colors switch to the on-dark set automatically without setting pivot-on-dark on the link itself.

    References


    API Reference

    Props

    Name Type Default Description
    pivot-size string "body-md" This will create an attribute: pivot-size="value"
    pivot-weight string "regular" This will create an attribute: pivot-weight="value"
    pivot-tag string "p" 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 text content to display.

    CSS Custom Properties

    Name Description
    --global-color-text-on-dark-light Text color applied to slotted content when `pivot-on-dark` is set.
    --global-color-text-on-dark-link-color Link color propagated to slotted `pivot-link` elements when `pivot-on-dark` is set.
    --global-color-text-on-dark-link-hover-color Hover link color propagated to slotted `pivot-link` elements when `pivot-on-dark` is set.
    --global-color-text-on-dark-link-visited-color Visited link color propagated to slotted `pivot-link` elements when `pivot-on-dark` is set.