color-map 2.2.0 → 2.3.1

package/.claude-plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+	"name": "color-map",
+	"version": "2.3.1",
+	"description": "Generate WCAG-checked color palettes, scales and design tokens with the color-map CLI",
+	"author": {
+		"name": "Homa Wong (unional)"
+	},
+	"homepage": "https://github.com/cyberuni/color-map",
+	"repository": "https://github.com/cyberuni/color-map",
+	"license": "MIT",
+	"keywords": ["color", "palette", "design-system", "contrast", "css"]
+}

package/.codex-plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+	"name": "color-map",
+	"version": "2.3.1",
+	"description": "Generate WCAG-checked color palettes, scales and design tokens with the color-map CLI",
+	"author": {
+		"name": "Homa Wong (unional)"
+	},
+	"homepage": "https://github.com/cyberuni/color-map",
+	"repository": "https://github.com/cyberuni/color-map",
+	"license": "MIT",
+	"keywords": ["color", "palette", "design-system", "contrast", "css"]
+}

package/.cursor-plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+	"name": "color-map",
+	"version": "2.3.1",
+	"description": "Generate WCAG-checked color palettes, scales and design tokens with the color-map CLI",
+	"author": {
+		"name": "Homa Wong (unional)"
+	},
+	"homepage": "https://github.com/cyberuni/color-map",
+	"repository": "https://github.com/cyberuni/color-map",
+	"license": "MIT",
+	"keywords": ["color", "palette", "design-system", "contrast", "css"]
+}

package/CHANGELOG.md

@@ -0,0 +1,100 @@
+# color-map
+
+## 2.3.1
+
+### Patch Changes
+
+- 764413e: `llms.txt` now maps the library as well as the commands: each entry point with its exports, the conventions that hold across them, and the `schema` command, which it had left out. The docs site serves the same file at `/color-map/llms.txt`.
+
+## 2.3.0
+
+### Minor Changes
+
+- 7998846: Add contrast to `color-map/color`: `contrast()` (WCAG 2 by default), `meets()` with named levels such as `AA`, `onColor()` for readable text on a background, and `findContrast()` to find a color of a given hue and chroma that reaches a target and report the ratio it achieves. Any `(fg, bg) => number` function, or a `ContrastFn` with thresholds, replaces WCAG 2, for example an APCA function built on colorjs.io. `mix()` now treats the hue of a converted gray as missing in `oklch` and `lch`, so mixing white with blue in `oklch` keeps blue's hue.
+- 0072bf7: Add the color core at `color-map/color`: parse any CSS Color 4 color (hex, named, `rgb()`, `hsl()`, `hwb()`, `lab()`, `lch()`, `oklab()`, `oklch()`, `color()`), convert between 15 color spaces, serialize with `toCss()` and `toHex()`, check and fix gamut with `inGamut()` and `toGamut()` (CSS Color 4 mapping or clip), and compare with `deltaEOk()` and `equals()`. Colors are plain `{ colorSpace, components, alpha? }` objects with `null` for `none`. `fromArgb()` and `toArgb()` convert to and from Material Color Utilities' integer colors. Each space is its own module, so importing one space costs only that space. The existing `createColors`, `createColorsFromMap`, `rgbHex` and `rgbaString` are unchanged.
+- bffd600: Add `createGradient()` to `color-map/scale`: it returns a number of colors along a gradient through color stops, the way a CSS gradient blends them. A stop is `{ color, at? }` or a bare color; stops without a position spread evenly; `in` and `hue` work as they do in `mix()`, with `oklab` by default; each stop's color carries its own alpha. `createColorsFromMap` is now deprecated in favor of `createGradient`, with no change in behavior.
+- aba59da: Add the `color-map` command and an agent skill to the package. `npx color-map` runs `convert`, `mix`, `contrast`, `find-contrast`, `scale`, `palette`, `harmony`, `export` and `schema`; output is TOON by default (`--format json` for JSON), errors are coded, and WCAG 2 is the contrast measure. The package also ships JSON Schemas for every command's options (`color-map/schemas/*`), an `llms.txt`, and a `color-map` skill as a plugin for Claude Code, Cursor, Codex and Copilot CLI. The package still has no runtime dependencies, and the library entry points do not load the command.
+- 01f8f8a: Add `mix()` for interpolating colors the way CSS does, and `parseExpr()` and `resolve()` for CSS Color 5 values: `color-mix()`, relative colors with a `calc()` subset, `light-dark()`, `contrast-color()`, `currentcolor` and system colors. They are exported from `color-map/color`.
+- 887187f: Add `color-map/palette`: `harmony()` (complementary, split, analogous, triadic and tetradic, rotated in OKLCH by default), `harmonize()` (Material's rule: move a hue half the way toward another, at most 15°), `inverse()`, `darkVariant()` (`mirror`, `tone-swap` or `lightness-invert`), `semanticPalette()` (primary, status, surface and outline roles, each pair recording its contrast) and `validate()` (failing pairs, scales whose lightness is not steady, and out-of-gamut colors). Tone gaps of 50 give about 4.5 on WCAG 2, and 4.48 at the worst pair.
+- b213db4: Add `color-map/scale`: `createScale()` with the `tailwind-11`, `radix-12`, `tone-13` and `even` presets (or your own lightness, chroma and hue-shift curves), `createContrastScale()` to pick each step by target contrast, `scaleFromBrand()` for a 12-step scale with your brand color exactly at step 9, and `tonalPalette()` for L* tones, where tones 40 apart reach contrast 3. `mix()` now also treats the hue of a converted gray as missing in `hsl` and `hwb`, and converting white to `hsl` gives saturation 0.
+- be3ba42: Add `color-map/tokens`: `toDtcg()` (a DTCG 2025.10 token file with a hex fallback; `none` components print as `"none"`), `toCssVariables()` (custom properties in one rule) and `toTailwindTheme()` (a Tailwind v4 `@theme` block in oklch). They take a color, a CSS string, an array (a scale; 11 colors get the keys 50 to 950), a nested object, or a `semanticPalette()` result.
+- 0ccc6f7: Add narrow forms of the converting helpers to `color-map/color`: `createToHex`, `createInGamut`, `createToGamut`, `createDeltaEOk`, `createEquals`, `createMix`, `createContrast`, `createMeets`, `createOnColor` and `createFindContrast`. Each takes the spaces your colors are in, as `createConverter` does, and returns the helper over just those, so a bundle no longer carries all 15 spaces. Each adds the spaces it works in itself; `createToGamut`, for example, adds `srgb`, `oklch` and `oklab`. The narrow helpers take color objects rather than CSS strings, so they do not carry `parse`. `toHex` over every space is about 3 kB gzip; `createToHex(oklch)` is about 1.3 kB. The existing helpers are unchanged.
+- 42ff99d: `color-map` now re-exports `color-map/color`, `color-map/scale`, `color-map/palette` and `color-map/tokens`, so `import { parse, toCss } from 'color-map'` works. With a bundler, this costs nothing extra.
+  
+  Add `color-map/legacy` with `createColors`, `createColorsFromMap`, `rgbHex`, `rgbaString` and their types. The root still exports these names, unchanged, but marks them deprecated: 3.0 removes them from the root, so import them from `color-map/legacy`.
+
+### Patch Changes
+
+- 9b46fea: Add an Acknowledgements section to the README.
+- 9930c90: Make `parse`, `toGamut` and `mix` faster, with the same results and no API change. `parse` reads hex and the plain functional forms by char code (about 2.4 times faster, on the repository benchmark), `toGamut` into `srgb` searches in linear sRGB (about 4.6 times), and `mix` skips the `none` and powerless-hue work when no component is `none` (about 3 times). Anything the fast parse path does not take still goes through the previous parser, so every accepted form and error message is unchanged. The gzip size of the convert-from-a-string scenario grows by about 0.9 kB.
+- 8287110: Speed up color conversion, `toGamut`, `contrast`, `mix` and the scale and palette builders (`semanticPalette` runs about 1.8 times as fast), and shrink every entry point's gzip size slightly. Every result is unchanged, to the last bit.
+- 602a460: Fix names such as `constructor`, `__proto__` and `toString` reaching `Object.prototype` in `parse`, `parseExpr`, `meets`, `harmony`, `createScale` and `toDtcg`; they are now unknown names like any other, and `toDtcg` returns groups without a prototype. Make `toCss` about 2.7 times faster with an exact rounding fast path; its output is unchanged.
+- 96f4464: Include `CHANGELOG.md` in the published package.
+- 85506ca: An unknown preset, scheme, mode, strategy, contrast algorithm or hue method now throws `color-map: unknown <thing> "<value>"; use one of ...` instead of a raw `TypeError` (`createScale({ seed, steps: 'nope' })`) or a silent fallback (`mode`, harmony `space`). An unknown color space also lists the valid ones, and `meets` words its unknown-level error the same way.
+
+Entries from 2.2.0 and earlier were produced by semantic-release, which was
+configured without the changelog plugin — 2.1.0 and 2.2.0 exist only as GitHub
+Releases and are absent below. Everything from the next release on is written
+here by changesets.
+
+## [2.0.6](https://github.com/unional/color-map/compare/v2.0.5...v2.0.6) (2022-10-03)
+
+
+### Bug Fixes
+
+* re-release again ([cf9ba4c](https://github.com/unional/color-map/commit/cf9ba4c75af52f5803b53a30cb0e003c201595f2))
+
+## [2.0.5](https://github.com/unional/color-map/compare/v2.0.4...v2.0.5) (2022-10-03)
+
+
+### Bug Fixes
+
+* re-release ([0742296](https://github.com/unional/color-map/commit/07422964537f9a0564149a353ecfe3911c01eb0a))
+
+## [2.0.4](https://github.com/unional/color-map/compare/v2.0.3...v2.0.4) (2022-10-03)
+
+
+### Bug Fixes
+
+* cjs package.json ([3b85801](https://github.com/unional/color-map/commit/3b85801902c2b555d9fa9f4bb98a8da23bcd25c6))
+
+## [2.0.3](https://github.com/unional/color-map/compare/v2.0.2...v2.0.3) (2022-06-13)
+
+
+### Bug Fixes
+
+* add main field ([3acec72](https://github.com/unional/color-map/commit/3acec726b6a9bfe82cbe6553dec6ba53b659facb))
+
+## [2.0.2](https://github.com/unional/color-map/compare/v2.0.1...v2.0.2) (2022-06-13)
+
+
+### Bug Fixes
+
+* add exports.require for CJS ([b36cde8](https://github.com/unional/color-map/commit/b36cde8cd75e4a00ef572b0b6a4badb2109a1a84))
+
+## [2.0.1](https://github.com/unional/color-map/compare/v2.0.0...v2.0.1) (2022-06-13)
+
+
+### Bug Fixes
+
+* use NodeNext module resolution ([#128](https://github.com/unional/color-map/issues/128)) ([fdfc5cc](https://github.com/unional/color-map/commit/fdfc5ccfcc0025d1b2c3ccbe0138c3b491fc7037))
+
+# [2.0.0](https://github.com/unional/color-map/compare/v1.1.4...v2.0.0) (2022-06-13)
+
+
+### Bug Fixes
+
+* remove spec files from dist ([#126](https://github.com/unional/color-map/issues/126)) ([e1ad859](https://github.com/unional/color-map/commit/e1ad859a38c91a450cd23f1b126ba9992de87c62))
+
+
+* fix!: export as ESM (#127) ([ae16eaa](https://github.com/unional/color-map/commit/ae16eaa83629a5248143eee8a895a0edb15240c1)), closes [#127](https://github.com/unional/color-map/issues/127)
+
+
+### BREAKING CHANGES
+
+* export with only ESM
+
+This is more of a testing release, to see what are the behavior of ESM:
+
+- how it behaves when exporting ESM using esnext
+- how it behaves with only ESM

package/README.md

@@ -14,10 +14,25 @@ Color map generator with no dependency.
 
 Inspired from [`colormap`](https://github.com/bpostlethwaite/colormap).
 
-## `createColors(from, to, shades, alpha?)`
+## Library
 
 ```ts
-import { createColors } from 'color-map'
+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](https://cyberuni.github.io/color-map/library/) 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?)`
+
+```ts
+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])
@@ -26,34 +41,80 @@ const rgbaRange = createColors([0, 0, 255], [0, 255, 128], 72, [0, 1])
 const rgbRange = createColors([0, 0, 255], [0, 255, 128], 72)
 ```
 
-## `rgbHex(rgb)`
+### `rgbHex(rgb)`
 
 ```ts
-import { rgbHex } from 'color-map'
+import { rgbHex } from 'color-map/legacy'
 
 rgbHex([0, 128, 255]) // '#0080ff'
 rgbHex([0, 128, 255, 0.3]) // '#0080ff'
 ```
 
-## `rgbaString(rgba)`
+### `rgbaString(rgba)`
 
 ```ts
-import { rgbaString } from 'color-map'
+import { rgbaString } from 'color-map/legacy'
 
 rgbaString([0, 128, 255, 0.2]) // 'rgba(0,128,255,0.2)`
 
 ```
 
-## `createColorsFromMap(colormap, shades, alpha?)`
+### `createColorsFromMap(colormap, shades, alpha?)`
 
 ```ts
-import { createColorsFromMap, ColorMap } from 'color-map'
+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:
+
+```ts
+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](https://cyberuni.github.io/color-map/library/#gradients) for the full recipe.
+
+## The `color-map` command
+
+The package ships a command for agents, with no extra install and no runtime dependency:
+
+```sh
+npx color-map palette '#3b82f6'
+```
+
+Output is [TOON](https://github.com/toon-format/toon) by default, with `--format json` for JSON. It follows the [AXI](https://github.com/kunchenguid/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.
+
+| Command | What 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.5` | find 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`](./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](https://bottosson.github.io/posts/oklab/), and writes [Design Tokens](https://www.designtokens.org/) color values. Its scales and palettes learn from [Radix Colors](https://www.radix-ui.com/colors), [Material Design 3](https://m3.material.io/styles/color/system/overview) and [Tailwind CSS](https://tailwindcss.com/). It started from [`colormap`](https://github.com/bpostlethwaite/colormap). The [Compare page](https://cyberuni.github.io/color-map/compare/) 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](https://cyberuni.github.io/color-map/credits/) says what each one contributed and under which license.
+
 ## Contribute
 
 ```sh
@@ -71,6 +132,8 @@ 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.
+
 [codecov-image]: https://codecov.io/gh/cyberuni/color-map/branch/main/graph/badge.svg
 [codecov-url]: https://codecov.io/gh/cyberuni/color-map
 [downloads-image]: https://img.shields.io/npm/dm/color-map.svg?style=flat