Skip to content

The hyva-tokens command

The hyva-tokens command 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.

Design tokens are essentially key-value pairs that store design-related information, such as colors, spacing, and typography.
A similar concept was used in earlier JS based 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 script, use the following command:

npx hyva-tokens

This 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 different, you need to also set the format key to the value figma.

Figma Token Format Requirements

The Figma token converter performs a direct key-to-CSS-variable-name mapping. It cannot strip wrapper keys or resolve token references at conversion time.

Wrapper Keys

If your Figma token file uses wrapper structures, those wrapper names become part of the CSS variable name.

For example, this token structure:

{
  "global": {
    "Extended": {
      "white": {
        "value": "#ffffff",
        "type": "color"
      },
      "slate": {
        "50": {
          "value": "#f8fafc",
          "type": "color"
        }
      }
    }
  }
}

Generates CSS variables like:

--global-Extended-white: #ffffff;
--global-Extended-slate-50: #f8fafc;

If you want cleaner variable names like --white or --slate-50, you need to restructure your token file to remove the wrapper keys.

Unresolved Token References

The converter does not resolve references between tokens. If your tokens contain references like {fontFamilies.standard} or $textDecoration.none, these will appear literally in the generated CSS rather than being replaced with actual values.

For example, typography tokens that reference other tokens:

{
  "text-heading": {
    "font-family": {
      "value": "{fontFamilies.standard}",
      "type": "fontFamilies"
    }
  }
}

Will generate:

--text-heading-font-family: {fontFamilies.standard};

To avoid this, ensure your token values contain the actual values rather than references to other tokens.

Example Token Files

For reference implementations of properly structured Figma token files, see:

These examples demonstrate the expected flat key structure without wrapper groups.

Future Improvements

The token converter is actively being improved to handle more complex Figma token structures. For updates or to provide feedback, see the hyva-modules-tailwind-js repository or the underlying @fylgja/props-builder.

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 are ignored, and a warning is 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.