color-map

Color map generator with no dependency.

Inspired from colormap.

Library

import { parse, toCss, convert, semanticPalette, toTailwindTheme } from 'color-map'

toCss(convert(parse('#3b82f6'), 'oklch')) // oklch(0.62308 0.18801 259.81453)
toTailwindTheme(semanticPalette({ brand: '#3b82f6', mode: 'light' })) // an @theme { ... } block

color-map re-exports the subpaths color-map/color, color-map/scale, color-map/palette and color-map/tokens. With a bundler, the root costs the same bytes as a subpath. Code that runs without a bundler can import a subpath to load less. See the library docs for the full API.

Legacy API

The original API lives in color-map/legacy. The root color-map still exports it in 2.x, marked deprecated, and stops in 3.0.

createColors(from, to, shades, alpha?)

import { createColors } from 'color-map/legacy'

// creates array of [r,g,b,a]
const rgbaRange = createColors([0, 0, 255], [0, 255, 128], 72, [0, 1])

// creates array of [r,g,b,1]
const rgbRange = createColors([0, 0, 255], [0, 255, 128], 72)

rgbHex(rgb)

import { rgbHex } from 'color-map/legacy'

rgbHex([0, 128, 255]) // '#0080ff'
rgbHex([0, 128, 255, 0.3]) // '#0080ff'

rgbaString(rgba)

import { rgbaString } from 'color-map/legacy'

rgbaString([0, 128, 255, 0.2]) // 'rgba(0,128,255,0.2)`

createColorsFromMap(colormap, shades, alpha?)

import { createColorsFromMap, ColorMap } from 'color-map/legacy'

const summer: ColorMap = [{ index: 0, rgb: [0,128,102] }, { index: 1, rgb: [255,255,102] }]

const colors = createColorsFromMap(summer, 60)

createColorsFromMap is deprecated. Use createGradient instead:

import { createGradient } from 'color-map'

const colors = createGradient(['rgb(0 128 102)', 'rgb(255 255 102)'], 60, { in: 'srgb' })

It returns color objects with channels from 0 to 1, not whole numbers. See Gradients for the full recipe.

The color-map command

The package ships a command for agents, with no extra install and no runtime dependency:

npx color-map palette '#3b82f6'

Output is TOON by default, with --format json for JSON. It follows the AXI principles: essential fields by default and --full for the rest, precomputed contrast ratios, explicit empty results, coded errors with exit codes (1 failed, 2 wrong call), no prompts, and a suggested next command after each result.

Contrast is WCAG 2.

For agents

• JSON Schemas for every command's arguments and options ship in schemas/ (for example color-map/schemas/scale.schema.json) and print with color-map schema <command>.
• The color-map agent skill ships in this package as a plugin for Claude Code, Cursor, Codex and Copilot CLI (plugin.json, skills/color-map).
• llms.txt maps the commands.

The command is a separate bundle (bin/color-map.js) that inlines its parser. No library entry point loads it, so importing color-map costs nothing for it.

Acknowledgements

color-map follows CSS Color 4 and 5 (W3C), uses Björn Ottosson's OKLab, and writes Design Tokens color values. Its scales and palettes learn from Radix Colors, Material Design 3 and Tailwind CSS. It started from colormap. The Compare page measures it against culori, Color.js, chroma-js, @texel/color, @colordx/core, lightningcss and colord. No third-party source code is bundled. The Credits page says what each one contributed and under which license.

Contribute

# after fork and clone
npm install

# begin making changes
git checkout -b <branch>
npm run watch

# after making change(s)
git commit -m "<commit message>"
git push

# create PR

npm run size checks the gzip size of each entry point against its budget. npm run build && npm run bench times the same operations in color-map, culori and colorjs.io and prints ops/sec for each; --filter <name> runs only the matching operations.