Hyvä Tokens

hyva-tokens is a command-line tool that generates a CSS file from a design tokens file. This bridges the gap between design and development by allowing you to use values from design applications like Figma directly in your theme.

If you are unfamiliar with design tokens, they are essentially key-value pairs that store design-related information, such as colors, spacing, and typography. You have likely used a similar concept in your TailwindCSS configuration. For a more detailed explanation, please refer to our FAQ page on design tokens.

How It Works

While you can import a JSON file with design tokens directly into your tailwind.config.js file in Tailwind v2 and v3, mapping the values can be cumbersome. Instead, hyva-tokens focuses on the CSS output, converting your design tokens into CSS custom properties (variables). This approach is inspired by tools like @fylgja/props-builder and Style Dictionary.

To run the tool, use the following command:

npx hyva-tokens

This command will read a design tokens file and generate a generated/hyva-tokens.css file in your theme.

Configuration

By default, hyva-tokens looks for a file named design.tokens.json in your Tailwind directory. You can customize this and other options in a hyva.config.json file located in the root of your Tailwind directory.

Specifying a Source File

If you are using a different file name for your tokens (e.g., from Figma), you can specify it using the src key in your hyva.config.json file:

{
  "tokens": {
    "src": "hyva.figma-tokens.json",
    "format": "figma",
  }
}

Since the format of Figma is diffrent, you need to also pass the format key with the value figma.

Defining Tokens Manually

If you prefer to manage your tokens manually, you can define them directly in your hyva.config.json file using the values key:

{
    "tokens": {
        "values": {
            "color": {
                "primary": {
                    "lighter": "oklch(62.3% 0.214 259.815)",
                    "DEFAULT": "oklch(54.6% 0.245 262.881)",
                    "darker": "oklch(37.9% 0.146 265.522)"
                },
                "secondary": {
                    "lighter": "oklch(72.3% .219 149.579)",
                    "DEFAULT": "oklch(52.7% .154 150.069)",
                    "darker": "oklch(39.3% .095 152.535)"
                }
            }
        }
    }
}

This example uses a structure similar to a TailwindCSS configuration.

A significant advantage of this approach is that you can import hyva.config.json into your tailwind.config.js file. This allows you to define your CSS variables and Tailwind classes in a single location, which is especially useful for Tailwind v2 and v3 projects.

Warning

If you use the values option in combination with the src option, the values will be ignored, and a warning will be displayed.

Usage with Tailwind v2 and v3

By default, hyva-tokens generates CSS for Tailwind v4, using the @theme selector. For compatibility with Tailwind v2 and v3, you need to change the CSS selector to :root. This allows the CSS variables to be available globally.

To do this, set the cssSelector option in your hyva.config.json file:

{
  "tokens": {
    "cssSelector": ":root"
  }
}

Now you can use the generated CSS file with your Tailwind v2 or v3 project.