Token Types
Typography (composite)

Typography Token

We style text elements by composing many typography-related design decisions together.

Typography is considered a Composite Token.

In our guides, each design decision (font size, letter spacing, etc.) that is part of the Composite Token is referred to as a property of the Typography Token.

Design decisions defined by Typography Tokens

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.

  • Individual Tokens can be created to define each independent styling property and combined to create the Typography Composite Token.

Tokens Studio supports these text and font styling design decisions to be combined 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. Tokens Studio also supports Styles with Variable References.

→ Jump to the Export to Figma Overview for more details

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 in the Composition Token Value 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.

The independent Token Type of each property within the Typography Composite Token has unique specifications. Select the Token Type below to get more details.

Using Math

Each property defined within the Typography Token that requires numeric values supports accepting math equations.

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

Values that reference another Token

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).

When trying to reference another Token as the Value for a Typography Token, you will see

  • Tokens 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.

✦

The value will show a broken reference until the originating token set is marked as enabled.

→ Jump to the Token Values with References guide for more details

Limitations of Typography Tokens

When working with Typography Tokens, there are a few known limitations to 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.

Text Styles with Variable references

Typography Tokens can be Exported to Figma as Text Styles that reference Text Properties as Variables.

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.

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.

→ Read the Export to Figma Styles with Variable References for more details and troubleshooting tips.

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 the preprocessor → 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:

Figma resources:

Typography resources:

CSS resources:

Community resources:

💡 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, or submit it on our feedback tool.

Requests, roadmap and changelog

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

Last updated on September 9, 2024
Text
Font Family