Skip to content

cyberuni/color-map

v2.2.0MIT

Generate WCAG-checked color palettes, scales and design tokens with the color-map CLI

GitHubOpen Website

color-map

NPM version NPM downloads

Github NodeJS Codecov

Semantic Release

Visual Studio Code

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.

CommandWhat it does
convert <color> --to <space>convert to any CSS color space, optionally gamut-mapped
mix <a> <b>mix as color-mix() does
contrast <fg> <bg>WCAG 2 ratio with AA and AAA verdicts
find-contrast <bg> --target 4.5find a color that reaches a ratio
scale <seed>a Tailwind, Radix, tone or even scale, a brand scale, or a contrast scale
palette <brand>a semantic palette; every text pair carries its ratio
harmony <color>complementary, split, analogous, triadic or tetradic colors
export [color]CSS variables, DTCG JSON or a Tailwind v4 theme
schema [command]the JSON Schema of a command's options

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.

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.