How to Design Typography Tokens Without Mistaking 14px / 16px / 20px for a Type System

A real Typography Token does more than store font-size as a variable. It binds semantic roles such as page heading, component heading, body, and supporting information to cross-platform type parameters so design and code can share the same hierarchy reliably.

Many "font tokens" merely rename 12, 14, 16, 20, and 24 as font-100 and font-200. Designers still have to remember whether a page heading uses 600 or 700, while developers assemble line-height and weight themselves. These tokens are variables, but they have not reduced decision cost.

01 1. The Core of a Typography Token Is Its Role, Not Its Size

Atlassian's current typography system maps design styles such as Heading / XXL, XL, L, and M to typography tokens in code and explains where each applies, including brand marketing, page headings, and component headings. Carbon also manages type through tokens and distinguishes productive type for product efficiency from more expressive type. The common principle is that a token must say what hierarchy the text serves, not merely how many pixels it uses.

02 2. Which Properties Belong in a Typography Token?

At minimum, consider font family, font size, font weight, and line height, with letter spacing and font style where needed. Complex systems may also include variable-font axes, text transform, and platform differences. Do not split size, line height, and weight into three unrelated tables and make users rebuild the combination every time.

03 3. A Primitive → Semantic Model Is Easier to Maintain

The Primitive layer stores foundation values such as size-100=12px, size-200=14px, and weight-semibold=600. The Semantic layer describes use, such as typography-body-default, typography-heading-page, and typography-label-small, and references the foundation values.

When the brand font changes or product density is adjusted, the team can update mappings rather than revise every page. DTCG 2025.10 is the first stable Design Tokens format and provides a standardized foundation for exchanging types, values, descriptions, and references among tools. The team must still define which semantic levels fit its product.

04 4. Do Not Confuse HTML Headings with Visual Font Sizes

The visually largest text is not necessarily always an h1, but the page still needs a correct semantic structure. Atlassian's typography guidance likewise emphasizes correct HTML heading hierarchy for assistive technology. Design system documentation should explain the relationship between visual tokens and semantic elements so developers do not select the wrong tag merely to get a style.

05 5. Body Readability Depends on More Than Font Size

Long-form body text requires coordinated font size, line height, line length, and weight. Atlassian's general guidance recommends roughly 16px or larger for long-form content, but tables and compact components in a back-office product may need smaller levels. Do not turn that into an absolute rule that "all product body text must be 16px." Establish levels for each content type.

06 6. Chinese and English Need More Than One Shared Screenshot Test

Chinese characters differ substantially from English in visual density, character height, and punctuation. A 14px/20px combination may feel relaxed in English but crowded in a Chinese interface. Mixed Chinese and English, numbers, financial symbols, Japanese, and font fallbacks also matter. Typography tokens can share semantic roles while different locales map to different families, weights, or line heights.

07 7. Responsive Type Does Not Mean Setting Every Size in vw

Large marketing headlines can use fluid typography that changes smoothly within a controlled viewport range, while product buttons, tables, and form labels benefit from stable sizes. Define min/max values and fluid rules for Display tokens, while keeping Body and UI tokens relatively stable. This preserves brand expression without letting operational interfaces grow indefinitely on ultrawide screens.

08 8. Do Not Assume the Same Font Weight Looks the Same in Every Typeface

A weight of 600 can look very different across families, and some fonts do not contain a genuine 600 at all, leaving the browser to synthesize it. Replacing a font requires a new optical and readability review rather than retaining identical numbers. For variable fonts, define the allowed axis ranges so design tools and production code do not render differently.

09 9. Map Figma Text Styles Explicitly to Code Tokens

If the design style is called "Heading / M," the corresponding token or component should be easy to find in code. Do not let designers use local Text Styles while developers maintain a separate set of Sass variables. Ideally, tokens act as the shared source of truth that generates Figma styles, CSS variables, and platform resources.

10 10. How Should You Control the Number of Tokens?

If two tokens have identical properties in 95% of cases and differ only because they came from different pages, the system will expand rapidly without adding meaning. Begin with stable roles: Display, Page heading, Section heading, Component heading, Body, Label, Helper, and Code, then extend from real scenarios. For every new token, ask whether it represents a new semantic role or merely a request to make one page "slightly larger."

A good Typography System changes the conversation from "Should this be 18 or 20?" to "Is this a page heading or a component heading?" Tokens begin to work when the decision language changes.

Frequently Asked Questions

What is the difference between a Typography Token and a Figma Text Style?

A Text Style is a way to apply type in a design tool. A token is design-decision data shared across tools and code. They can map one to one, but they are not the same concept.

Should font tokens be named by size or purpose?

Name the foundation layer by value or scale and the semantic layer by purpose, such as body-default and heading-page. This makes systemic adjustment easier.

Do Chinese and English need separate Typography Tokens?

They can share roles, while font family, line height, or some sizes may use locale mappings. Whether to split them depends on the product's language complexity.

Must all body text be 16px?

No absolute rule applies. Long-form content generally needs a more comfortable size, while dense back-office interfaces may use smaller text. Validate reading distance, line height, contrast, and task type together.

Are more granular tokens always better?

No. Excessive granularity recreates choice overload. Tokens should represent stable, repeatable semantic roles.