Skip to content
helix-ui

CSS-variable IntelliSense

var(--helix-ui-color-bg-action-brand-default) is 44 characters. You don’t want to remember it. There are three ways to get autocomplete without memorizing the prefix.

1. Typed helper — t() / cssVar()

The shortest path. Import from @helix-ui/tokens:

import { t } from '@helix-ui/tokens';


<div
  style={{
    color: t('color.text.action.brand'),
    background: t('color.bg.surface.subtle'),
    padding: t('space.4'),
  }}
/>;

t() is a typed alias for cssVar(). The argument is a TokenPath union — every helix-ui token, autocompleted. The return is a HelixUICssVar string (var(--helix-ui-color-text-action-brand)), not a generic string, so you get end-to-end type safety.

If you’d rather use the long form: cssVar('color.text.action.brand') is identical.

2. String literal types

If you write inline CSS strings instead of helper calls, you can still get type safety:

import type { HelixUICssVar } from '@helix-ui/tokens';


const accentBg: HelixUICssVar = 'var(--helix-ui-color-bg-action-brand-default)';
// Typo? TypeScript fails the build.

HelixUICssVar is the union of every var(--helix-ui-*) string helix-ui ships. Useful for component prop types that should accept “any helix-ui color” without leaking the raw string:

interface MyBadgeProps {
  accent?: HelixUICssVar;
}

3. Editor autocomplete inside CSS files

For .css files where you can’t import TypeScript types, helix-ui ships a plain-text list of every CSS variable at @helix-ui/tokens/css-vars.txt. Most editors have an extension that reads from this.

VS Code

Install CSS Variables Autocomplete and add to your project’s .vscode/settings.json:

{
  "cssVariables.lookupFiles": ["node_modules/@helix-ui/tokens/dist/css/all.css"]
}

Now typing var(--he… inside any .css / .tsx / .module.css file pops up the full list with colour previews for color tokens.

JetBrains (WebStorm, etc.)

The built-in CSS Modules support detects var(--helix-ui-*) from the imported stylesheet automatically. Make sure your project includes the helix-ui CSS in a <link> or @import so JetBrains’ index picks it up.

Other editors

The list is at node_modules/@helix-ui/tokens/dist/css-vars.txt (one variable per line) and dist/css-vars.json (array). Most editor extensions support one or the other.

4. Build-time validation (optional)

A typo in var(--helix-ui-color-brnad-500) won’t fail TypeScript — it’s still a valid CSS string. To catch these at build time, install the first-party stylelint plugin:

Terminal window
pnpm add -D stylelint @helix-ui/stylelint-plugin
{
  "plugins": ["@helix-ui/stylelint-plugin"],
  "rules": {
    "helix-ui/known-var": [true],
    "helix-ui/no-color-hex": [true],
    "helix-ui/no-pixel-space": [true]
  }
}

The rules validate var(--helix-ui-*) references against the installed token manifest, reject raw hex colors in authored CSS, and reject bare pixel values in spacing declarations (margin, padding, and gap families).

Why we don’t augment CSSProperties directly

We considered ambient-augmenting React’s CSSProperties so every color, background, padding etc. would autocomplete helix-ui variables out of the box. We decided against it because:

  • It interferes with users who legitimately use other CSS variable systems (Tailwind, Open Props).
  • It locks you into our type universe, which violates the spirit of “tokens are JSON, code is downstream” — you should be able to opt in or out.

The opt-in pattern (t(), HelixUICssVar) is more invasive only in the places you choose, with the same type safety.