Handling dynamic opacity in token aliases/references and Tailwind CSS

[kaelig]

This post aims to guide you through the steps to extend your design tokens to handle RGB colors and dynamic opacity seamlessly.

Problem Statement

1. Your color tokens are in HEX format.
2. You want to use them in Tailwind CSS, which requires RGB format for its color opacity modifier syntax (example: class="text-red/30").
3. You also want to handle opacity in token references.

Assumptions

• You're already using Style Dictionary for managing design tokens.
• You're familiar with Tailwind CSS and its color opacity modifier syntax.

Step 1: Define Your Color Tokens in HEX

Here's an example of what your color tokens might look like:

// colors.js
const color = {
  base:
    teal: {
      900: { value: '#0c2a2a' },
      500: { value: '#04a29f' },
      100: { value: '#8efbf7' }
    }
  }
};

module.exports = { color }

We need to convert HEX colors to RGB. To do this, we'll go through the entire color palette and populate RGB equivalents next to HEX values using tinycolor2 and a custom JavaScript helper.

First, install the tinycolor2 package:

npm install -D tinycolor2

Then, before module.exports = { color }, add:

/**
 * Recursively traverses a nested color palette object to add RGB equivalents to its HEX values.
 * The function adds an "rgb" key next to each "value".
 *
 * @param {Object} obj - The nested color palette object.
 * @returns void - Transforms the object with the same structure as the input, but with added "rgb" key.
 *
 * @example
 * const palette = {
 *   red: {
 *     500: { value: '#FF5733' }
 *   }
 * };
 * addRGBRecursively(palette);
 * console.log(newPalette);
 *
 * Output will be:
 * {
 *   red: {
 *     500: { value: '#FF5733', rgb: '255 87 51' }
 *   }
 * }
 */
const addRGBRecursively = (obj) => {
  for (const key in obj) {
    if (key === 'value') {
      const hexColor = obj[key];
      const { r, g, b } = tinycolor2(hexColor).toRgb();
      obj.rgb = [r, g, b].join(' ');
    } else if (typeof obj[key] === 'object') {
      addRGBRecursively(obj[key]);
    }
  }
};

addRGBRecursively(colors);

Step 2: Using the tokens with Tailwind

We want to be able to write code like this:

<div class="bg-teal/30">This block has a teal background with 30% opacity</div>

Update your project's tailwind.config.js to refer to the RGB values:

const colors = require('path/to/colors.js');

module.exports = {
  // Add to existing config...
  theme: {
    colors: {
      teal: {
        light: 'rgb(var(--color-base-teal-100) / <alpha-value>)',
        DEFAULT: 'rgb(var(--color-base-teal-500) / <alpha-value>)',
        dark: 'rgb(var(--color-base-teal-900) / <alpha-value>)',
      },
    },
  },
};

Then, add the following transform to your Style Dictionary config:

const tinycolor2 = require('tinycolor2');

StyleDictionary.registerTransform({
  name: 'color/tailwind',
  type: 'value',
  // You may need to tweak this value
  matcher: (token) => token.attributes?.category === 'base',
  transformer(token) {
    return token.rgb;
  },
});

Incorporate this new transform into your Style Dictionary config like so:

// sd.config.js
module.exports = {
  platforms: {
    css: {
      transforms: [/* existing transforms, add: */, 'color/tailwind'],
      // ...existing settings...
    }
  }
};

And import the resulting file in your CSS.

Step 4: Handling Opacity in Token References

You can now refer to these RGB color tokens in other tokens and add opacity to them. Here's an example of how you can define a shadow effect token that uses the RGB color and also includes opacity:

module.exports = {
  effect: {
    shadow: {
      basic: {
        value:
          '0 1px 10px 0 rgb({color.base.teal.100.rgb} / 6%), 0 2px 4px 0 rgb({color.base.teal.500.rgb} / 8%)',
      },
    },
  },
};

Summary

By following these steps, you can make your Style Dictionary tokens more flexible, allowing you to use Tailwind CSS's dynamic opacity features effectively. Now you're ready to leverage the full power of design tokens along with dynamic opacity in your Tailwind projects. Happy coding! 🎉