Typography - Token Type

Style text elements by composing many typography-related design decisions together into a single Typography Token.

Each of the nine design decisions (font size, letter spacing, etc.) that is part of the Composite Token is referred to as a property of the Typography Token in out guides.

Creating a new Typography Token in the Tokens Studio Plugin for Figma.

---

Design decisions

Typography Tokens define a group of properties used to style text elements.

In CSS, this is known as the Text and Font Styling properties, which are defined individually.

Typography Tokens can be applied to text layers to define all styling decisions in a single token.

Each property composed to style text elements can be defined as it's own Token and referenced within the Typography Composite Token:

1. Font family

2. Font weight

3. Font size

4. Line height

5. Letter spacing

6. Paragraph indent

7. Paragraph spacing

8. Text decoration

9. Text case

Typography Tokens can be attached to Text Styles in Figma.

---

Possible values

Like all Composite Tokens, you define the value of each property individually. When you create the Typography Token in the plugin, you can reference each Token you've already created as a property or enter a hard-coded value.

The best practice is to define all parts of a Composite Token, even with a null/none value, rather than to leave it empty.

Hard coded values

The dedicated Token Type of each property within the Typography Composite Token has unique specifications, described in detail in their own guides.

1

Font Family

Font Family defines the typeface.

• It must be written as a string value that exactly matches how Figma has it written in their UI.

• It acts as a 'pair' with Font Weight due to Figma's unique approach to text styling.

→ Jump to the Font Family Guide

2

Font Weight

Font Weight defines the thickness and styling of the characters of a typeface.

• It can be written as a unitless number, or a string value that exactly matches how Figma has written it their UI for the particular typeface.

• It acts as a 'pair' with Font Family due to Figma's unique approach to text styling.

→ Jump to the Font Weight Guide

3

Font Size

Font Size defines the height of the glyphs/characters of a typeface.

• It should be written as a numeric value with a unit of measurement in either pixels or rem.

• Font Size impacts the Line Height and Letter Spacing values.

→ Jump to the Font Size Guide

4

Line Height

Line Height defines the vertical distance of each line of text related to its font size.

• It should be written as a numeric value with a percentage to support responsive design in Figma.

• Values without a percentage unit will be assumed as a fixed value in pixels.

→ Jump to the Line Height Guide

5

Letter Spacing

Letter Spacing defines the horizontal distance between each glyph/character related to its font size.

• It should be written as a numeric value with a percentage to support responsive design in Figma.

• Values without a percentage unit will be assumed as a fixed value in pixels.

→ Jump to the Letter Spacing Guide

6

Paragraph Spacing

Paragraph Spacing defines the vertical distance between 2 paragraphs of text

• It should be written as a numeric value with a unit of measurement in either pixels or rem.

• Values without a unit will be assumed as a fixed value in pixels.

→ Jump to the Paragraph Spacing Guide

7

Paragraph Indent

Paragraph Indent defines an offset of the first word of every paragraph.

• It should be written as a numeric value with a unit of measurement in either pixels or rem.

• Values without a unit will be assumed as a fixed value in pixels.

→ Jump to the Paragraph Indent Guide

8

Text Decoration

Text Decoration defines the position of an optional line in a string of text.

• It should be written as the string value that matches the intended property.

→ Jump to the Text Decoration Guide

9

Text Case

Text Case defines a transformation to the capitalization of letters in a string of text.

• It should be written as the string value that matches the intended property.

→ Jump to the Text Case Guide

Any property defined within the Typography Token that accepts numeric values can use math to calculate their value in Tokens Studio.

There's an example in the image below for Line Height and Letter Spacing to convert a unitless number into a percentage to accommodate Figma's limitations on those properties.

→ Jump to the guide on Tokens with Math Values for more details.

Values that reference another Token

Like all Composite Tokens, you may reference an existing Token as the value for each individual property as described above ↑.

If you'd prefer to reference an existing Typography Composite Token as the value instead of defining each Property, select the Token's Reference mode button (2x2 circle icon).

Once the Typography Token form is open, you can select the icon button to reference a Typography composite Token as the value.

When trying to reference another Token as the Value for a Typography Token, you will see Tokens in the dropdown list that are:

• Living in Token Sets that are currently active.

  • In the left menu on the plugin's Tokens page, a checkmark is visible next to the Token Set name.

• Token Type is compatible:

  • typography

However, like all Token Types, you can "force" a reference by manually entering the Token Name between curly brackets.

For example {token.name.here}

The value will show a broken reference until the originating Token Set is marked as enabled.

Jump to the guide on Token Values with References by selecting the card below to learn more.

Token Values with References

---

Apply Typography Tokens

Typography Tokens define all 9 styling properties of text when the Token is applied.

With one or more text layers selected in Figma, click on the name of a Typography Token in the Plugin to instantly apply its value.

Keep in mind, Tokens can only be applied to the entire layer. In the case of Typography, you might want to apply a Token to a particular word within the text layer, but that is not possible today due to limitations of the Figma plugin API.

💌 Create a free account to upvote on the feature request for this here and we will notify you when we start working on it.

Once a Token has been applied, it will remain attached until you manually remove it.

---

Text Styles in Figma

Typography Tokens can be Exported to Figma as Text Styles. Tokens Studio also supports Styles with Variable References.

Here are some tips for creating Text Styles with Variable References using the Plugin.

Before you export your Typography Tokens to Figma as styles, ensure each property within the Typography Tokens has a value referencing another Token.

When you Export to Figma, select these Options from the menu:

• Typography Styles is selected.

• Number and String Variables are selected.

• Create styles with variable references is selected.

Select the Export Styles and Variables from the Tokens page to configure the Options.

Ensure your Export to Figma as Themes or Sets configuration includes all necessary Tokens.

• Themes and token sets where the referenced Tokens are located are active.

• Themes and token sets where the variables are attached may need to be configured as reference only.

You'll notice these Variables are created on Export based on their Token Type:

• fontFamily (will create as string variable)

• fontWeight (will create either as string or number variable, depending on if they are a string or a number)

• letterSpacing (number variable)

• lineHeight (number variable)

• paragraphSpacing (number variable)

• paragraphIndent (number variable)

You'll notice the Text Style will be created on Export, with all possible values mapped to the appropriate Variables, based on the Token Type for each property.

For Tokens using percentage units %, the plugin will not map this property to the variable created to preserve the responsive design decision in the token.

A Text Style created with Variable References from the Plugin will leave properties with percentage values attached to the Token value and not a variable. The remaining text properties will be attached to Variables.

Known issue with Font Weight as Figma doesn't allow changing a Variable Type after its been created.

If you are converting your Font Weight Tokens between numeric and string values and you've already exported to Figma as a Style with Variable References, you may need to delete the Variable from the Figma collection.

Figma doesn't allow the changing of a Variable type, so by deleting that single Variable in Figma, when you export the Typography Token as a Style with Variable References, the Plugin will create the variable with the new Token Type.

Jump to the guide on Exporting Tokens to Figma by selecting the card below to learn more.

Export to Figma Guide

---

W3C DTCG Token Format

typography is an official token type in the W3C Design Token Community Group specifications.(9.7 Typography )

However, Tokens Studio has approached Typography Tokens differently than how it is defined in the current spec draft. We support:

• Additional text properties not defined in the spec.

• Dedicated Token Types for each text property.

We've made these adjustments in the plugin to align with Figma's unique approach to Typography.

---

Transforming Tokens

Engineers typically transform Tokens used in code with Style Dictionary, which is tool-agnostic. Tokens coming from Tokens Studio require an additional step: @Tokens-studio/sd-transforms, an npm package that prepares Tokens for Style Dictionary.

When transforming Typography Tokens, which are a Composite Token with several adaptations to accommodate Figma's unique approach to Text Styling, there are specific configurations to be aware of.

Composite Tokens require the SD-Transforms option to expand composite Tokens into multiple Tokens.

Make sure you look at the generic SD-Transforms package to include this option, which allows you to further customize this transformation further using Style Dictionary.

→ SD-Transforms Read-Me Doc, Using Expand

"object, object" When you transform your Typography Tokens and they show "object, object", it means your SD-Transforms configuration needs to be adjusted to include "expand".

If you are working in Android Compose, there is an optional transform to convert typography objects into Android Compose shorthand (platform option).

→ SD-Transforms Read Me Doc, ts/typography/compose/shorthand

Each property defined within the Typography Token has individual SD-Transform configurations to be aware of, which can all be found on the Read Me page on Github.

---

Resources

Mentioned in this doc:

• SD-Transforms - Read Me
• Style Dictionary - https://styledictionary.com/
• Design Tokens Community Group - W3C Draft
• Design Tokens Community Group - 9.7 Typography

Figma resources:

• Design in Figma - Explore Text Properties

CSS resources:

• MDN Web Docs - Text Styling Fundamentals

Community resources:

• Nate Baldwin's Typography + Dimension scale tool - Proportio.app
• Import Typography Styles from Figma into Tokens Studio - Video Tutorial by Sam I am Designs
• Marco Krenn's Fluid Typescale Generator + Design Token Integration

  • Office hours demo of the tool and process (2023)

💡 Something to share? Submit it here!

Known issues and bugs

Tokens Studio Plugin GitHub - Open issues for Token Type Typography Composite

🐞 If you are experiencing an issue not listed here, please reach out to us on the Troubleshooting channel of our community Slack, submit it on our feedback tool, or send us an email [e-mail]

Requests, roadmap and changelog

• Enhanced Typography Support - Feature Request
• Expand Token Types - Feature Request
• Support Multiple Token Types per Layer - Feature Request

💌 Visit https://feedback.tokens.studio/ to contribute or subscribe to updates.