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-textfor all body copy to ensure consistent typography tokens are applied. - Use
pivot-tagto 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-darkwhenever text appears on a dark or colored background. - Use
pivot-inlineon childpivot-linkelements to embed links naturally within body text.
Don’t
- Don’t use
pivot-textfor headings or display text — use the appropriate heading component instead. - Don’t set font size or color directly on
pivot-textusing inline styles or utility classes; usepivot-sizeandpivot-on-darkinstead to stay consistent with design tokens. - Don’t nest block-level tags inside a
<span>pivot-tag. For example, avoidpivot-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-linkis the component thepivot-on-darklink-color propagation described above is designed for. Slot apivot-linkinside apivot-text(withpivot-inlineon the link) to embed a link naturally in body copy; when the parentpivot-texthaspivot-on-darkset, the link’s colors switch to the on-dark set automatically without settingpivot-on-darkon the link itself.
References
- MDN — The Paragraph element
<p> - 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
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. |
body-xl — light surface, all weights
<pivot-text pivot-size="body-xl" pivot-weight="regular"
>body-xl regular — The quick brown fox jumps over the lazy dog.</pivot-text
>
<pivot-text pivot-size="body-xl" pivot-weight="medium"
>body-xl medium — The quick brown fox jumps over the lazy dog.</pivot-text
>
<pivot-text pivot-size="body-xl" pivot-weight="semibold"
>body-xl semibold — The quick brown fox jumps over the lazy dog.</pivot-text
>
<pivot-text pivot-size="body-xl" pivot-weight="bold"
>body-xl bold — The quick brown fox jumps over the lazy dog.</pivot-text
>body-lg — light surface, all weights
<pivot-text pivot-size="body-lg" pivot-weight="regular"
>body-lg regular — The quick brown fox jumps over the lazy dog.</pivot-text
>
<pivot-text pivot-size="body-lg" pivot-weight="medium"
>body-lg medium — The quick brown fox jumps over the lazy dog.</pivot-text
>
<pivot-text pivot-size="body-lg" pivot-weight="semibold"
>body-lg semibold — The quick brown fox jumps over the lazy dog.</pivot-text
>
<pivot-text pivot-size="body-lg" pivot-weight="bold"
>body-lg bold — The quick brown fox jumps over the lazy dog.</pivot-text
>body-md — light surface, all weights (default size)
<pivot-text pivot-size="body-md" pivot-weight="regular"
>body-md regular — The quick brown fox jumps over the lazy dog.</pivot-text
>
<pivot-text pivot-size="body-md" pivot-weight="medium"
>body-md medium — The quick brown fox jumps over the lazy dog.</pivot-text
>
<pivot-text pivot-size="body-md" pivot-weight="semibold"
>body-md semibold — The quick brown fox jumps over the lazy dog.</pivot-text
>
<pivot-text pivot-size="body-md" pivot-weight="bold"
>body-md bold — The quick brown fox jumps over the lazy dog.</pivot-text
>body-sm — light surface, all weights
<pivot-text pivot-size="body-sm" pivot-weight="regular"
>body-sm regular — The quick brown fox jumps over the lazy dog.</pivot-text
>
<pivot-text pivot-size="body-sm" pivot-weight="medium"
>body-sm medium — The quick brown fox jumps over the lazy dog.</pivot-text
>
<pivot-text pivot-size="body-sm" pivot-weight="semibold"
>body-sm semibold — The quick brown fox jumps over the lazy dog.</pivot-text
>
<pivot-text pivot-size="body-sm" pivot-weight="bold"
>body-sm bold — The quick brown fox jumps over the lazy dog.</pivot-text
>body-xl — dark surface, all weights
<pivot-text pivot-size="body-xl" pivot-weight="regular" pivot-on-dark
>body-xl regular — The quick brown fox jumps over the lazy dog.</pivot-text
>
<pivot-text pivot-size="body-xl" pivot-weight="medium" pivot-on-dark
>body-xl medium — The quick brown fox jumps over the lazy dog.</pivot-text
>
<pivot-text pivot-size="body-xl" pivot-weight="semibold" pivot-on-dark
>body-xl semibold — The quick brown fox jumps over the lazy dog.</pivot-text
>
<pivot-text pivot-size="body-xl" pivot-weight="bold" pivot-on-dark
>body-xl bold — The quick brown fox jumps over the lazy dog.</pivot-text
>body-lg — dark surface, all weights
<pivot-text pivot-size="body-lg" pivot-weight="regular" pivot-on-dark
>body-lg regular — The quick brown fox jumps over the lazy dog.</pivot-text
>
<pivot-text pivot-size="body-lg" pivot-weight="medium" pivot-on-dark
>body-lg medium — The quick brown fox jumps over the lazy dog.</pivot-text
>
<pivot-text pivot-size="body-lg" pivot-weight="semibold" pivot-on-dark
>body-lg semibold — The quick brown fox jumps over the lazy dog.</pivot-text
>
<pivot-text pivot-size="body-lg" pivot-weight="bold" pivot-on-dark
>body-lg bold — The quick brown fox jumps over the lazy dog.</pivot-text
>body-md — dark surface, all weights
<pivot-text pivot-size="body-md" pivot-weight="regular" pivot-on-dark
>body-md regular — The quick brown fox jumps over the lazy dog.</pivot-text
>
<pivot-text pivot-size="body-md" pivot-weight="medium" pivot-on-dark
>body-md medium — The quick brown fox jumps over the lazy dog.</pivot-text
>
<pivot-text pivot-size="body-md" pivot-weight="semibold" pivot-on-dark
>body-md semibold — The quick brown fox jumps over the lazy dog.</pivot-text
>
<pivot-text pivot-size="body-md" pivot-weight="bold" pivot-on-dark
>body-md bold — The quick brown fox jumps over the lazy dog.</pivot-text
>body-sm — dark surface, all weights
<pivot-text pivot-size="body-sm" pivot-weight="regular" pivot-on-dark
>body-sm regular — The quick brown fox jumps over the lazy dog.</pivot-text
>
<pivot-text pivot-size="body-sm" pivot-weight="medium" pivot-on-dark
>body-sm medium — The quick brown fox jumps over the lazy dog.</pivot-text
>
<pivot-text pivot-size="body-sm" pivot-weight="semibold" pivot-on-dark
>body-sm semibold — The quick brown fox jumps over the lazy dog.</pivot-text
>
<pivot-text pivot-size="body-sm" pivot-weight="bold" pivot-on-dark
>body-sm bold — The quick brown fox jumps over the lazy dog.</pivot-text
>Dark surface — link color inheritance
A slotted pivot-link automatically switches to the on-dark link colors when its ancestor pivot-text has pivot-on-dark set — no pivot-on-dark needed on the link itself.
<!-- pivot-on-dark on pivot-text propagates dark link colors via --__link-color* -->
<pivot-text pivot-on-dark>
This is body text on a dark surface with a
<pivot-link pivot-href="#" pivot-inline>slotted pivot-link</pivot-link>
— the link's colors switch to the on-dark set automatically, with no
pivot-on-dark needed on the link itself.
</pivot-text>Semantic tag (pivot-tag)
<!-- Use pivot-tag to match document semantics without changing visual styling -->
<pivot-text pivot-tag="h2" pivot-size="body-md"
>pivot-tag="h2" — heading semantics with body-md styling</pivot-text
>
<pivot-text pivot-tag="h3" pivot-size="body-sm"
>pivot-tag="h3" — heading semantics with body-sm styling</pivot-text
>
<pivot-text pivot-tag="p" pivot-size="body-md"
>pivot-tag="p" — default paragraph (explicit)</pivot-text
>
<pivot-text pivot-tag="span" pivot-size="body-sm"
>pivot-tag="span" — inline span with body-sm styling</pivot-text
>