Type scale

Overview

Almost every design system sizes type with a t-shirt scale: xs, sm, base, lg, xl, and upwards. It is easy to learn and it has one fatal property for a health product. The scale names the size, so a component that wants "the size a footnote should be" has to hard-code the answer.

The moment the reader changes their text size, that hard-coded answer is the one thing that cannot follow, because it was written as a number in a component rather than resolved from a role. A scale addressed by size also hides the decision a component is making. It asked for text-xs when what it meant was a footnote, and text-xs is a number, so nobody can retune what a footnote should be without hunting down every place that number was pasted.

opsinjs therefore uses a semantic scale, in the manner of Apple's Dynamic Type text styles: roles named for the job they do. A component asks for footnote and the system decides what a footnote is at the current text size, on this device, in this container. The mapping can change; the intent cannot.

How it works

There is one family of roles, named for the job each does rather than for its size, and the table below is the whole of it. There is no separate family for numerals; a measurement is a reading role too, and how it gets tabular figures is the second half of this section.

Reading roles carry words. Every role name below is a real token: prefix it with text-opsin- and it is the utility class that sets the role.

A card's title sits at headline, not title3, and the table says so. The reason is what happens at 200% text: a title3 title reaches 40px, which splits a word across two lines inside a 336px card, while headline at the same multiplier wraps at a space. A modal title is a screen title rather than a card title, so title3 is where a Dialog or a Sheet heading belongs and the only place it does. On a system that is often read one-handed by people over 60, a card should not spend a size step it does not need.

A measurement is a reading role, not a separate family. There is no value role family and no text-opsin-value-* utility to reach for. A health value is set in a reading role at title2 or larger, and never below body, which is the second rule in tokens/type.json. Its label sits in subheadline, its unit a step down from the number, and its provenance in footnote. So the same eleven roles carry both the words and the numbers.

Tabular figures come from a mechanism, not from the role. Anything carrying the data-opsinjs-value attribute is set in font-variant-numeric: tabular-nums by the product theme, and the numeric family is reached through font-opsin-numeric. A number therefore gets stable, aligned digits because of what it is, an attribute the component anatomy sets, rather than because of which size role it happened to land in. That is the mechanism the system actually ships, and it is why a measurement in title1 and a measurement in title2 both align.

Tabular figures are not a stylistic choice here. Proportional digits have different widths, so 111 and 100 are different lengths; a column of readings does not align, a value that updates shifts the layout under the reader's thumb, and a chart axis wobbles as it redraws. Putting the numeric variant on the value attribute rather than asking each component to remember it is what makes it impossible to forget.

A role is four values, not one. Each carries a size, a line height, a tracking adjustment and a weight, because they are not independent: large type needs tighter tracking and proportionally tighter leading, small type needs the reverse. Shipping only sizes is how a system ends up with headings that are correctly sized and set too loose.

A role is not a heading level. title2 is an appearance; h2 is document structure. Choose the heading level from the outline of the page and the role from what it should look like. Choosing an h4 because you wanted smaller text is how a document becomes unnavigable for anybody who moves through it by heading.

Your blood pressure was 148 over 92

At 200%

Your blood pressure was 148 over 92

Using it

Default to body and justify anything else. Most text in a health product is body text. A screen with six distinct type roles is usually a screen that has not decided what it is about.

Give a measurement a size of its own, and keep its label and provenance smaller.

Do not add a step. If a size is missing, the usual cause is that a role is being used for the wrong job. A genuine gap is a token proposal rather than a local override, because a local size does not participate in Dynamic Type. See Contributing tokens.

Two weights, three at the outside. Regular for reading, a medium or semibold for emphasis, and a heavier weight reserved for a measurement set apart from running text. Systems with five weights use them to imply importance, and implied importance on a health screen competes with clinical status. See rule 3 on Typography.

Do not set the same content in two roles at two breakpoints. The role is already responsive; overriding it at a breakpoint takes it out of the scale and out of Dynamic Type at the same time.

Tokens

Every role's size, line height, tracking and weight is generated from tokens/type.json by scripts/build-tokens.mts. Every role scales by the same factor when the reader changes their text size, because the multiplier is applied once at the root rather than per role. Specimens are rendered from the generated values, so what you see is the token rather than an illustration of it.

Accessibility impact

• A semantic scale keeps the reader's own setting intact. Because every role resolves to rem and a component asks for the role rather than a pixel size, the reader's text-size multiplier and their browser zoom both reach every step. A single hard-coded size anywhere opts that one element out, and the failure is invisible until somebody actually turns their text size up.
• caption2 is the floor and it is a real floor. Nothing in the system is smaller, and caption2 is still measured for contrast at its own size and weight, because APCA is sensitive to both and a plain WCAG ratio is not.
• Tabular figures materially help low-numeracy and dyslexic readers, who are a large proportion of any consumer health audience. Alignment is not decoration; it is what lets somebody compare two numbers without counting digits.
• Roles and heading levels must not be conflated. Screen-reader users navigate by heading level. A page whose levels were chosen for their appearance is a page whose structure lies.
• Nothing may be smaller than caption2 to make something fit. If text does not fit, the layout is wrong. Shrinking below the floor is how a system quietly ships unreadable provenance lines.

Related

• Dynamic Type says what these roles do as the reader's multiplier changes, and covers the 1.3× bar every component must clear.
• Numbers, units and precision has the canonical rules for what a number should say; this page only sets it.
• Typography tokens has the generated values behind every role.