Typography Tokens

Overview

Typography tokens define the typographic styles used throughout the design system to ensure consistency in text appearance across all platforms and applications. They control font families, weights, sizes, line heights, spacing, and text decorations.

Architecture

Chassis Tokens uses a layered typography architecture where foundational tokens defined in the Brand group are referenced by composite typography tokens in the App group. This separation allows brand-specific typography choices to automatically propagate through all text styles.

How it works:

Brand group tokens define the core typographic identity:

• Font families for different text categories (text, display, code)
• Font weights with semantic names (normal, strong, mass, elegant)

App group tokens combine these foundational elements with size and spacing values to create complete typography styles ready for use in components:

• font.text.medium.normal combines fontFamily, fontWeight, fontSize, lineHeight, and other properties
• Composite tokens automatically adapt when brand fonts or weights change

Benefits:

• Switch font families across entire system by changing brand tokens
• Maintain consistent typographic hierarchy across brands
• Single source of truth for each font property
• Automatic updates when brand typography changes

Organization

Typography tokens in Chassis are organized into several categories:

Primitive Tokens (Brand group): Core typographic properties including font families and font weights that define brand identity.

Modular Tokens (App group): Individual typographic properties like font sizes, line heights, letter spacing, and paragraph spacing that can be combined in different ways.

Composite Tokens (App group): Complete typography styles combining multiple properties (family, weight, size, line height, spacing) into ready-to-use text styles.

Contextual Tokens (App group): Semantic typography styles assigned to specific use cases like headings, body text, labels, and UI component text.

This multi-tier organization provides both flexibility (through modular tokens) and convenience (through contextual tokens) when applying typography to UI elements.

Font Families

Font family tokens define the typefaces used throughout the design system. These are defined in the Brand group and reference specific font families installed in the design environment or available via web fonts.

Example Values

{
  "typography": {
    "fontFamily": {
      "text": {
        "$type": "fontFamilies",
        "$value": "'Helvetica Neue', Helvetica, Arial, system-ui, -apple-system, sans-serif"
      },
      "display": {
        "$type": "fontFamilies",
        "$value": "'Times New Roman', Times, serif"
      },
      "code": {
        "$type": "fontFamilies",
        "$value": "'Courier New', Courier, monospace"
      }
    }
  }
}

Font Weights

Font weight tokens define the thickness or boldness of type. These semantic weight names ensure consistent visual hierarchy while allowing different brands to interpret weights differently based on their chosen typefaces.

where [family] can be text, display, or code.

Weight Hierarchy

The semantic naming provides a clear hierarchy:

• elegant: Minimal visual weight, used sparingly for sophisticated treatments
• normal: Default weight for most content
• strong: Clear emphasis without overpowering
• mass: Maximum impact for critical elements

Typography Properties

Modular typography tokens are individual properties that can be combined to create complete text styles. These tokens provide fine-grained control over typography while maintaining consistency.

Font Sizes

Font size tokens define the size of text across the system. Two sets of sizes are available:

where [size] can be: 2xsmall, xsmall, small, medium, large, xlarge, 2xlarge, 3xlarge, 4xlarge, 5xlarge

Line Heights

Line height tokens control the vertical spacing between lines of text. Proper line height improves readability and visual rhythm.

Letter Spacing

Letter spacing (tracking) tokens control the horizontal space between characters.

Paragraph Spacing

Paragraph spacing tokens define the vertical space between paragraphs.

Text Case

Text case tokens control capitalization.

Text Decoration

Text decoration tokens control underlines and strikethroughs.

Composite Tokens

Composite typography tokens combine multiple properties into complete, ready-to-use text styles. These are defined in the App group and are the primary tokens used when designing interfaces.

Example composite token:

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

Text Family Styles

Text family styles use the primary text font family and are available in multiple sizes and weights. These are the workhorses of the design system, used for most UI text.

Display Family Styles

Display family styles use the display font family for headings and prominent text.

Code Family Styles

Code family styles use the monospaced code font family.

Contextual Typography

Contextual typography tokens assign semantic meaning to text styles, making it clear what type of content each style is intended for. These reference composite text styles and provide the most convenient way to apply typography.

Content Hierarchy

Titles

Body Text

Highlights

Component Typography

Component-specific typography tokens reference contextual or composite tokens and are used directly in UI components. These ensure consistent typography across all component implementations.

Button Typography

Form Input Typography

Badge Typography

Alert Typography

HTML Element Typography

HTML element typography tokens provide default styles for semantic HTML elements, ensuring consistent typography when rendering content from CMS systems or markdown.

Usage Guidelines

Choosing the Right Token

For components: Use component-specific tokens (font.button.*, font.form-input.*, etc.)

For content: Use contextual tokens (font.context.body.*, font.context.title.*, etc.)

For custom styles: Use composite tokens (font.text.[size].[weight], font.display.[size].[weight])

For fine control: Use modular tokens (typography.fontSize.*, typography.lineHeight.*, etc.)

Accessibility

• Minimum font size for body text should be 16px (medium) for readability
• Use strong or mass weights to ensure sufficient contrast in text hierarchy
• Line heights of 1.5× or greater improve readability for body text
• Avoid using elegant (light) weights for small text sizes

Performance

• Limit the number of font families loaded to 2-3 maximum
• Load only the font weights actually used in your design
• Use system fonts when performance is critical
• Consider variable fonts for flexible weight options with minimal file size

Brand Customization

To customize typography for a new brand:

1. Create a brand token set (e.g., brand-acme.json)
2. Override typography.fontFamily.* tokens with brand-specific fonts
3. Override typography.fontWeight.* tokens to match available weights
4. All composite and contextual tokens automatically update

Example:

{
  "typography": {
    "fontFamily": {
      "text": {
        "$type": "fontFamilies",
        "$value": "'Inter', sans-serif"
      },
      "display": {
        "$type": "fontFamilies",
        "$value": "'Playfair Display', serif"
      }
    },
    "fontWeight": {
      "text": {
        "normal": {
          "$type": "fontWeights",
          "$value": "Regular"
        },
        "strong": {
          "$type": "fontWeights",
          "$value": "SemiBold"
        },
        "mass": {
          "$type": "fontWeights",
          "$value": "Bold"
        },
        "elegant": {
          "$type": "fontWeights",
          "$value": "Light"
        }
      }
    }
  }
}