Typography Properties in DESIGN.md Tokens: Complete Reference for Design Systems

The DESIGN.md specification supports seven CSS typography properties—fontFamily, fontSize, fontWeight, lineHeight, letterSpacing, fontFeature, and fontVariation—that enable design systems to define consistent typographic scales through typed tokens.

The google-labs-code/design.md repository provides a structured Markdown format for documenting design systems. Understanding which typography properties can be defined in DESIGN.md tokens allows you to create portable, code-generating design specifications that map directly to CSS font attributes.

Supported Typography Properties in DESIGN.md

According to the token schema defined in docs/spec.md, the typography section contains typed tokens describing the complete set of CSS font properties a design system can expose. Each typography token accepts the following fields:

• fontFamily (string): Name of the font family (e.g., Public Sans).
• fontSize (string): Base font size using any CSS length unit (rem, px, em).
• fontWeight (number): Numeric weight such as 400, 600, or 700. Both bare numbers and quoted strings are accepted.
• lineHeight (string): Line-height value as a unit-less multiplier or explicit length.
• letterSpacing (string): Letter-spacing value, either absolute (0.1rem) or relative (0.05em).
• fontFeature (string): OpenType feature settings (e.g., "liga on").
• fontVariation (string): Variable-font axis settings (e.g., "wght 700").

A token may include any subset of these fields. Omitted properties do not generate CSS declarations and instead inherit from the rendering environment's defaults.

Defining Typography Tokens in DESIGN.md Files

Typography tokens are defined within the YAML front-matter of a DESIGN.md file under the typography key.

Front-Matter Token Definition

The following example from the repository's README.md demonstrates a complete typography configuration:

---
name: Heritage
typography:
  headline-xl:
    fontFamily: Public Sans
    fontSize: 2.5rem
    fontWeight: 700
    lineHeight: 1.2
    letterSpacing: 0.02rem
    fontFeature: "liga on"
    fontVariation: "wght 700"
  body-md:
    fontFamily: Public Sans
    fontSize: 1rem
    fontWeight: 400
    lineHeight: 1.5
    letterSpacing: 0.01rem
  label-sm:
    fontFamily: Space Grotesk
    fontSize: 0.75rem
    fontWeight: 500
---

Each key under typography becomes a reusable token encapsulating the specified font properties. Real-world implementations in examples/totality-festival/DESIGN.md and examples/paws-and-paths/DESIGN.md demonstrate how these tokens function in production design systems.

Referencing Typography Tokens in Components

Components reference typography tokens to ensure consistent text styling across the design system.

Component-Level Typography Assignment

As implemented in the component schema documented in README.md, apply a typography token using the typography field:

components:
  button-primary:
    backgroundColor: "{colors.tertiary}"
    textColor: "{colors.on-tertiary}"
    rounded: "{rounded.sm}"
    padding: 12px
    typography: "{typography.label-sm}"

This reference pulls the full set of font properties from the typography.label-sm token, applying them to all text within the component.

Using Typography Tokens in Markdown Content

Typography tokens can be referenced directly within the markdown body of a DESIGN.md file, particularly when generating configuration files for CSS frameworks.

The following pattern from examples/totality-festival/DESIGN.md shows inline token usage:

# Example usage

The headline uses the `{typography.headline-xl}` token, guaranteeing the exact size, weight and spacing across the site.

When processed by the CLI, these references resolve to concrete CSS values during export to frameworks like Tailwind CSS.

Summary

• The DESIGN.md specification in google-labs-code/design.md supports seven typography properties: fontFamily, fontSize, fontWeight, lineHeight, letterSpacing, fontFeature, and fontVariation.
• Token definitions reside in the YAML front-matter of DESIGN.md files, as formally specified in docs/spec.md.
• Components reference typography tokens using the {typography.token-name} syntax to inherit complete font styling.
• Tokens can define any subset of properties; unspecified values inherit from the browser's default rendering environment.

Frequently Asked Questions

What file defines the official typography token schema?

The complete specification for typography properties is documented in docs/spec.md within the google-labs-code/design.md repository. This file enumerates the seven supported CSS font properties that constitute a valid typography token.

Can typography tokens include only a subset of properties?

Yes. A typography token may include any combination of the seven supported properties. Omitted properties do not generate CSS declarations, allowing the rendering environment's defaults to apply. For example, a token defining only fontFamily and fontSize is valid.

How are typography tokens exported to CSS frameworks?

The DESIGN.md CLI processes token references like {typography.headline-xl} during export. As demonstrated in examples/totality-festival/DESIGN.md, these references resolve to concrete CSS values when generating framework-specific configurations such as Tailwind CSS theme extensions.

What is the difference between fontFeature and fontVariation?

The fontFeature property controls OpenType feature settings such as ligatures ("liga on"), while fontVariation configures variable font axis settings like weight or width ("wght 700"). Both accept string values but target different aspects of font rendering.

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