Typography
Coherent and consistent use of type
Typography defines tone and ensures information is clear, legible, and consistent. Together with our spacing guidelines, it creates a balanced, accessible, and reliable user experience.
Use
The components already have the typography system applied.
For example if you use the title components like TitleGroup, DashboardTitle and PageTitle they handle setting the type on a title group for you.
<script>
import { TitleGroup } from '@ldn-viz/ui';
</script>
<TitleGroup
eyebrow="Air quality"
title="Nitrogen dioxide"
subtitle="Rolling 24-hour mean"
headingLevel={3}
/>Air quality
Nitrogen dioxide
Rolling 24-hour mean
Where you can't use a component and in your own markup you need to set your own type. The rest of this page explains how.
note: Some of the examples below use Tailwind utilities for color and padding. You don't need Tailwind to use the system.
Choose a typeset
Set the right typeset for the page or component you are building. There are two typesets: longform for reading, and product for interfaces, tables, charts and maps.
The typeset dictates the size and spacing behaviour of its children.
Set by adding a class to a containing element. Where typesets are nested the inner one applies.
<article class="typeset-longform">
<p class="body-md">Set by the longform typeset</p>
<div class="typeset-product">
<p class="body-md">Set by the product typeset</p>
</div>
</article>Read more detail about how typesets work
Give text a role
The system describes type by role. A role names the job a piece of text does; an article headline, an input label, the title of a chart, and dictates every property that job requires: font family, size, weight, line height and letter spacing.
Each role's job, sizes and weight are listed under Roles.
Roles are applied by giving the element a class that corresponds to the role.
<h3 class="title-lg">The large title role</h3>The closest typeset context then applies values to the roles properties: font family, size, weight, line height and letter spacing.
<article class="typeset-longform">
<p class="body-md">The medium body title role. Properties set by the longform typeset</p>
</article>
<article class="typeset-product">
<p class="body-md">The medium body title role. Properties set by the product typeset</p>
</article>The medium body title role. Properties set by the longform typeset
The medium body title role. Properties set by the product typeset
The product typeset applies a tighter line height on this role
Formatted content
In some situations like rendering Markdown or content from a CMS, it might not be possible to add classes to every element on the page. Inside typeset-longform and typeset-product--formatted plain html is styled without the need for direct role classes. A class on the element replaces its default style.
<div class="typeset-product--formatted">
<h3>About this data</h3>
<p>Counts are provisional until the annual release.</p>
<ul>
<li>Source: GLA City Intelligence</li>
<li>Updated quarterly</li>
</ul>
<p class="body-sm">Style over-ride</p>
</div>About this data
Counts are provisional until the annual release.
- Source: GLA City Intelligence
- Updated quarterly
Style over-ride
See the reference for the styling that is applied per element.
Content width
In a formatted typeset, running text is limited to 38 times the body size, which is 608px at a 16px body size. Figures, images, videos, tables, code blocks and charts can be up to 56 times the body size (896px). To set a block's width directly, use width-content, width-content-wide or width-content-full.
Escaping the style
To turn the styling off, for example around an embedded component that has its own styles, add not-typeset to a block or to a single element. The styling also stops at a typeset nested inside.
<div class="typeset-longform">
<h3>Title</h3>
<div class="not-typeset">
<h3>I have escaped</h3>
</div>
<h3 class="not-typeset">So have I</h3>
</div>Title
I have escaped
So have I
Usage aliases
The system provides a set of pre-defined usage alias classes. These are classes that are named for where they are applied.
Aliases are named {place}-{part}, for example .card-title, .chart-tick and .dashboard-section-title.
<h3 class="chart-title">A chart title</h3>
<p class="chart-subtitle">and its subtitle</p>A chart title
and its subtitle
These are a convenience. Each alias applies a role, and some also add the muted text colour or tabular numerals. Use a role class where you can, because the roles are the system's stable API.
Check the reference section for the full set of classes.
Title groups
A title group is the text at the top of a card, chart, table or panel. It has up to three parts, in this order: an optional eyebrow, a title and an optional subtitle. Write the parts as sibling elements, each with its role:
<section class="typeset-product flow-standard">
<p class="eyebrow">Air quality</p>
<h2 class="title-md">Nitrogen dioxide</h2>
<p class="subtitle-sm">Rolling 24-hour mean</p>
</section>Air quality
Nitrogen dioxide
Rolling 24-hour mean
Card, ChartContainer and TitleGroup components set this with their emphasis prop. Surfaces and chrome has more examples.
Colour and emphasis
Set text colour with a semantic token:
<p class="body-md text-color-text">Primary text</p>
<p class="body-sm text-color-text-muted">Secondary text</p>
<span class="label-md text-color-label">Control label</span>Primary text
Secondary text
Control labelThe text tokens are --color-text and --color-text-muted, from most to least emphasis. The label tokens are --color-label and --color-label-muted. Text or an icon on a filled control uses an inverse token, such as --color-inverse-text, so that it contrasts with the fill in light and dark mode.
Subhead, subtitle, eyebrow and the lead paragraph are muted by the system.
See the foundation section on colour for more.
To emphasise text within a role, add text-strong, which sets semibold. text-soft sets regular.
<p class="body-md">Readings are <span class="text-strong">provisional</span>.</p>Readings are provisional.
Things to avoid
- Tailwind type utilities such as
text-xl,font-boldandleading-tight. The preset removes them. Use a role, ortext-strongandtext-softfor weight. - Setting a size per breakpoint. Each role already has a value for every breakpoint.
- Adding a weight to a role to change its look. Use
text-strongortext-soft. - Mixing typesets in one region. Give reading content in an application its own
typeset-product--formattedortypeset-longformcontainer. - Using the type scale directly, including inside a component. Use a role.
How it works
Typeface
We use the sans serif font Inter. Inter is a variable font family designed for computer screens, available via Google Fonts under the Open Font License. By using webfonts in our applications we can be reasonably certain that Inter will be used under normal circumstances. All weights are included, so there is no risk of a browser synthesising a bold or a semibold from a lighter face, which produces a coarser letterform than the designed one.
If Inter fails to load, text falls back through this stack:
ui-sans-serif,system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue",
Arial, "Noto Sans", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto
Color Emoji"Type scale
Every size comes from a scale of 17 steps. Step 0 is 16px, the body size.
| Step | Size | Sample |
|---|---|---|
| 14 | 72px | Ag |
| 13 | 64px | Ag |
| 12 | 56px | Ag |
| 11 | 48px | Ag |
| 10 | 40px | Ag |
| 9 | 36px | Ag |
| 8 | 32px | Ag |
| 7 | 30px | Ag |
| 6 | 28px | Ag |
| 5 | 26px | Ag |
| 4 | 24px | Ag |
| 3 | 22px | Ag |
| 2 | 20px | Ag |
| 1 | 18px | Ag |
| 0 | 16px | Ag |
| -1 | 14px | Ag |
| -2 | 12px | Ag |
Designs and code use the roles, which take their sizes from the scale.
Generative logic
The scale is built from five base sizes: 12, 14, 16, 18, (doubled twice) and 20 (doubled once)
Doubling chains:
- 12 → 24 → 48
- 14 → 28 → 56
- 16 → 32 → 64
- 18 → 36 → 72
- 20 → 40 (→ 80 if extended)
22, 26 and 30 belong to no chain. They are hand-placed values, included in the lower half of the scale as intermediate sizes for responsive type. Below 32px, each step is about 1.07 to 1.17 times the one before (12, 14, 16, 18, 20, 22, 24, 26, 28, 30, 32). The close steps give fine control at interface sizes, where a small difference in size is easier to see than it is at display sizes.
Extending the scale:
- Above step 14 (72px): extend the doubling chain — 40 → 80, 48 → 96, 56 → 112 etc.
- Below step -2 (12px): continue the dense-region ratio, giving the next step ≈ 11px.
Typesets
The system has two typesets: longform for reading, and product for interfaces, tables, charts and maps. Both use the same roles. A typeset gives a role its font, weight, line height, letter-spacing or size. Longform is airier, which suits long passages of text, and product is tighter, which suits dashboards.
| Class | For | Flow context | Content styles and widths |
|---|---|---|---|
typeset-longform | Articles, reports and documentation | flow-spacious | Yes |
typeset-product | Interfaces, tables, charts and maps | None | No |
typeset-product--formatted | Content from a CMS or Markdown in a product setting | flow-standard | Yes |
typeset-longform and typeset-product--formatted set the vertical spacing through flow. typeset-product sets type only, and can be combined with a flow class as required.
The typeset is chosen once, on a wrapper or app root:
<div class="typeset-longform"></div>where contexts are nested the inner context takes precedence:
<article class="typeset-longform">
<p class="body-md">I am set by the longform typeset</p>
<div class="typeset-product">
<p class="body-md">I am set by the product typeset</p>
</div>
</article>Product is the default typeset. Its role values are also set on :root, so a role class outside any typeset still works.
Roles
A role names the job a piece of text does, such as the label on an input or the title of a card. If card titles need to be a step larger, the change is made to the role and every card title changes with it.
There are ten roles:
Example
Usage
Each role comes in three sizes, sm, md and lg, except eyebrow, which has one. No title is smaller than 18px, so a heading in a small container, such as a popover or a sidebar section, can use label-lg.
Labels and eyebrows are medium (500), titles are semibold (600), and display, headlines and metrics are bold (700). Other roles are regular (400). Metrics use tabular numerals.
Font weight
The system has five font weights.
| Weight | Numeral |
|---|---|
| Light | 300 |
| Regular | 400 |
| Medium | 500 |
| Semibold | 600 |
| Bold | 700 |
Identity weight vs emphasis weight
- Identity weight is attached to role within a typeset
- Emphasis weight is a separate modifier that can be applied as an over-ride to give emphasis.
Per-role identity weights
Both typesets give each role the same weight.
| Role | Weight |
|---|---|
| Display | Bold (700) |
| Headline | Bold (700) |
| Subhead | Regular (400) |
| Title | Semibold (600) |
| Subtitle | Regular (400) |
| Body | Regular (400) |
| Label | Medium (500) |
| Metric | Bold (700) |
| Caption | Regular (400) |
| Eyebrow | Medium (500) |
Line height
Line height is defined in three steps based on a simple formula: font-size + k, where font-size and k are measured in px.
| tight | default | loose |
|---|---|---|
| font-size + 4px | font-size + 8px | font-size + 12px |
Line height comes from the role. There are no line-height utilities.
Responsive sizing
Some roles grow as the screen widens. The breakpoints are sm (640px), md (768px), lg (1024px) and xl (1280px). Type at wider screens stays at the xl size.
These roles change size, in pixels:
| Role | Typeset | base | sm | md | lg | xl |
|---|---|---|---|---|---|---|
display-lg | Both | 40 | 48 | 56 | 64 | 72 |
display-md | Both | 36 | 40 | 48 | 56 | 64 |
display-sm | Both | 32 | 36 | 40 | 48 | 56 |
headline-lg | Longform | 30 | 32 | 36 | 40 | 40 |
headline-lg | Product | 30 | 32 | 36 | 36 | 40 |
headline-md | Longform | 28 | 28 | 30 | 32 | 32 |
headline-md | Product | 28 | 28 | 30 | 30 | 30 |
headline-sm | Longform | 26 | 26 | 28 | 30 | 30 |
subhead-lg | Longform | 24 | 24 | 24 | 26 | 26 |
subhead-md | Longform | 22 | 22 | 22 | 24 | 24 |
title-lg | Longform | 22 | 22 | 22 | 24 | 24 |
body-lg | Longform | 18 | 18 | 20 | 20 | 20 |
metric-lg | Both | 28 | 30 | 32 | 32 | 36 |
Every other role has one size at every breakpoint.
Reference
Choose a typeset and a breakpoint to see the values for each role.
Each value is the token --typography-base-product-{role}-{property}.
| Role | font-size | line-height | font-weight | letter-spacing |
|---|---|---|---|---|
| display-lg | 40px | 48px | 700 | 0px |
| display-md | 36px | 44px | 700 | 0px |
| display-sm | 32px | 40px | 700 | 0px |
| headline-lg | 30px | 38px | 700 | 0px |
| headline-md | 28px | 36px | 700 | 0px |
| headline-sm | 26px | 34px | 700 | 0px |
| subhead-lg | 24px | 32px | 400 | 0px |
| subhead-md | 22px | 30px | 400 | 0px |
| subhead-sm | 20px | 28px | 400 | 0px |
| title-lg | 22px | 30px | 600 | 0px |
| title-md | 20px | 28px | 600 | 0px |
| title-sm | 18px | 26px | 600 | 0px |
| subtitle-lg | 20px | 28px | 400 | 0px |
| subtitle-md | 18px | 26px | 400 | 0px |
| subtitle-sm | 16px | 24px | 400 | 0px |
| body-lg | 18px | 26px | 400 | 0px |
| body-md | 16px | 24px | 400 | 0px |
| body-sm | 14px | 22px | 400 | 0px |
| label-lg | 18px | 26px | 500 | 0px |
| label-md | 14px | 22px | 500 | 0px |
| label-sm | 12px | 20px | 500 | 0px |
| metric-lg | 28px | 32px | 700 | 0px |
| metric-md | 24px | 28px | 700 | 0px |
| metric-sm | 20px | 24px | 700 | 0px |
| eyebrow | 14px | 18px | 500 | 0px |
| caption-sm | 12px | 16px | 400 | 0px |
| caption-md | 14px | 18px | 400 | 0px |
| caption-lg | 16px | 20px | 400 | 0px |
Formatted content
In a typeset-longform or typeset-product--formatted: Headings, the lead paragraph, quotes and captions take these roles:
| Element | Role |
|---|---|
| h1 | headline-lg |
| h2 | headline-sm |
| h3 | title-lg |
| h4 | title-md |
| h5 | title-sm |
| p.lead | body-lg, muted |
| figcaption | caption-sm, muted |
| blockquote | subtitle-md, muted, with a brand-colour rule on the left |
| cite | caption-md, muted, upright |
| Any other text | body-md |
Other elements keep the role of the text around them, with these changes:
| Element | Style |
|---|---|
| a | Link colour, underlined. The underline thickens on hover |
| strong, b | Semibold |
| em, i | Italic |
| mark | Muted caution background |
| abbr | Help cursor, when it has a title |
| small | 0.875 times the surrounding size |
code | 0.875 times the surrounding size, on a muted surface |
| kbd | As code, with a border |
| Disc markers, then circle and square when nested. Markers are muted |
| Numbers, then letters and roman numerals when nested |
| Term semibold, description indented |
pre | Muted surface, scrolls sideways when too wide |
summarydetails | Summary semibold |
table | Full width. Caption muted and above, header cells semibold, figures in tabular numerals, rules between rows |
hr | Wash border colour |
Usage aliases
A usage alias is a class named for the place it is used, such as card-title or chart-tick. Each alias applies a role, and some also add the muted text colour or tabular numerals.
Charts
| Sample | Alias | Role | Adds |
|---|---|---|---|
| Chart title | chart-title | title-md | – |
| Chart subtitle | chart-subtitle | subtitle-sm | Muted colour |
| Axis title | chart-axis-title | label-md | Muted colour |
| Data label | chart-label | label-md | – |
| 2024 | chart-tick | caption-md | Muted colour, tabular numerals |
| 2024 | chart-tick-sm | caption-sm | Muted colour, tabular numerals |
| Source: GLA | chart-note | caption-sm | – |
chart-label is for value labels, annotations and legend entries. chart-tick-sm is for the ticks of a dense chart.
Tables
| Sample | Alias | Role | Adds |
|---|---|---|---|
| Table title | table-title | title-md | – |
| Table subtitle | table-subtitle | subtitle-sm | Muted colour |
| Column header | table-col-head | label-md | Tabular numerals |
| Column header | table-col-head-sm | label-sm | Tabular numerals |
| 1,284 | table-body | body-sm | Tabular numerals |
Interface
| Sample | Alias | Role | Adds |
|---|---|---|---|
| Dashboard title | dashboard-main-title | headline-md | – |
| Dashboard subtitle | dashboard-main-subtitle | subhead-md | Muted colour |
| Section title | dashboard-section-title | headline-sm | – |
| Section subtitle | dashboard-section-subtitle | subhead-sm | Muted colour |
| Header title | header-title | title-md | – |
sidebar-title | title-md | – | |
| Dialog title | dialog-title | label-lg | – |
| Card title | card-title | title-md | – |
| Card subtitle | card-subtitle | subtitle-sm | Muted colour |
| Input label | input-label | label-md | – |
| Placeholder | input-placeholder | body-md | – |
| Field value | input-value | body-md | – |
| Hint text | input-hint | caption-sm | – |
button-label | label-md | – | |
button-label-sm | label-sm | – |
Controls such as buttons, tabs and chips use the label role's line height. Their padding sets their height.
The full rules for type are in the specification.