Token Types
Paragraph Spacing

Paragraph Spacing Token

Paragraph Spacing is not intended to be applied to text elements directly but as a part of a Typography Composite Token.

Design decisions defined by Paragraph Spacing Tokens

Paragraph Spacing defines the vertical distance between 2 paragraphs of text.

This isn't a typical CSS property; you could define it by adding a margin to your paragraphs

✦

This property does not appear in Dev Mode
While you can apply the Token using the plugin to change Figma's Paragraph Spacing property, this value does not have a CSS equivalent property so it does not show up in Dev Mode when inspecting CSS.

The token applied will show up when inspecting Tokens Studio in Dev Mode.

→ Read the Dev Mode guide for more details

When we apply a Typography Composite Token to a text layer in Figma, these Paragraph Spacing values will change the text layer:

  • Preferred value - 0
    • No additional space between paragraphs.
    • A line break would be added to create the space needed instead.
      • This most closely matches how spacing between paragraphs would be done in code.
  • Relative to Font Size - value in rem units
    • Example: Paragraph Spacing at 0.5rem with Font Size at 1rem
      • A person who has increased the font size of a mobile phone will see the space between paragraphs half the size of the text.
  • Fixed - value in pixels
    • Example 8px
      • The space between paragraphs will remain the same as a user zooms into a webpage.

Paragraph Spacing Tokens can be attached to Number Variables in Figma.

→ Jump to the Export to Figma overview for more details on Paragraph Spacing Tokens as Variables

Possible values

Like all Tokens defining a dimension design decision, the value of a Paragraph Spacing Token must include a numeric value and, ideally, a unit of measure.

Tokens without a unit specified are applied as the pixel equivalent in Figma.

Hard-coded values

When writing the hard-coded values for a Paragraph Spacing Token, you'll want to:

  • Avoid spaces
  • Include a number and unit of measure.
    • Values without a unit will be translated to pixels in Figma.
    • The value should always be greater than 0.
  • Or use the specified string (below) for the normal value.

rem units (rem)

To support responsive design, you can define your Paragraph Spacing Token in rem units, and the plugin automatically converts the value to the pixel equivalent.

  • For example, a Paragraph Spacing Token with a value of 1rem, when applied as a **Typography Composite Token, will appear as 16px in Figma.

Rem Units act as a multiplier of the base font size, so when a user changes their preferences to a larger font size or uses a zoom feature in your product, elements defined in rem units will respond accordingly.

The value of 1rem can be configured in the plugin Settings for Base Font Size.

→ Read the guide on Base Font Size in the plugin

pixels (px)

If your design requires a fixed value, you can define your Paragraph Spacing Token in pixel units, for example:

32px

Values that reference another Token

When trying to reference another Token as the Value for a Paragraph Spacing 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:
    • The same = paragraphSpacing
    • dimension
    • number

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

W3C DTCG Token Format

Paragraph Spacing is not an official token type in the W3C Design Token Community Group specifications.

Tokens Studio has added Paragraph Spacing as a token type to support Figma's unique approach to this text property.

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 Paragraph Spacing Tokens, there are specific configurations to be aware of.

The preprocessor in the SD-Transforms package will automatically convert the Tokens Studio specific Token Type of paragraphSpacing to align with the DTCG Format Token Type of dimension.

→ SD-Transforms Read-Me Doc, Using the preprocessor

Paragraph Spacing, as part of Typography Composite Tokens, requires 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

Resources

Mentioned in this doc:

Figma resources:

CSS resources:

Community resources:

  • None yet!

💡 Something to share? Submit it here!

Known issues and bugs

Tokens Studio Plugin GitHub - Open issues for Token Type Paragraph Spacing

  • None yet

🐞 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

  • None

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

Last updated on September 9, 2024
Paragraph Indent
Text Case