@huekit/tokens

Turn brand colors into a complete, framework-neutral design token set. Zero dependencies. The data spine of huekit, the OKLCH toolkit for designers.

import { tokens } from '@huekit/tokens'

tokens({ brand: '#3b82f6', danger: '#ef4444' }, { precision: 3 })
// → :root {
//     --brand-50: oklch(0.971 0.013 259.815);
//     --brand-50-fg: #000000;
//     ...
//   }

tokens({ brand: '#3b82f6' }, { raw: true })
// → structured token model any formatter can consume

What this is for

Every design system starts the same way: someone hands you a brand hex, and you need a full scale, plus text colors that stay readable on every step, plus a way to get all of it into CSS.

@huekit/tokens does that in one call. Give it named colors, get back an 11-stop, sRGB-gamut-safe scale per color, a readable foreground for every stop, and the WCAG contrast ratio that proves it. Output as CSS custom properties, or as structured data.

It's framework neutral on purpose. The CSS variables work anywhere. The raw token model is the shape that adapters build on, so the same data can be formatted for Tailwind, Panda, Figma, or whatever comes next without regenerating anything.

Install

npm install @huekit/tokens

Requires Node.js 18 or newer. The package is ESM-only:

import { tokens } from '@huekit/tokens'

From CommonJS, use dynamic import('@huekit/tokens'); require() is not provided.

API

tokens(input, options?)

Input is a hex string, an OKLCH object, or an object of named colors:

tokens('#3b82f6')                                   // → --color-50 … --color-950
tokens({ l: 0.6, c: 0.19, h: 260 })                 // → same, from OKLCH
tokens({ brand: '#3b82f6', danger: '#ef4444' })     // → --brand-* and --danger-*

Returns a CSS string by default, or a TokenSet with { raw: true }.

| Option | Type | Default | Description | |--------|------|---------|-------------| | raw | boolean | false | Return the structured TokenSet instead of CSS | | precision | number | 4 | Decimal places in oklch() values | | stops | Record<string, number> | 11-stop ramp | Custom stop → lightness map | | prefix | string | '' | Prefix for CSS variables, e.g. 'hk-' → --hk-brand-500 | | foregrounds | boolean | true | Emit a -fg variable per stop | | chromaFit | 'fit' \| 'keep' | 'fit' | Fit chroma to sRGB per stop, or preserve the input chroma |

precision must be an integer from 0 to 12. Custom stop lightness values must be finite and are clamped to the 0…1 range. prefix and foregrounds affect CSS output only.

For CSS output, color names and non-empty prefixes must start with an ASCII letter or underscore; stop names may also start with a number. The remaining characters may be letters, numbers, underscores, or hyphens. Duplicate generated custom properties throw an error. Use { raw: true } if another formatter needs a different naming convention.

toCss(set, options?)

Formats an existing TokenSet as CSS. Useful when you've filtered or modified the model by hand.

const set = tokens({ brand: '#3b82f6' }, { raw: true })
delete set.colors.brand.stops['950']
toCss(set, { prefix: 'app-' })

toCss accepts only prefix and foregrounds. It serializes the supplied model as-is and does not recompute gamut fitting or contrast after manual edits.

The token model

With { raw: true, precision: 3 } you get a structure designed to be built on:

{
  colors: {
    brand: {
      name: 'brand',
      base: { l: 0.623, c: 0.188, h: 259.815 },
      stops: {
        '500': {
          stop: '500',
          value: 'oklch(0.602 0.188 259.815)',
          oklch: { l: 0.602, c: 0.188, h: 259.815 },
          foreground: '#000000',
          contrast: 5.24,
          inGamut: true
        },
        // … 10 more stops
      }
    }
  }
}

Every stop carries its CSS string, its raw components, a readable foreground, and the contrast ratio behind that choice. Nothing is hidden behind a formatter.

Gamut-safe scales

The input color's chroma is a ceiling, not a constant applied blindly to every lightness. For each stop, hue and target lightness stay fixed while chroma is reduced only as much as needed to fit inside sRGB.

For #3b82f6 at precision 3, the middle of the scale keeps the source chroma while the light and dark ends are fitted:

| Stop | Requested chroma | Emitted chroma | |------|------------------|-----------------| | 50 | 0.188 | 0.013 | | 400 | 0.188 | 0.155 | | 500 | 0.188 | 0.188 | | 600 | 0.188 | 0.188 | | 950 | 0.188 | 0.103 |

This avoids browser-dependent clipping at the ends of the ramp. Contrast is calculated from the exact emitted, continuous linear-sRGB color.

Set chromaFit: 'keep' when you intentionally want wider-gamut output. In that mode every stop preserves the rounded input chroma, and each stop's inGamut flag tells you whether that emitted value still fits sRGB. Foreground contrast uses the sRGB-clamped representation for out-of-gamut stops.

Readable foregrounds, automatically

For each stop, black and white are both measured against the background and the winner is kept. On a typical scale the foreground flips somewhere in the middle:

| Stop | Chroma | Foreground | Contrast | |------|--------|------------|----------| | 50 | 0.013 | #000000 | 19.32 | | 400 | 0.155 | #000000 | 7.90 | | 500 | 0.188 | #000000 | 5.24 | | 600 | 0.188 | #ffffff | 5.71 | | 950 | 0.103 | #ffffff | 15.89 |

Nothing in the generated scale drops below WCAG AA.

Using the output

/* paste the CSS straight in */
:root {
  --brand-500: oklch(0.602 0.188 259.815);
  --brand-500-fg: #000000;
}

.button {
  background: var(--brand-500);
  color: var(--brand-500-fg);
}

Or build your own formatter over the raw model:

const set = tokens({ brand: '#3b82f6' }, { raw: true })

const json = Object.fromEntries(
  Object.values(set.colors).flatMap(scale =>
    Object.values(scale.stops).map(s => [`${scale.name}-${s.stop}`, s.value])
  )
)

The huekit suite

| Package | What it does | |---------|--------------| | @huekit/hex | hex → oklch() conversion | | @huekit/scale | perceptual lightness scale from one color | | @huekit/contrast | WCAG & APCA contrast + readability helpers | | @huekit/mix | blend colors, no muddy midpoint | | @huekit/tokens ← you are here | the token model: scales, foregrounds, CSS variables | | @huekit/tailwind | Tailwind v4 @theme formatter over this model (soon) |

License

MIT