Oombla DocsMenuoombla.com

Tailwind CSS

Export design tokens for Tailwind

Design tokens for the TailwindCSS platform are exported as JavaScript files that can be added to Tailwind’s main config file tailwind.config.js without any modification.

// tailwind.config.js

module.exports = {
  content: [
    "path/to/source/files",
  ],
  darkMode: "class",
  theme: {
    ...require("./src/tokens/colors.js"),
    ...require("./src/tokens/spacing.js"),
    ...require("./src/tokens/typography.js"),
  },
  plugins: [
    require("./src/tokens/typographyStyles.js")
  ],
}

The above example is how you could integrate the exported design tokens into a Tailwind project. For a full implementation example, view the TailwindCSS example project on GitHub.

Colors

The colors are exported into a file named colors.js and are contained in a single, hierarchal object. The top-level property is named colors to match Tailwind’s convention and the colors are all contained as subproperties of this main property.

The hierarchy of the color object matches the hierarchy in Figma. So for example if the color style in Figma is Light / Blue / 500 then the corresponding token when exported for Tailwind will be structured like so:

module.exports = {
  colors: {
    light: {
      blue: {
        '500': '#2c75ff',
      },
    },
  },
}

And then the corresponding classnames would be converted to kebab-case to reflect heirarchy:

<!-- example classname reference -->
<span class="text-light-blue-500">Blue text</span>

And dot notation when referencing them within the theme function:

/* theme() reference */
.example { color: theme("colors.light.blue.500") }

Spacing

The spacing tokens follow the same structure as the color tokens. The top-level object property is spacing and all the spacing tokens are contained as subproperties:

module.exports = {
  spacing: {
    '1': '0.25rem',
    '2': '0.5rem',
  },
}

And the corresponding classnames would reference these properties:

<!-- example classname reference -->
<p class="mt-2">Top margin added</p>

As would the theme references:

/* theme() reference */
.example { margin-top: theme("spacing.2") }

Typography

The typography tokens file is a collection of type-related style properties

There is no single, top-level object property for the typography tokens, rather there are eight groups of type-related styles. The property names follow the CSS-in-JS syntax of camel-cased names that match the corresponding CSS property:

  • fontFamily
  • fontSize
  • fontStyle
  • fontWeight
  • letterSpacing
  • lineHeight
  • textDecoration
  • textTransform

Within each group, the subproperties are named according to the text style in Figma and the value is the corresponding CSS style value (every text style has one entry in each group).

module.exports = {
  fontFamily: {
    'body-1': 'IBMPlexSans-Web',
  },
  fontSize: {
    'body-1': [
      '1.0625rem',
      '1.625rem',
    ],
  },
  fontStyle: {
    'body-1': 'normal',
  },
  fontWeight: {
    'body-1': 400,
  },
  letterSpacing: {
    'body-1': 0,
  },
  lineHeight: {
    'body-1': '1.625rem',
  },
  textDecoration: {
    'body-1': 'none',
  },
  textTransform: {
    'body-1': 'none',
  },
}

Each group’s subproperty’s value is the equivalent of its correpsonding CSS value with the exception of the fontSize group. The values for the fontSize typography tokens follow Tailwind’s unique syntax in which a default line-height is also specified along with the font-size. Tailwind does this so that a font-size can be specified in the classlist without requiring the matching line-height classname.

So using the body-1 font-size token in the code sample directly above, if the classname text-body-1 was added to an element, that element’s rendered style would include the font-size and line-height:

<span class="text-body-1">Body 1 text</span>

<!-- above is equivalent to: -->
<span class="text-body-1 leading-body-1">Body 1 text</span>

(Note that in the config file where the typography tokens are specified, line-height values are passed via lineHeight, but in the class name convention they are specified with leading. This occurs for other properties as well.)

Typography Styles

The typographyStyles file assigns all of the typography tokens to their respective text style and creates a single classname that can be used to specify the full text style. The classnames are converted from the Figma style name to kebab-case. So if the text style name was Body 1 the resultant classname would be body-1.

The styles are added to Tailwind using the addComponents() helper function:

const plugin = require("tailwindcss/plugin");

module.exports = plugin(function({ addComponents, theme }) {
  addComponents({
    ".body-1": {
      fontFamily: theme("fontFamily.body-1"),
      fontSize: theme("fontSize.body-1"),
      fontStyle: theme("fontStyle.body-1"),
      fontWeight: theme("fontWeight.body-1"),
      lineHeight: theme("lineHeight.body-1"),
      letterSpacing: theme("letterSpacing.body-1"),
      textTransform: theme("textTransform.body-1"),
      textDecoration: theme("textDecoration.body-1"),
    },
  });
});

(Read more about Tailwind plugins.)

Once the plugin has been added to the Tailwind config (see code sample at the top of the page) a style name class can be used to specify the full text style:

<p class="body-1">Body text</p>

<!-- above is equivalent to: -->

<p class="
  font-body-1
  text-body-1
  font-body-1
  leading-body-1
  tracking-body-1
  transform-body-1
  not-italic
  no-underline
">Body text</p>

Note the data-type helpers for the clashing classname font-body-1. Though in this scenario, TailwindCSS would resolve the duplicate classname

Note that TailwindCSS knows how to resolve the duplicate classname font-body-1 to the font-family name and font weight for the Body 1 style (though you can specify a CSS data-type as a helper). Also note that TailwindCSS has reserved keyword names for font-style and text-decoration so there is no font-style or text-decoration equivalent using the body-1 keyword.

Sample repository

Go to the TailwindCSS platform sample repository to view a working demo of the design tokens exported for the TailwindCSS platform.