Typography

Usage

Overview

Typography is a layout-oriented text container that spaces paragraphs and styled lists (ul, ol, li) for readable vertical rhythm. It suits markdown-like content, help articles, and mixed text-plus-list instructions inside the product shell. The mental model is “document fragment,” not “single label.”

When to use

Multiple paragraphs with consistent gaps between them.
Lists (procedures, requirements, feature bullets) that should inherit design-system list styling.
Rendered rich content where structure is headings, paragraphs, and lists—not arbitrary flex layouts.

When not to use

Single line or single paragraph: prefer Text roles.
Application chrome (toolbars, dense tables, form rows): use layout primitives and form field wrappers instead.
Fully custom interactive UI: Typography is for reading flow, not controls.

Variants

`type`	Purpose	Emphasis
Default	Comfortable reading	Body copy, help, onboarding
Data	Tighter vertical rhythm	Dense informational panels
Critical	Focused urgent copy	Keep sections short; still readable

Anatomy

Typography is a vertical stack with token-driven gaps; lists receive indentation, markers, and colors from the system. List indentation is 1em, so it always matches the list's computed font size. Lists have no margin, list items have no inline padding, and --list-item-y-padding is applied only between sibling items. Headings inside the block should respect hierarchy relative to surrounding page headings.

Content guidelines

Headings inside Typography: Ensure they don’t skip levels relative to the page (h1 outside shouldn’t jump to h3 inside without reason).
Lists: Parallel phrasing; short items; avoid more than three nesting levels.
Paragraphs: One idea each; break up walls of text with lists when steps or criteria appear.
i18n: Translation lengthens bullets—test wrapping and marker alignment.

Behavior and states

Typography itself is not interactive; links or buttons inside must be real focusable elements.
Dynamic updates should not reorder content unexpectedly while users read.

Best practices

Choose type based on density of the surrounding page.
Keep list items complete sentences OR consistent fragments—not mixed.
Use ordered lists only when order truly matters.

Don’t

Dump very long policy text without navigation anchors in product surfaces meant for quick tasks.
Use Typography as a substitute for accessible form labels.
Nest lists deeply to simulate outlines—flatten or split into sections.

Accessibility

Lists must be real list elements so screen readers announce counts.
Maintain logical heading order for the combined page + fragment.
Ensure link text is descriptive (“Export guidelines”) not “click here”.
Color tokens for markers and text must meet contrast requirements.

Time / Accessibility

Typography / API and Development

On this page

Typography

Usage

Overview

When to use

Multiple paragraphs with consistent gaps between them.
Lists (procedures, requirements, feature bullets) that should inherit design-system list styling.
Rendered rich content where structure is headings, paragraphs, and lists—not arbitrary flex layouts.

When not to use

Single line or single paragraph: prefer Text roles.
Application chrome (toolbars, dense tables, form rows): use layout primitives and form field wrappers instead.
Fully custom interactive UI: Typography is for reading flow, not controls.

Variants

`type`	Purpose	Emphasis
Default	Comfortable reading	Body copy, help, onboarding
Data	Tighter vertical rhythm	Dense informational panels
Critical	Focused urgent copy	Keep sections short; still readable

Anatomy

Content guidelines

Headings inside Typography: Ensure they don’t skip levels relative to the page (h1 outside shouldn’t jump to h3 inside without reason).
Lists: Parallel phrasing; short items; avoid more than three nesting levels.
Paragraphs: One idea each; break up walls of text with lists when steps or criteria appear.
i18n: Translation lengthens bullets—test wrapping and marker alignment.

Behavior and states

Typography itself is not interactive; links or buttons inside must be real focusable elements.
Dynamic updates should not reorder content unexpectedly while users read.

Best practices

Choose type based on density of the surrounding page.
Keep list items complete sentences OR consistent fragments—not mixed.
Use ordered lists only when order truly matters.

Don’t

Dump very long policy text without navigation anchors in product surfaces meant for quick tasks.
Use Typography as a substitute for accessible form labels.
Nest lists deeply to simulate outlines—flatten or split into sections.

Accessibility

Lists must be real list elements so screen readers announce counts.
Maintain logical heading order for the combined page + fragment.
Ensure link text is descriptive (“Export guidelines”) not “click here”.
Color tokens for markers and text must meet contrast requirements.

Time / Accessibility

Typography / API and Development

On this page