How to Define Typography Tokens with Font Family, Size, and Weight in DESIGN.md

Typography tokens in DESIGN.md are defined within the YAML front-matter as a typography map containing properties like fontFamily, fontSize, and fontWeight, following the schema specified in docs/spec.md.

The google-labs-code/design.md repository establishes a machine-readable format for declaring design tokens directly in markdown files. Defining typography tokens with font family, size, and weight in DESIGN.md creates portable text styles that synchronize across Figma, Tailwind CSS, and other design-to-code workflows.

Understanding the Typography Token Schema

According to docs/spec.md (lines 84-90), each typography token follows a strict property schema based on CSS typography values. The specification requires three core fields for every typography token:

• fontFamily: A string specifying the typeface name (e.g., Public Sans or Space Grotesk).
• fontSize: A dimension value including units (px, em, rem).
• fontWeight: A numeric value such as 400 for regular text or 700 for bold.

The schema also defines optional properties for advanced styling: lineHeight (accepting either dimension values or unitless multipliers), letterSpacing (dimension), and fontFeature or fontVariation strings for OpenType feature settings.

Step-by-Step: Creating Typography Tokens

To define typography tokens in your DESIGN.md file:

1. Open the YAML front-matter block at the top of the file, delimited by triple dashes (---).
2. Declare a typography root key to contain all text style definitions.
3. Define semantic token names (such as h1, body-md, or label-caps) as child keys containing the required property fields.

This structure follows the introductory example shown in docs/spec.md (lines 29-36).

Complete YAML Examples

The following example demonstrates three distinct typography tokens implementing different font families and weights:

---
version: alpha
name: Daylight Prestige
typography:
  # Heading level 1 – large, bold display text

  h1:
    fontFamily: Public Sans
    fontSize: 48px
    fontWeight: 600
    lineHeight: 1.1
    letterSpacing: -0.02em

  # Body copy – medium-sized regular text

  body-md:
    fontFamily: Public Sans
    fontSize: 16px
    fontWeight: 400
    lineHeight: 1.6

  # Upper-case label – small, spaced text for UI controls

  label-caps:
    fontFamily: Space Grotesk
    fontSize: 12px
    fontWeight: 500
    lineHeight: 1
    letterSpacing: 0.1em
---

Implementation patterns illustrated:

• h1 uses a semi-bold weight (600) with negative letterSpacing to tighten large display text.
• body-md employs a unitless lineHeight multiplier (1.6), which scales proportionally with the fontSize.
• label-caps demonstrates mixing font families and positive letterSpacing to achieve all-caps label aesthetics.

Optional Typography Properties

Beyond the required fields, the schema in docs/spec.md supports additional fine-tuning for specialized typographic control:

• lineHeight: Accepts either dimension values (24px) or unitless multipliers (1.5).
• letterSpacing: Controls tracking with dimension values like 0.1em or -0.02em.
• fontFeature and fontVariation: Enable advanced OpenType features or variable font axis configurations.

These optional fields allow precise text rendering adjustments while maintaining compatibility with design token consumers.

Reference Implementations in Example Projects

Real-world usage appears in the repository's example directories, demonstrating how typography tokens integrate with broader design systems:

• examples/totality-festival/DESIGN.md: Demonstrates typography tokens within a festival branding context.
• examples/paws-and-paths/DESIGN.md: Illustrates typography implementation for a nature-focused project interface.

Both files showcase complete typography map definitions alongside color and spacing tokens within the YAML front-matter block.

Summary

• Typography tokens reside in the YAML front-matter of DESIGN.md under the typography key.
• Required properties are fontFamily (string), fontSize (dimension), and fontWeight (number).
• Optional properties include lineHeight, letterSpacing, fontFeature, and fontVariation.
• The schema is formally defined in docs/spec.md (lines 84-90) with introductory examples at lines 29-36.
• Reference implementations exist in examples/totality-festival/ and examples/paws-and-paths/ for practical guidance.

Frequently Asked Questions

What file format does DESIGN.md use for typography tokens?

DESIGN.md uses YAML front-matter enclosed by triple dashes (---) at the beginning of the file. The typography tokens are defined within this YAML block as a map under the typography key, making them both human-readable and parseable by automated design token pipelines.

Can I use relative units like rem or em for font sizes?

Yes, the fontSize property accepts any CSS dimension value including px, rem, em, or viewport units. The specification in docs/spec.md treats these as dimension types, so unit flexibility is built directly into the schema.

How do I specify font weights for variable fonts?

Use the fontWeight field with a numeric value (100-900) as you would with standard fonts. For variable fonts requiring specific axis settings beyond weight, utilize the optional fontVariation property to declare variable font axis values according to the OpenType specification.

Where can I see a complete working example of DESIGN.md with typography?

The repository provides working examples in examples/totality-festival/DESIGN.md and examples/paws-and-paths/DESIGN.md. These files demonstrate complete typography token definitions alongside complementary design tokens like colors and spacing.

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