Typography Token Schema in DESIGN.md: Structure and Properties Explained

Typography tokens in DESIGN.md follow a strict schema where each token name maps to a Typography object containing five required properties: fontFamily, fontSize, fontWeight, lineHeight, and letterSpacing.

The google-labs-code/design.md repository establishes a standardized format for design tokens that ensures consistency across design systems. Understanding the typography token schema is essential for correctly defining text styles in your DESIGN.md files. Each typography token follows a specific map structure defined in the official specification at docs/spec.md (lines 151-202).

Typography Token Structure

Typography tokens are defined as a map where each key represents a semantic token name (such as h1, body-md, or label-caps) and each value must be a Typography object.

Required Properties

According to the specification in docs/spec.md, every Typography object must include exactly five properties:

Property	Type	Description
fontFamily	string	Name of the font family (e.g., Public Sans, Space Grotesk)
fontSize	string	Font size with units (e.g., 48px, 16px)
fontWeight	number or string	Numeric weight (e.g., 600) or named weight (e.g., Bold)
lineHeight	number or string	Line-height multiplier or value (e.g., 1.1, 1.6)
letterSpacing	string	Letter-spacing value with units (e.g., -0.02em, 0.1em)

YAML Schema Definition

The complete schema structure can be expressed in YAML format as follows:

typography:
  <token-name>:
    fontFamily: <string>
    fontSize: <string>
    fontWeight: <number|string>
    lineHeight: <number|string>
    letterSpacing: <string>

Implementing Typography Tokens

To define typography tokens in your DESIGN.md file, create a typography section at the root level with named tokens containing all required properties.

typography:
  h1:
    fontFamily: Public Sans
    fontSize: 48px
    fontWeight: 600
    lineHeight: 1.1
    letterSpacing: -0.02em
  body-md:
    fontFamily: Public Sans
    fontSize: 16px
    fontWeight: 400
    lineHeight: 1.6
    letterSpacing: 0
  label-caps:
    fontFamily: Space Grotesk
    fontSize: 12px
    fontWeight: 500
    lineHeight: 1
    letterSpacing: 0.1em

Referencing Typography Tokens in Components

Once defined, typography tokens are referenced within component definitions using the interpolation syntax {typography.<token-name>}.

## Example Component

components:
  card-title:
    typography: "{typography.h1}"
    textColor: "{colors.primary-80}"

The reference {typography.h1} points directly to the h1 token defined in the typography map.

Source Files and Schema Documentation

The typography token schema is formally defined in the following locations within the google-labs-code/design.md repository:

• docs/spec.md: Contains the official schema definition and property specifications (lines 151-202)
• README.md: Provides a summary of token sections and usage patterns (lines 66-71)
• examples/totality-festival/DESIGN.md: Demonstrates real-world implementation of typography tokens in production design files

Summary

• Typography tokens in DESIGN.md use a map structure with token names as keys and Typography objects as values
• Each Typography object requires five mandatory properties: fontFamily, fontSize, fontWeight, lineHeight, and letterSpacing
• The schema supports flexible fontWeight values as either numbers (600) or strings (Bold)
• Reference tokens in components using the syntax {typography.token-name}
• Official documentation resides in docs/spec.md with examples available in the examples/totality-festival/ directory

Frequently Asked Questions

What are the required properties for a typography token in DESIGN.md?

Every typography token must include five properties: fontFamily (string), fontSize (string with units), fontWeight (number or string), lineHeight (number or string), and letterSpacing (string with units). These requirements are enforced according to the schema defined in docs/spec.md.

Can fontWeight be specified as either a string or number in DESIGN.md typography tokens?

Yes, the fontWeight property accepts both numeric values like 600 or 700 and named weights like Bold or Regular. This flexibility allows integration with various design tools and CSS frameworks while maintaining type safety.

How do you reference a typography token in a DESIGN.md component definition?

Typography tokens are referenced using the interpolation syntax {typography.<token-name>}. For example, to use an h1 token, you would write "{typography.h1}" in the component's typography field.

Where is the official typography token schema defined in the design.md repository?

The official schema is documented in docs/spec.md at lines 151-202, with additional context in the repository's README.md at lines 66-71. Practical examples can be found in examples/totality-festival/DESIGN.md.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}