Prepared Docs

Overview

Text components (including heading and body roles in the design system) apply consistent type scale, color, weight, and semantics to strings. They are the default way to render readable content instead of ad hoc styles. The mental model is “meaning plus appearance”—pick the role that matches the job, not only the pixel size.

When to use

Headings, body copy, captions, labels-as-text, and inline emphasis inside interfaces.
Any user-visible string that should track design tokens for color and size.
Internationalized content that may swap in rich fragments via formatMessageProps.

When not to use

Single-token labels bound to form controls: prefer the Label component for explicit association.
Long rich documents: Typography may structure lists and paragraphs better.
Clickable actions: use Button or Interactable rather than styled text alone; use the product navigation pattern for links.

Variants

Role / type	Purpose	Emphasis
Display / Heading / Subheading / Title	Section hierarchy	One Display per view or major region; don’t skip levels
NumericDisplay / NumericCompact	Large numbers that must stay a `span`	2.4rem and 1.8rem. MetricCard always uses NumericDisplay
BodyLarge / BodyBase / BodySmall	Body ladder	BodySmall for secondary metadata, not for primary instructions alone
Label / Button	Compact UI and action-aligned copy	Label for field labels; Button for text that matches button typography
Overline	Eyebrows or badges	Use sparingly; test readability
Caption	Supporting one-line text	Secondary context without competing with body
MonoMedium / MonoSmall	Monospace literals	IDs, code, tokens; pick scale by density
Semantic colors	Status and tone	Pair with icons or text for color-blind users

Anatomy

CoreText renders semantic elements (h1–h4 for display heading types, p or span for body and other types) with token-driven styling. NumericDisplay and NumericCompact stay spans at heading sizes so a metric value is never an h*. Alignment, truncation, no-wrap, and transformation props adjust layout but should not fight the content’s natural reading pattern.

Odometer

Opt in with animation={{ type: TextAnimation.Odometer, value, from? }}. Every reel element carries the root’s text type, weight, and color, so font-size, family, line-height, letter-spacing, and glyph width are identical with or without animation. Digit windows derive their geometry from the inherited font metrics. Heading types are excluded from OdometerTextType; use NumericDisplay or NumericCompact for large animated numbers.

Supply from only when the entrance should roll. Omission snaps.
Polite live requires announcement. Default live is off.
Reduced motion, snap, and zero duration skip the wrap row and land on the target.

Content guidelines

Prepared conventions: Buttons and primary actions often use title case; standalone labels frequently use sentence case—match the surface you ship.
Headings: Describe the following content; avoid vague labels (“Details”, “Info”) when a specific noun helps.
Truncation: Visible text may clip; ensure critical meaning survives or expose full string to assistive tech.
i18n: All strings through formatMessage; plan for expansion in German and Romance languages.
Strong / medium weight: Use for emphasis, not entire paragraphs.

Behavior and states

Interactive text should still be a real control with focus styles—don’t fake links with onClick on plain text.
Disabled appearance should reflect unavailable content, not essential instructions hidden only by color.

Best practices

Maintain strict heading order for accessibility and SEO in content pages.
Use semantic colors (Success, Warning, Error) consistently with product meaning.
Test truncation at small breakpoints.

Don’t

Use heading levels for size only—if the semantics aren’t a heading, choose a body type or NumericDisplay / NumericCompact.
Depend on color alone for errors or success.
Stack many font sizes in one card without hierarchy intent.

Accessibility

Map visual level to semantic level (h* vs p).
Meet contrast requirements for text and icon+text pairs.
Truncation should not remove the only mention of critical identifiers from the accessibility tree.
Rich formatMessage fragments must remain keyboard accessible when they include links or buttons.

Separator / Accessibility

Text / API and Development

Overview

When to use

Headings, body copy, captions, labels-as-text, and inline emphasis inside interfaces.
Any user-visible string that should track design tokens for color and size.
Internationalized content that may swap in rich fragments via formatMessageProps.

When not to use

Single-token labels bound to form controls: prefer the Label component for explicit association.
Long rich documents: Typography may structure lists and paragraphs better.
Clickable actions: use Button or Interactable rather than styled text alone; use the product navigation pattern for links.

Variants

Role / type	Purpose	Emphasis
Display / Heading / Subheading / Title	Section hierarchy	One Display per view or major region; don’t skip levels
NumericDisplay / NumericCompact	Large numbers that must stay a `span`	2.4rem and 1.8rem. MetricCard always uses NumericDisplay
BodyLarge / BodyBase / BodySmall	Body ladder	BodySmall for secondary metadata, not for primary instructions alone
Label / Button	Compact UI and action-aligned copy	Label for field labels; Button for text that matches button typography
Overline	Eyebrows or badges	Use sparingly; test readability
Caption	Supporting one-line text	Secondary context without competing with body
MonoMedium / MonoSmall	Monospace literals	IDs, code, tokens; pick scale by density
Semantic colors	Status and tone	Pair with icons or text for color-blind users

Anatomy

Odometer

Supply from only when the entrance should roll. Omission snaps.
Polite live requires announcement. Default live is off.
Reduced motion, snap, and zero duration skip the wrap row and land on the target.

Content guidelines

Prepared conventions: Buttons and primary actions often use title case; standalone labels frequently use sentence case—match the surface you ship.
Headings: Describe the following content; avoid vague labels (“Details”, “Info”) when a specific noun helps.
Truncation: Visible text may clip; ensure critical meaning survives or expose full string to assistive tech.
i18n: All strings through formatMessage; plan for expansion in German and Romance languages.
Strong / medium weight: Use for emphasis, not entire paragraphs.

Behavior and states

Interactive text should still be a real control with focus styles—don’t fake links with onClick on plain text.
Disabled appearance should reflect unavailable content, not essential instructions hidden only by color.

Best practices

Maintain strict heading order for accessibility and SEO in content pages.
Use semantic colors (Success, Warning, Error) consistently with product meaning.
Test truncation at small breakpoints.

Don’t

Use heading levels for size only—if the semantics aren’t a heading, choose a body type or NumericDisplay / NumericCompact.
Depend on color alone for errors or success.
Stack many font sizes in one card without hierarchy intent.

Accessibility

Map visual level to semantic level (h* vs p).
Meet contrast requirements for text and icon+text pairs.
Truncation should not remove the only mention of critical identifiers from the accessibility tree.
Rich formatMessage fragments must remain keyboard accessible when they include links or buttons.

Separator / Accessibility

Text / API and Development