Skip to content

Text

P-02 · Primitives · Primitives

All elements · Text on the Primitives page

Last checked 2026-10-22 · Awaiting approval · Accessibility tests

Copies the bun run a11y:approve command for Text.

Text

P-02WCAG 2.2 AA · Passed #429

All typography, headings included. No attributes gives sm / regular / ink. Layout-only styling (overflow, whitespace) is the only thing that goes in style.

Axis Values
data-size xs · sm · md · lg · xl · h1 · h2 · h3 · h4 · h5 · h6 · overline
data-weight light · regular · medium · semibold · bold · heavy
data-tone secondary · muted · disabled · link · inverse
data-color primary · info · success · warning · error · purple · electric-blue · pink · yellow · brown
data-align · data-truncate · data-mono center · end / (1) · 2 · 3 lines / monospace
Tones and colors

Default: 14px, weight 500, ink.

Secondary tone for supporting copy.

Muted tone for metadata and captions.

Disabled tone.

Link tone.

Success color, medium weight.

Error color, medium weight.

Purple accent.

Truncated: this sentence is far too long for the width of its container and will be clipped with an ellipsis.

Two-line clamp: this sentence is far too long for the width of its container and will be clipped after the second line, with an ellipsis at the end of the second line.

monospace · 4f3c-91ab-…

Guidance

When to use

  • Set any run of text in the app, from page headings to table metadata.
  • Show supporting copy, captions or timestamps with data-tone="secondary" or "muted".
  • Clip a long record title to one, two or three lines with data-truncate.
  • Show identifiers, codes and amounts in monospace with data-mono.

When to consider something else

  • When the text is an action, use a Button; when it navigates, use a real <a> with the link tone. See Button.
  • When a short status or category label sits beside content, use Chip. See Chip.
  • When the message is a page-level status, warning or error, use Banner instead of colored text. See Banner.
  • When the text is a form label or helper message, use Field, which wires it to the control. See Field.

Usability

Do
  • Apply qf-text to the element that carries the meaning: h1 to h6 for headings, p for paragraphs, span inline.
  • Keep heading sizes in order with the heading levels; data-size changes only the look.
  • Give truncated text a way to read the full value, such as a title, a Tooltip or a detail view.
  • Use data-align="end" with data-mono for numeric columns so digits line up.
Don’t
  • Don't use data-color alone to say success, warning or error; add an icon or words.
  • Don't use the disabled tone for text that is only less important; use secondary or muted.
  • Don't put anything but layout styling (overflow, whitespace) in style.

Accessibility

Keyboard

No keyboard interaction of its own.

Roles and names

  • Text adds no role. Headings must be real h1 to h6 elements (or role="heading" with aria-level), not a p with data-size="h2".
  • The link tone only styles text. A link must be an <a href>; a span with the link tone is not a link.
  • Truncated text stays whole in the DOM, so screen readers read the full string.

Focus

  • Text is not focusable. When it is inside a focusable element, that element owns the focus ring.

Other requirements

  • Text is a visual primitive with no keyboard behavior of its own.
  • Body text needs 4.5:1 contrast and large text 3:1 (1.4.3). Check secondary, muted and accent colors on the surface they sit on, in both themes; the default is weight 500; nothing lighter is loaded.
  • Color alone must not carry meaning (1.4.1); a link tone in running text needs a non-color cue such as an underline.
  • Truncation must not hide information users need with no other way to get it; text must also survive 200% zoom and text spacing overrides (1.4.4, 1.4.12).

Test your implementation too. This guidance covers the element as specified here. How a screen composes it (labels, order, announcements) still needs its own keyboard and screen reader check.

Accessibility tests

WCAG 2.2 AA · Passed

Passed the gate (run 358b316 on 2026-10-22): no finding in any theme. Awaiting a person’s approval of the checklist below.

Text test checklist
Area Automated A person checks
General Passed Color is never the only cue, text alternatives say the same thing as the graphic, and the element reads the same in the light and the dark theme.
Zoom Passed At 200% zoom, at 320 CSS pixels wide and with the WCAG text-spacing overrides, nothing is lost, clipped or overlapping.
Keyboard Passed Every row of the Keyboard table works, focus is always visible and never trapped, and the tab order follows the reading order.
Screen reader Passed With NVDA or JAWS on Windows and VoiceOver on macOS, names, roles and states are announced as Roles and names says, and changes are announced once. (3 items)

Approving. When the checklist passes on the checked run, record it with bun run a11y:approve -- text --by "Your name" and commit a11y/approvals.json with the rebuilt pages. All test status

Package

Consumers link one stylesheet, css/classic/index.css, which includes every element. The files below are where this element is defined.

Text package
Source css/classic/primitives/layout.css
Specimens also use Box · Card · Chip · Icon · Table · Toolbar
Sprites sprites/icons.svg
React Not yet available: the React binding has not started.

Latest updates

No recorded changes yet.

All release notes