@voltr/token-derivation

Deterministic design-token derivation utilities for Voltr Token Studio.

Install

npm install @voltr/token-derivation

Usage

Color scale from a single seed

import { deriveColorScale } from '@voltr/token-derivation'

const palette = deriveColorScale('#2563eb')

console.log(palette)
// {
//   '50':  '#eff6ff',
//   '100': '#dbeafe',
//   ...
//   '500': '#2563eb',
//   ...
//   '900': '#1e3a8a',
// }

The seed defaults to tone 500. Pass anchorTone for a different anchor:

deriveColorScale('#dc2626', { anchorTone: 600 })

Full family with metadata

import { deriveColorFamily } from '@voltr/token-derivation'

const family = deriveColorFamily('#2563eb', existingFamily, {
  familyName: 'blue',
})

// family['500'].$value === '#2563eb'
// family.$extensions.voltr.derivation.formula === 'oklch-v1'

Spacing scale

import { deriveSpacingScale } from '@voltr/token-derivation'

const spacing = deriveSpacingScale(existingScale, { baseUnit: 4 })

// spacing['4'].$value === { value: 16, unit: 'px' }

Radius preset

import { deriveRadiusScale } from '@voltr/token-derivation'

const radius = deriveRadiusScale(existingScale)

// radius.md.$value === { value: 8, unit: 'px' }

API

| Export | Description | |--------|-------------| | deriveColorScale(seedHex, options?) | Returns { [tone]: hex } from a seed color | | deriveColorFamily(seedHex, existingFamily?, options?) | Returns a full token family object with $value leaves | | deriveSpacingScale(existingScale?, options?) | Returns a token group with derived dimension values | | deriveRadiusScale(existingScale?, options?) | Returns a token group with the default radius preset | | normalizeHexColor(hex) | Normalizes 3-digit and 6-digit hex with validation |

All functions are pure — no I/O, no side effects.

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | anchorTone | number | 500 | Which tone the seed represents | | toneProfile | object | TONE_PROFILE_V1 | Per-tone lightness and chroma mapping | | tones | string[] | STANDARD_COLOR_TONES | Which tone keys to emit | | baseUnit | number | 4 | Base pixel unit for spacing | | preset | object | DEFAULT_RADIUS_PRESET | Key-value radius map | | formulaVersion | string | 'oklch-v1' | Written into $extensions.voltr.derivation |

Formula

Colors are derived in OKLCH space for perceptual uniformity. The v1 profile maps 10 standard tones (50–900) from a single seed using fixed lightness offsets and chroma multipliers. Out-of-gamut colors are fitted to sRGB via binary search.

License

Private — Voltr Token Studio thesis project.