Skip to content

Simple Tokens

Simple tokens let you define design tokens directly in hyva.config.json without needing a design tool like Figma or Penpot.

The structure mirrors a Tailwind CSS theme config - plain key/value pairs without the $value/$type wrapper that W3C design token files normally require.

Defining Simple Tokens in hyva.config.json

Add your token values under the values key inside the tokens section of hyva.config.json:

tailwind/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)"
        }
      },
      "spacing": {
        "xs": "0.5rem",
        "sm": "0.75rem",
        "md": "1rem",
        "lg": "1.5rem",
        "xl": "2rem"
      }
    }
  }
}

Run npx hyva-tokens and the key paths become CSS custom properties:

@theme {
  --color-primary-lighter: oklch(62.3% 0.214 259.815);
  --color-primary: oklch(54.6% 0.245 262.881);
  --color-primary-darker: oklch(37.9% 0.146 265.522);
  --color-secondary-lighter: oklch(72.3% 0.219 149.579);
  --color-secondary: oklch(52.7% 0.154 150.069);
  --color-secondary-darker: oklch(39.3% 0.095 152.535);
  --spacing-xs: 0.5rem;
  --spacing-sm: 0.75rem;
  --spacing-md: 1rem;
  --spacing-lg: 1.5rem;
  --spacing-xl: 2rem;
}

Dark Mode with Simple Tokens

The simple token values format supports dark mode inline using the @media:dark- key prefix. This lets you define both light and dark values in the same file - no separate dark mode token file needed.

tailwind/hyva.config.json
{
  "tokens": {
    "values": {
      "color": {
        "background": "#ffffff",
        "@media:dark-background": "#1a202c",
        "text": "#1a202c",
        "@media:dark-text": "#f7fafc"
      },
      "shadow": {
        "color": "gray",
        "@media:dark-color": "hsl(220 40% 2%)",
        "weight": "1%",
        "@media:dark-weight": "25%"
      }
    }
  }
}

The @media:dark- prefix generates a prefers-color-scheme: dark media query:

@theme {
  --color-background: #ffffff;
  --color-text: #1a202c;
  --shadow-color: gray;
  --shadow-weight: 1%;
}

@media (prefers-color-scheme: dark) {
  @theme {
    --color-background: #1a202c;
    --color-text: #f7fafc;
    --shadow-color: hsl(220 40% 2%);
    --shadow-weight: 25%;
  }
}

To use a CSS class for dark mode instead of the media query (e.g. a .dark class on <html>), set the mediaDark option in your config:

tailwind/hyva.config.json
{
  "tokens": {
    "mediaDark": ".dark",
    "values": { }
  }
}

See the hyva-tokens configuration reference for full details on dark mode support.

Sharing Simple Token Values with Tailwind v2 and v3

Because the values structure mirrors a Tailwind theme object, you can import hyva.config.json directly into tailwind.config.js. This gives you one source of truth for both your CSS custom properties and your Tailwind utility classes:

tailwind.config.js
const hyvaConfig = require('./hyva.config.json');

module.exports = {
    theme: {
        extend: {
            colors: hyvaConfig.tokens.values.color,
            spacing: hyvaConfig.tokens.values.spacing,
        },
    },
};