Typography
The type scale and how to reference it.
Type ships as a scale of semantic steps from @base-org/bds-tokens — each a
font size, line height, and weight bundled under one token. Reference a step by
name rather than composing sizes by hand, and text stays consistent across
every surface. This documentation is set in the same scale.
<p className="text-body">Body copy</p>
<h2 className="text-title-1">A section heading</h2>
<span className="text-label-medium">A field label</span>Choosing a step
| Step | Use for |
|---|---|
display | The single largest moment on a page — a hero or empty-state headline. |
title-1 – title-3 | Section and subsection headings, in descending order. |
headline | A label that needs more weight than body without changing size. |
body | Running text and most UI copy. |
label-medium | Field labels, table headers, and emphasized captions. |
label-regular | Secondary labels and captions. |
footnote | Fine print and dense metadata. |
Usage
Do
Reference a step by token — text-title-1, text-body — so size, line
height, and weight move together and stay in sync with the system.
Don't
Compose type from arbitrary text-[..] sizes and weights. It drifts from
the scale and breaks the vertical rhythm the tokens are tuned for.
Font
The scale is set in Base Sans (Google Sans Flex in the product components). It carries exactly two weights — Light (300) for body copy and Regular (400) for headings and emphasis — so hierarchy reads as a change in size, and occasionally weight, but never a jump to bold.
Guidelines
Defaults for setting text in BDS components and product UI. See the Guidelines overview for how to apply them.
Fonts and rendering
- Use
.woff2web fonts only, never.ttfor.otf. - Set
-webkit-font-smoothing: antialiasedand-moz-osx-font-smoothing: grayscaleon the root layout for sharper text.
Numbers
- Use
font-variant-numeric: tabular-numsin timers, counters, prices, and tables (skip it if the font is already monospace).
Line length and wrapping
- Keep long-form text lines to 60–75 characters wide.
- Use
text-wrap: balanceon headings andtext-wrap: prettyon descriptions; use neither on long-form text. - Use
overflow-wrap: break-wordfor long words, links, and IDs; usewhite-space: nowrapfor labels and badges. - When text is truncated with an ellipsis, make the full text available via a tooltip or an expanded view.
Punctuation and decoration
- Use smart punctuation: curly quotes, en dash (–) for ranges, em dash (—) for asides, ellipsis (…).
- Use
text-underline-position: from-fontandtext-decoration-skip-ink: autoso underlines don't cross descenders. - Store text with normal capitalisation and apply uppercase or lowercase
with
text-transform, never by typing the string in caps.