The hyva-tokens command

The hyva-tokens command generates a CSS file from design tokens, enabling direct use of design values (e.g., from Figma) in your theme.

Design tokens are key-value pairs for design information (colors, spacing, typography). This concept was also used in older JS-based TailwindCSS configs. For details, see our FAQ on design tokens.

How It Works

While Tailwind v2/v3 allows direct JSON import into tailwind.config.js, mapping can be complex. hyva-tokens simplifies this by converting design tokens directly into CSS custom properties (variables). This approach is inspired by tools like @fylgja/props-builder and Style Dictionary.

Run the script:

npx hyva-tokens

This reads your design tokens file and generates `generated/hyva-tokens.css` in your theme.

Configuration

By default, hyva-tokens uses tailwind/design.tokens.json. Customize this and other options in hyva.config.json at your Tailwind directory's root.

Specifying a Source File

To use a different token file (e.g., from Figma), specify it with the src key in `hyva.config.json`:

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

For Figma tokens, also set format to figma.

Figma Token Format Requirements

The Figma converter directly maps keys to CSS variable names. It does not strip wrapper keys or resolve token references during conversion.

Wrapper Keys

Figma token wrapper structures 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;

For cleaner variable names (e.g., --white, --slate-50), restructure your token file to remove wrapper keys.

Unresolved Token References

The converter does not resolve token references. References like {fontFamilies.standard} or $textDecoration.none will appear literally in the generated CSS.

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 prevent this, ensure token values are actual values, not references.

Example Token Files

See these examples for properly structured Figma token files:

• Fylgja CSS Tokens - A well-structured example (remove spacing for Tailwind compatibility)
• Open Props Figma Tokens - Another example

These show the expected flat key structure without wrapper groups.

Defining Tokens Manually

To define tokens manually, use the values key directly in `hyva.config.json`:

{
    "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 structure is similar to a TailwindCSS configuration.

A key advantage: hyva.config.json can be imported into tailwind.config.js. This centralizes CSS variable and Tailwind class definitions, useful for Tailwind v2/v3 projects.

Usage with Tailwind v2 and v3

By default, hyva-tokens generates CSS for Tailwind v4 using @theme. For Tailwind v2/v3 compatibility, change the cssSelector to :root to make CSS variables globally available.

Set cssSelector in `hyva.config.json`:

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

You can now use the generated CSS with your Tailwind v2/v3 project.