@designtools/tokens

Colour token generation from brand colours, as pure TypeScript. generateTokens({ primary, neutral }) produces a TokenSystem — twelve-step OKLCH scales, contrast-checked semantic intents, surfaces, utilities, in light and dark — and exportTokens(tokens, format) serialises it, with CSS custom properties as the lead format and Tailwind v3/v4, DTCG, and Lovable as secondary outputs. No browser, DOM, or React.

Part of the @designtools/* suite; the designtools-tokens skill (in skills/) drives it at scaffold time.

Usage

Published, the CLI is generate-tokens:

npx @designtools/tokens --primary "#4e9caf"                          # CSS custom properties to stdout
npx @designtools/tokens --primary "#4e9caf" --vanilla --out tokens.css
npx @designtools/tokens --primary "#4e9caf" --format all --out ./tokens

From source in this monorepo (no build needed):

npx tsx packages/tokens/src/cli.ts --primary "#4e9caf"

Programmatic:

import { generateTokens, exportTokens } from "@designtools/tokens";

const tokens = generateTokens({ primary: "#4e9caf", neutral: "#9aa1af" });
const css = exportTokens(tokens, "css", { colorFormat: "oklch" });

Pass --vanilla (or compat: false) to omit the shadcn/ui aliases from the css and tailwind-v4 outputs — the right default for Base UI / vanilla-CSS stacks. Full input/output contracts, options, and export formats live in skills/designtools-tokens/SKILL.md.

Layout

src/     types, oklch, primitives, semantic, generate, export, index (barrel), cli
test/    parity tests, fixture cases, golden fixtures, fixture regenerator

Runtime dependencies: culori (colour maths) and apca-w3 (APCA contrast), both pure JS. Built with tsup to ESM plus a compiled generate-tokens bin; dist/ is produced at build/publish time and is not committed.

Commands

npm -w packages/tokens run build        # tsup -> dist (ESM + generate-tokens bin + .d.ts)
npm -w packages/tokens run typecheck
npm -w packages/tokens run cli -- --primary "#4e9caf"
npm -w packages/tokens run fixtures     # regenerate goldens — only when a behaviour change is intended
npm test                                # parity tests run in the repo's vitest suite

Determinism and parity

Same seeds and options always produce byte-identical output — pure arithmetic, no randomness, clocks, or environment reads. test/ pins that: the generator must reproduce the golden fixtures in test/fixtures/, which were generated from the original Colour Token Generator web-tool source. Regenerate them (run fixtures) only when a behaviour change is intended.

src/ (except index.ts and cli.ts) is a verbatim copy of that web tool's library, so the two stay in step; src/export.ts is the one deliberate exception, carrying the compat toggle behind --vanilla, with its own fixtures. This package is the canonical source.