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
One large figure, 32px
A queue count or metric value, passed as value; never a heading. Nothing in the scale is larger than 32px
Page / Section / Subsection / Title
Heading hierarchy, 24px down to 16px
One Page per view or major region; don’t skip levels
Subtitle / SubtitleEmphasis
Body copy, 14px (the default role)
SubtitleEmphasis for emphasis inside body copy
Body / Caption
Dense body copy and secondary metadata
Caption for secondary metadata, not for primary instructions alone
Label
Compact UI and action-aligned copy
Label for field labels
Overline
Eyebrows or badges
Use sparingly; test readability
Caption
Supporting one-line text
Secondary context without competing with body
Code1 / Code2
Monospace literals
IDs, code, tokens; pick scale by density
Semantic colors
Status and tone
Pair with icons or text for color-blind users
Anatomy
Text renders semantic elements (h1–h4 for display heading types, p or span for body and other types) with token-driven styling. Alignment, truncation, no-wrap, and transformation props adjust layout but should not fight the content’s natural reading pattern.
Odometer
Pass value to Text from @prepared911/ui/text. type selects the text style. Digits roll to each new value. from is the number shown on first paint. roll={false} renders the formatted number as plain text. announcement is localized copy spoken after the roll settles, not on first paint.
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
Do
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 set the heading role on a span.
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.