Font Tokens

Introduction

Font tokens are composite tokens: each holds a whole text style, where a typography token holds one property. A font token has the type typography, and its value is an object with a font family, a font weight, a font size, a line height, a letter spacing, a paragraph spacing, a text case, and a text decoration.

Each property references a typography token, as font.text.medium.strong shows in packages/tokens/source/base/app-base.json:

{
  "font": {
    "text": {
      "medium": {
        "strong": {
          "$type": "typography",
          "$value": {
            "fontFamily": "{typography.fontFamily.text}",
            "fontWeight": "{typography.fontWeight.text.strong}",
            "lineHeight": "{typography.lineHeight.text.medium}",
            "fontSize": "{typography.fontSize.text.medium}",
            "letterSpacing": "{typography.letterSpacing.base.zero}",
            "paragraphSpacing": "{typography.paragraphSpacing.base.zero}",
            "textCase": "{typography.textCase.base.none}",
            "textDecoration": "{typography.textDecoration.base.none}"
          }
        }
      }
    }
  }
}

The build adds one more property, the font style, which it takes from the font weight: normal, or the style that the weight names, such as italic.

Font tokens hold references, so their values follow the typography tokens. A brand changes the text styles by overriding the font families and the font weights, and no font token has to change. Where the token system has the optional screen group, font.website.* differs per screen, because its font sizes do.

Token levels

Font tokens have three levels, and a group for HTML elements next to them. Base tokens combine the typography tokens of one family, one size, and one weight. Context tokens and the fonts of HTML elements combine typography tokens too, by role. Component tokens hold a reference to a base token.

typography.fontFamily.text
typography.fontWeight.text.strong
typography.fontSize.text.medium
typography.lineHeight.text.medium
  font.text.medium.strong             references them
    font.button.medium                {font.text.medium.strong}

Base tokens

Base tokens are named font.<family>.<size>.<weight>. Each combines the family, the weight, the font size, and the line height that the typography tokens hold under the same names: font.display.large.mass references {typography.fontFamily.display}, {typography.fontWeight.display.mass}, {typography.fontSize.display.large}, and {typography.lineHeight.display.large}.

The other properties are the same in every base token: {typography.letterSpacing.base.zero}, {typography.paragraphSpacing.base.zero}, {typography.textCase.base.none}, and {typography.textDecoration.base.none}.

Context tokens

Context tokens name a text style by its role in the content. The table shows the properties that change with the role. The font family is {typography.fontFamily.text}, except in font.context.code.*, which references {typography.fontFamily.code}.

font.context.jumbo and font.context.hero take their font size from the size scale, and their line height is a percentage of that font size. The other context tokens take both from the same step of a typography scale.

Some context tokens change a property that the table does not show. font.context.link.* references {typography.textDecoration.base.underline}, and font.context.expired.* references {typography.textDecoration.base.line-through}. font.context.jumbo tightens its letters with {size.unit.nd05}. Every other letter spacing, text case, and text decoration is that of the base tokens.

HTML elements

The fonts of HTML elements are named after the element. Each takes its font size and its line height from the typography tokens of the same element, and its weight from typography.fontWeight.html.*, where the headings share one weight.

typography.fontFamily.html is a reference that a brand can override, so a brand chooses the family of the HTML elements without changing a font token. font.html.blockquote gets the font style italic from its weight. font.html.paragraph references {typography.paragraphSpacing.base.medium}; the other fonts of the group have no paragraph spacing.

Component tokens

Component tokens assign a base token of the text family to a part of a component. A component token holds the reference only, so it has the properties of the base token it names.

Accordion

Accordion fonts set the title and the body of each accordion size.

Alert

Alert fonts set the title and the body of each alert size. The title is one step larger than the body.

Assist

Assist fonts hold one text style per size, in the normal weight.

Badge

Badge fonts are one step smaller than their name says: font.badge.medium references the small step of the text family.

Breadcrumb

The breadcrumb font sets the text of the pages in a breadcrumb.

Button

Button fonts set the label of each button size, in the strong weight.

Chip

Chip fonts reference the same base tokens as the badge fonts, one step smaller than their name.

Date picker

Datepicker fonts share the small step. The current day and the labels have the strong weight, the other days the normal weight.

Dropdown

Dropdown fonts set the title of a dropdown and its items. The title is smaller than the items.

Form input

Form input fonts set the label and the text of each input size. The floating tokens belong to the input with a floating label, whose label is xsmall.

Modal

Modal fonts set the title and the subtitle of each modal size. The title changes with the size; the subtitle is the same in every size.

Notification

Notification fonts set the title and the message of a notification.

Page

Page fonts set the title and the subtitle of each page size. The large and the medium title reference the same base token.

Section

Section fonts set the header of each section size.

Segment

Segment fonts are one step smaller than their name, as the badge fonts are, in the normal weight.

Tab

Tab fonts reference the same base tokens as the button fonts.

Table

Table fonts share the small step. The head has the strong weight, the data the normal weight.

Website

Website fonts hold properties of their own, not a reference to a base token. Each takes its font size from the typography token of the same name, which the token set of each screen holds. The font family is {typography.fontFamily.text}, and the line height is a percentage of the font size, so it follows the font size of the screen.

The website fonts are defined in packages/tokens/source/screen-website/screen-base.json, and the other font tokens in packages/tokens/source/base/app-base.json.

Usage

Choose the level that names the text:

• Use a component token for the part of a component that it names, such as font.button.medium for the label of a medium button.
• Use a context token for content with a role: font.context.heading, font.context.body.medium, font.context.link.medium.
• Use a base token where no context or component token fits. No context or component token references the display family, so font.display.* is the way to set a text in it.
• Use font.html.* for the default style of an HTML element.

Give a new component token a reference to a base token, as the existing component tokens have. The token then follows the typography scales and the fonts of each brand.

A font token holds no color. Set the color of a text with a color token.

Platform output

A font token prints as one Sass map on the web, and as one constant or resource per property on iOS and Android. The table shows the font size of font.context.jumbo on iOS and Android.

The values in the examples of this section are those of the chassis brand in the current version, and they differ in other brands.

The build writes the map of the web to main.scss, on one line. The keys are CSS properties: the paragraph spacing is margin-bottom, and the text case is text-transform.

$cx-font-context-jumbo: ("font-family": var(--font-family-text), "font-weight": var(--font-weight-text-mass), "font-size": 6rem, "line-height": 1.25em, "font-style": normal, "letter-spacing": -0.0313em, "margin-bottom": 0rem, "text-transform": none, "text-decoration": none) !default;

The web platform names the custom properties of Chassis CSS for the family, the weight, the font size, and the line height that a font token references, so its maps work with Chassis CSS only. The presets web-scss, web-px, and web-vw print the values; see the Style Dictionary page.

iOS and Android name each constant or resource after the token and the property. The format of a property is the format of its typography token, except for the line height and the letter spacing.

The build writes the sizes of a font token to the number file of each screen, and the other properties to the string file. The main file holds all of them. On iOS, NumberLarge.swift has these lines:

    public static let FontContextJumboLineHeight = CGFloat(120)
    public static let FontContextJumboFontSize = CGFloat(96)
    public static let FontContextJumboLetterSpacing = CGFloat(-0.5)
    public static let FontContextJumboParagraphSpacing = CGFloat(0)

On Android, number_large.xml has the same properties:

  <dimen name="font_context_jumbo_line_height">120sp</dimen>
  <dimen name="font_context_jumbo_font_size">96sp</dimen>
  <item name="font_context_jumbo_letter_spacing" type="dimen" format="float">-0.0052</item>
  <dimen name="font_context_jumbo_paragraph_spacing">0sp</dimen>

The line height and the letter spacing print by rules of their own inside a font token:

• A line height that is a percentage prints in em on the web. iOS and Android print a size: that percentage of the font size of the same token.
• The letter spacing on Android is in ems of the font size of the same token, which android:letterSpacing takes.

See the web, iOS, and Android docs for the files that hold these names.