Overview

What typography is

Typography plays an important role in guiding users through content. By using a range of text styles (fonts, sizes, colors, treatments, and spacing) typography not only differentiates design elements but also creates a visual hierarchy that enhances the clarity and readability of information, allowing users to focus on the content itself rather than its presentation.

Typography establishes how text looks and reads across Blue Yonder products: which typefaces to load, which scale to use for body copy and headings, and how density adjusts font size without breaking hierarchy.

Tokens and utilities live in packages/experience-system/src/theme/theme.css and resolve under ThemeProvider.

What typography is not

Typography is not decoration or free‑form styling. It should not be used to:

• Add emphasis without meaning
• Fix layout or hierarchy problems
• Communicate semantic states (error, success, warning)
• Create new text styles or manual overrides

Typography is also not interchangeable with other foundations:

• Use color for state and contrast
• Use elevation for spatial priority
• Use layout for structure

Typeface

The primary font family used is"Calibre" it provides visual distinction and recognition to Blue Yonder user interfaces. It is iused for almost all UI elements, except code-related use cases, where monospace plays the key role.

Load web fonts before Tailwind and theme.css in your global stylesheet. See Installation for the recommended @import order (Calibre CDN + Google Fonts for Roboto Mono).

Body text uses antialiased rendering on body (-webkit-font-smoothing / -moz-osx-font-smoothing) and default color var(--color-neutral-12).

Type scale

Typography hierarchy in Experience System is defined using a linear token‑based scale. The scale is compatible with Tailwind utility classes and uses the same size step names.

Font sizes are CSS variables in the dynamic @theme inline block. Each step pairs --text-* with --text-*--line-height (and aliases such as --line-height-3xl for headings). Sizes multiply by --scale-typography so ultra-compact density can shrink copy without changing class names.

* Sizes are given as a reference for the standard density, as token values are subject to change according to defined density mode.

The text-xs, text-sm, and text-base have minimum size defined as 11px so ultra-compact scaling never drops below a readable floor.

The scale of tokens is detached from the scale of HTML <H*> tags to allow control visual and structural hierarchy separately. Default values for HTM header tags are defined in the @base layer CSS definitions.

Preview

Access raw values in CSS when needed:

.custom-label {
  font-size: var(--text-sm);
  line-height: var(--text-sm--line-height);
}

Font weights

Static weights are registered in @theme and exposed as Tailwind utilities:

The scale also includes thin through black (100–900) for specialized layouts. Experience System components most often use normal, medium, and semibold—for example strong / b inside ThemeProvider use 600, and many labels use font-medium when emphasized.

Line height and letter spacing

Line height tokens:

Paired --text-*--line-height variables keep each font size on a designed rhythm. --scale-line-height scales those pairs in ultra-compact mode (0.875×).

Letter spacing utilities: tracking-tighter, tracking-tight, tracking-normal, tracking-wide, tracking-wider, tracking-widest (defined as em offsets in theme.css). Semantic headings apply slight negative tracking for optical balance.

Semantic HTML inside ThemeProvider

When content renders inside ThemeProvider, base styles in theme.css style native elements under [data-ds-theme] without extra classes:

Tailwind utility classes in @layer utilities (for example text-sm, text-lg) override these base rules when you need a different size on a specific element—utilities always win over @layer base.

Use real heading levels (h1–h6) in document order for accessibility; do not skip levels for visual effect—adjust appearance with utilities if the outline requires it.

Important!
Do not rely on default h1-h6 size values — apply font size tokens according to the hierarchy role. For example: the regular application page title is using <h1> to provide clear hierarchy structure, but it should apply text-3xl token: <h1 className="text-3xl"> to match visual hierarchy of the page.

Density and typography

ThemeProvider spacing drives typography scaling via data-ds-spacing (see Spacing):

Prefer density for data-heavy screens; do not treat it as a separate “small font” accessibility setting. Keep identifiers, errors, and primary values at text-base or larger when possible—see spacing guidance on what should not be scaled.

Component typography

Primitives encode common tiers so features stay consistent:

• text-base — default for Button (md), Input, Label (md), Link (variant="base"), navigation items, and much field copy.
• text-sm — compact controls, Select labels, Badge, Kbd (sm).
• text-lg — Dialog titles and similar emphasis.

When a control should match surrounding copy, use Link with variant="inherit" or explicit text-* utilities rather than hard-coded pixel sizes.

Text box trim

Form controls that need tighter vertical metrics can use the tb-trim utility from text-box-utilities.css (text-box-trim / text-box-edge). It is progressive enhancement—unsupported browsers ignore it. Pair with the component’s chosen text-* and leading-* classes.

Best practices

• Hierarchy — Prefer fewer hierarchy levels per screen. Use the type scale consistently: one clear h1 per view, stepped headings below it, text-base for body and forms.
• Readability — Use text-base as the default text size unless there is a clear reason not to.
• Contrast — Pair type with semantic colors (text-neutral-12 on surfaces, text-neutral-11 for secondary). See Core colors and Accessibility.
• Avoid decorative all-caps in UI labels when possible; prefer sentence case for readability (see accessibility UX writing notes).
• Monospace — Reserve font-mono for code, shortcuts (Kbd), and data that benefits from fixed width—not general UI labels.
• Do not embed font files inside feature bundles; rely on the shared Calibre / Roboto Mono imports documented in Installation.

Accessibility

• Ensure sufficient color contrast for all text.
• Avoid large blocks of text set smaller than base.
• Do not rely on weight or color alone to convey meaning.
• Preserve consistent hierarchy to support screen readers and navigation.

Related

• Installation — Font imports and Tailwind setup
• Theming — ThemeProvider and token layers
• Spacing — Density modes and scaled layout
• Accessibility — Contrast, labels, and readable copy