Token Types
Paragraph Indent

Paragraph Indent as a Dimension Token

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

Paragraph Indent is not a dedicated Token type in Tokens Studio. We use a Dimension Token for this property.

Design decisions defined by Paragraph Indent Tokens

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

In CSS, this property is called text-indent.

Paragraph Indent decisions enhance the legibility of compact text elements, like a magazine article appearing as a column on the side of a page design. In Tokens Studio, we use a Dimension Token to define Paragraph Indent.

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

  • Default value - 0
    • No additional space is added.
    • All words would be aligned tight to the left side of the text container.
  • Relative to Font Size - value in rem units
    • Example: Paragraph Indent at 0.5rem with Font Size at 1rem
      • A person who has increased the font size of a mobile phone will see the space before the first word of each paragraph half the size of the text.
  • Fixed - value in pixels
    • Example 8px
      • The space before the first word in the paragraph will remain the same as a user zooms into a webpage.

Possible values

Like all Tokens defining a dimension design decision, the value of a Dimension Token for Paragraph Indent 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 Dimension Token for Paragraph Indent 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.

rem units (rem)

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

  • For example, a Paragraph Indent 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 Indent Token in ** pixel units**, for example:

32px

Units not supported by Figma

Em units are commonly used in CSS for Paragraph Indent properties but they are not supported in Figma.

You can still create Paragraph Indent Tokens with these units using the Tokens Studio plugin.

When you apply them to design elements in Figma, the Token will be present and visible to engineers inspecting the design element in Figma, but the Token won't interact with the Text Indent property in Figma's UI.

Values that reference another Token

When trying to reference another Token as the Value for a Dimension Token for Paragraph Indent, 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 = 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 Indent is not yet an official Token type in the W3C Design Token Community Group specifications.

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

Token Type syntax

The Paragraph Indent Token has a unique syntax in code which identifies if the Token is:

  • An independent property Token
  • Part of a Typography Composite Token

Looking at the JSON format, the "type" is "dimensions" when the Font Size Token is defined as an independent property Token.

This example shows a Dimension Token named paragraphIndent-none with the value in pixels.

{
 "paragraphIndent-none": {
  "value": "0px",
  "type": "dimension"
 }
}

This is in contrast to the Typography Composite Token, which has the property Token "type" written as"paragraphIndent".

This example shows a Typography Composite Token with the Paragraph Indent property Token named paragraphIndednt-none referenced as the value.

{
 "paragraph-3": {
  "value": {
   "fontFamily": "{font-family-sans}",
   "fontWeight": "{font-weight-default}",
   "lineHeight": "{line-height-classic}",
   "fontSize": "{font-size-small}",
   "letterSpacing": "{letter-spacing-tight}",
   "paragraphSpacing": "{paragraphSpacing-none}"
   "paragraphIndent": "{paragraphIndent.none}"
   "textCase": "{textCase.none}",
   "textDecoration": "{textDecoration.none}"
  },
  "type": "typography"
 }
}

This difference in syntax for the Paragraph Indent Token is less than ideal as it doesn't match the DTCG definition for this property, which is intended to be dimension. If your Design Tokens are being used in code, we have included a transformation to correct this inconsistency, described below.

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 Indent Tokens as a part of a Typography Composite Token, there are specific transforms to be aware of.

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

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

Paragraph Indent, 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 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".

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 Paragraph Indent

  • 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.](https://feedback. Tokens.studio/ )

Requests, roadmap and changelog

  • None

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

Last updated on September 9, 2024
Line Height
Paragraph Spacing