Typography

Headings

.h1 through .h6 apply a heading's appearance to any element. Use them to keep the document outline honest: the heading level should come from where the section sits in the page, and the size from how it should look. A card title that is the third level of the document is an <h3> with .h5 on it, not an <h5>.

.display is a size above .h1, for the one line at the top of a landing page. .lede is the paragraph directly under a heading: larger, looser, muted, and capped at the measure.

<h3 class="h5">A third-level heading that looks like a fifth</h3>
<p class="lede">The lede sets its own measure, so it stays readable however wide the column gets.</p>

.prose caps inline size at --measure (68ch), which is the line length research keeps landing on for continuous reading. It is the one class here that is about the block rather than the glyphs.

Size

Eight steps, each reading a --text-* token. The scale is a ratio rather than a series of round numbers, so the steps stay distinguishable at both ends. .text-cq and .display-cq size against the nearest .cq container instead of a fixed value, which is how a heading in a sidebar stays small on a wide monitor.

Weight

Four weights, and two of them are not round numbers. Deck's default face is variable, so 540 and 620 are available and are better choices than 500 and 600: at text sizes 500 is nearly indistinguishable from 400, and 600 is heavy enough to read as bold when it is meant to read as emphasis.

Alignment and casing

.text-start and .text-end are logical: they follow the text direction, so a right-to-left page mirrors without a second rule. There is no .text-left or .text-right, for the same reason there is no .ml-4.

.uppercase adds a small amount of letter-spacing along with the transform, because capitals set at the same tracking as lower case read as cramped. .nums switches on tabular figures, which is what you want in any column of numbers that has to line up.

Truncation

.truncate is one line with an ellipsis; .clamp-2 and .clamp-3 are two and three. All three hide text, so none of them should be the only place a value appears — put the full string in a title attribute or somewhere it can be read.

.truncate also sets min-inline-size: 0, without which it silently does nothing inside a flex row: a flex item will not shrink below its content by default, so the ellipsis never gets a chance to appear.

Writing modes

Six classes for vertical text — Japanese and Mongolian setting, and the rotated column header in a dense table, which is what .th-vertical is for. .writing-upright keeps Latin characters upright inside a vertical run instead of rotating them, and adds tracking, because upright Latin in a vertical column needs more air than horizontal Latin does.

Direction and bidi

These are for text whose direction differs from the page around it: an English product name inside an Arabic sentence, a file path in a Hebrew paragraph. Without isolation the bidi algorithm reorders punctuation at the boundary and a path ending in a slash comes out with the slash on the wrong end.

.bidi-isolate is the one to reach for when you know the direction of the run. .bidi-plaintext is for user-supplied strings whose direction you do not know — it takes the direction from the first strong character in the string, which is what a chat message or a comment field needs. .code-ltr is the specific case of a code span or path, which is always left to right whatever the page is.

When not to use these

• Not instead of a heading element. .h2 on a <div> looks like a heading and is not one. Screen reader users navigate by heading, and a div is not in that list.
• Not to shrink text below .text-xs for body copy. .text-2xs exists for a timestamp or a unit label beside something larger. A paragraph at that size is a paragraph nobody reads.
• Not .truncate on something with no other home. A truncated string with no title and no detail view is a value the reader cannot get at.
• Not .uppercase on a long run. Capitals lose the word shapes that make reading fast. It is for a label of one or two words.