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

> Learn how to define typography tokens with font family, size, and weight in DESIGN.md. Explore YAML front-matter and schema for consistent design.

- Repository: [Google Labs Code/design.md](https://github.com/google-labs-code/design.md)
- Tags: tutorial
- Published: 2026-07-01

---

**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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md) (lines 29-36).

## Complete YAML Examples

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

```yaml
---
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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/examples/totality-festival/DESIGN.md)**: Demonstrates typography tokens within a festival branding context.
- **[`examples/paws-and-paths/DESIGN.md`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/examples/totality-festival/DESIGN.md) and [`examples/paws-and-paths/DESIGN.md`](https://github.com/google-labs-code/design.md/blob/main/examples/paws-and-paths/DESIGN.md). These files demonstrate complete typography token definitions alongside complementary design tokens like colors and spacing.