color-map 2.2.0 → 2.3.0

package/schemas/harmony.schema.json

@@ -0,0 +1,58 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"$id": "https://unpkg.com/color-map/schemas/harmony.schema.json",
+	"title": "color-map harmony",
+	"description": "The colors of a harmony scheme: the color rotated around the hue wheel",
+	"type": "object",
+	"properties": {
+		"color": {
+			"type": "string",
+			"description": "The base color",
+			"x-kind": "argument"
+		},
+		"scheme": {
+			"type": "string",
+			"enum": [
+				"complementary",
+				"split",
+				"analogous",
+				"triadic",
+				"tetradic"
+			],
+			"description": "The harmony scheme",
+			"default": "complementary",
+			"x-kind": "option"
+		},
+		"space": {
+			"type": "string",
+			"enum": [
+				"hsl",
+				"hwb",
+				"lch",
+				"oklch"
+			],
+			"description": "The space whose hue is rotated",
+			"default": "oklch",
+			"x-kind": "option"
+		},
+		"gamut": {
+			"type": "string",
+			"enum": [
+				"srgb",
+				"srgb-linear",
+				"display-p3",
+				"display-p3-linear",
+				"a98-rgb",
+				"prophoto-rgb",
+				"rec2020"
+			],
+			"description": "The gamut every color must fit",
+			"default": "srgb",
+			"x-kind": "option"
+		}
+	},
+	"required": [
+		"color"
+	],
+	"additionalProperties": false
+}

package/schemas/mix.schema.json

@@ -0,0 +1,72 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"$id": "https://unpkg.com/color-map/schemas/mix.schema.json",
+	"title": "color-map mix",
+	"description": "Mix two CSS colors, as color-mix() does",
+	"type": "object",
+	"properties": {
+		"a": {
+			"type": "string",
+			"description": "The first color",
+			"x-kind": "argument"
+		},
+		"b": {
+			"type": "string",
+			"description": "The second color",
+			"x-kind": "argument"
+		},
+		"amount": {
+			"type": "number",
+			"minimum": 0,
+			"maximum": 1,
+			"description": "How far from a to b, 0 to 1",
+			"default": 0.5,
+			"x-kind": "option"
+		},
+		"in": {
+			"type": "string",
+			"enum": [
+				"srgb",
+				"srgb-linear",
+				"hsl",
+				"hwb",
+				"lab",
+				"lch",
+				"oklab",
+				"oklch",
+				"display-p3",
+				"display-p3-linear",
+				"a98-rgb",
+				"prophoto-rgb",
+				"rec2020",
+				"xyz-d50",
+				"xyz-d65"
+			],
+			"description": "The space to interpolate in",
+			"default": "oklab",
+			"x-kind": "option"
+		},
+		"hue": {
+			"type": "string",
+			"enum": [
+				"shorter",
+				"longer",
+				"increasing",
+				"decreasing"
+			],
+			"description": "How hues travel in a polar space",
+			"default": "shorter",
+			"x-kind": "option"
+		},
+		"full": {
+			"type": "boolean",
+			"description": "Show the complete output instead of truncating it",
+			"x-kind": "option"
+		}
+	},
+	"required": [
+		"a",
+		"b"
+	],
+	"additionalProperties": false
+}

package/schemas/palette.schema.json

@@ -0,0 +1,56 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"$id": "https://unpkg.com/color-map/schemas/palette.schema.json",
+	"title": "color-map palette",
+	"description": "A semantic palette from one brand color: primary, status colors, surface and outline, each with a text color and its WCAG 2 ratio",
+	"type": "object",
+	"properties": {
+		"brand": {
+			"type": "string",
+			"description": "The brand color",
+			"x-kind": "argument"
+		},
+		"mode": {
+			"type": "string",
+			"enum": [
+				"light",
+				"dark"
+			],
+			"description": "light or dark",
+			"default": "light",
+			"x-kind": "option"
+		},
+		"target": {
+			"type": "number",
+			"minimum": 1,
+			"maximum": 21,
+			"description": "The WCAG 2 ratio every text pair must reach",
+			"default": 4.5,
+			"x-kind": "option"
+		},
+		"gamut": {
+			"type": "string",
+			"enum": [
+				"srgb",
+				"srgb-linear",
+				"display-p3",
+				"display-p3-linear",
+				"a98-rgb",
+				"prophoto-rgb",
+				"rec2020"
+			],
+			"description": "The gamut every color must fit",
+			"default": "srgb",
+			"x-kind": "option"
+		},
+		"full": {
+			"type": "boolean",
+			"description": "Show the complete output instead of truncating it",
+			"x-kind": "option"
+		}
+	},
+	"required": [
+		"brand"
+	],
+	"additionalProperties": false
+}

package/schemas/scale.schema.json

@@ -0,0 +1,86 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"$id": "https://unpkg.com/color-map/schemas/scale.schema.json",
+	"title": "color-map scale",
+	"description": "Build a color scale from a seed color: a preset, a Radix-style brand scale, or contrast targets",
+	"type": "object",
+	"properties": {
+		"seed": {
+			"type": "string",
+			"description": "The color the scale is built around",
+			"x-kind": "argument"
+		},
+		"preset": {
+			"type": "string",
+			"enum": [
+				"tailwind-11",
+				"radix-12",
+				"tone-13",
+				"even"
+			],
+			"description": "The scale shape",
+			"default": "tailwind-11",
+			"x-kind": "option"
+		},
+		"steps": {
+			"type": "integer",
+			"minimum": 2,
+			"description": "Steps of an even scale; replaces --preset",
+			"x-kind": "option"
+		},
+		"brand": {
+			"type": "boolean",
+			"description": "Build a 12-step UI scale where the seed is step 9 exactly",
+			"x-kind": "option"
+		},
+		"mode": {
+			"type": "string",
+			"enum": [
+				"light",
+				"dark"
+			],
+			"description": "light or dark, for --brand",
+			"default": "light",
+			"x-kind": "option"
+		},
+		"background": {
+			"type": "string",
+			"description": "The background: page color for --brand, or what --targets are measured against",
+			"x-kind": "option"
+		},
+		"targets": {
+			"type": "array",
+			"items": {
+				"type": "number",
+				"minimum": 1,
+				"maximum": 21
+			},
+			"description": "Contrast ratios, one per step, such as 3,4.5,7: builds a contrast scale",
+			"x-kind": "option"
+		},
+		"gamut": {
+			"type": "string",
+			"enum": [
+				"srgb",
+				"srgb-linear",
+				"display-p3",
+				"display-p3-linear",
+				"a98-rgb",
+				"prophoto-rgb",
+				"rec2020"
+			],
+			"description": "The gamut every step must fit",
+			"default": "srgb",
+			"x-kind": "option"
+		},
+		"full": {
+			"type": "boolean",
+			"description": "Show the complete output instead of truncating it",
+			"x-kind": "option"
+		}
+	},
+	"required": [
+		"seed"
+	],
+	"additionalProperties": false
+}

package/skills/color-map/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: color-map
+description: Build a design-system color palette, scale or token file with the color-map CLI. Use when asked to pick or generate colors from a brand color, make a semantic palette with passing contrast, convert or mix CSS colors, check WCAG contrast, or export colors as CSS variables, DTCG tokens or a Tailwind v4 theme.
+---
+
+# color-map
+
+Drive the `color-map` command instead of writing color math by hand. Every result prints as TOON by default; add `--format json` for JSON. Run it with `npx color-map` when it is not installed.
+
+## One prompt to a valid palette
+
+1. Run `color-map palette '<brand color>' [--mode dark]`. The answer lists each role (`primary`, `primaryContainer`, `success`, `warning`, `danger`, `info`, `surface`, `surfaceVariant`, `outline`) with its background, text color and WCAG 2 ratio.
+2. Read `failing` and `issues`. `failing: 0` and `issues: "none: ..."` mean every pair meets its target. If not, change `--target` or the brand color and run it again; do not edit hex values by hand.
+3. Write the result with `color-map export '<brand color>' --source palette --to css|tailwind|dtcg`. The output is the file content: redirect it to a file.
+4. Do both modes when the design has a dark theme: run steps 1 and 3 with `--mode dark`.
+
+## Commands
+
+| Command | Use it to |
+| --- | --- |
+| `convert <color> --to <space> [--gamut <gamut>]` | change space; `--gamut` maps into a gamut instead of clipping |
+| `mix <a> <b> [--amount 0.5] [--in oklab]` | blend as `color-mix()` does |
+| `contrast <fg> <bg>` | WCAG 2 ratio with the AA and AAA verdicts |
+| `find-contrast <bg> --target 4.5 [--hue H] [--chroma C]` | find a text color that reaches a ratio |
+| `scale <seed> [--preset tailwind-11\|radix-12\|tone-13\|even] [--steps N] [--brand] [--targets R ...]` | a scale; `--brand` keeps the seed as step 9; `--targets` with `--background` builds a contrast scale |
+| `palette <brand> [--mode] [--target]` | the semantic palette above |
+| `harmony <color> --scheme complementary\|split\|analogous\|triadic\|tetradic` | related hues |
+| `export [color] --to css\|tailwind\|dtcg [--source palette\|scale] [--tokens file.json]` | write tokens |
+| `schema [command]` | print the JSON Schema of a command's options |
+
+Colors are any CSS color: `#3b82f6`, `oklch(0.7 0.15 250)`, `color-mix(in oklab, red, blue)`. Add `--full` for every field. Run `color-map <command> --help` for one command.
+
+## Rules
+
+- Contrast is WCAG 2. There is no other contrast algorithm; do not look for an option for one.
+- Pass colors as given; never round-trip them through hex when precision matters. Use `--to oklch` or `--format json`.
+- A failed call exits 2 with a coded error (`invalid-color`, `unknown-option`, ...) on stdout. Fix the input named in the error and retry; retrying the same call cannot help.
+- Nothing prompts, and an unknown flag fails instead of being ignored.

package/src/cli/bin.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs'
+import { createApp } from './cli.js'
+
+const { version } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')) as { version: string }
+
+createApp({ version })
+	.parse(process.argv)
+	.then((code) => {
+		if (typeof code === 'number') process.exitCode = code
+	})

package/src/cli/cli.ts

@@ -0,0 +1,40 @@
+import { type cli as CliNamespace, cli } from 'clibuilder'
+import { homeHeader, result } from 'clibuilder/axi'
+import { contrast } from './commands/contrast.js'
+import { convert } from './commands/convert.js'
+import { exportCommand } from './commands/export.js'
+import { findContrastCommand } from './commands/find-contrast.js'
+import { harmony } from './commands/harmony.js'
+import { mix } from './commands/mix.js'
+import { palette } from './commands/palette.js'
+import { scale } from './commands/scale.js'
+import { schemaCommand } from './schema-command.js'
+
+export const commands = [convert, mix, contrast, findContrastCommand, scale, palette, harmony, exportCommand] as const
+
+const description = 'Color tools for agents: convert, mix, contrast, scale, palette and export'
+
+/** The color-map CLI. Pass `streams` to capture its output. */
+export function createApp(options: Pick<CliNamespace.Options, 'streams' | 'version'>) {
+	let app = cli({ name: 'color-map', description, version: options.version, streams: options.streams }).default({
+		description,
+		run() {
+			return result(
+				{
+					...homeHeader({ description }),
+					commands: [...commands.map((c) => c.name), 'schema'],
+					defaults: 'WCAG 2 contrast, sRGB gamut, TOON output (--format json for JSON)'
+				},
+				{
+					help: [
+						"Run `color-map palette '#3b82f6'` for a semantic palette with every contrast pair checked",
+						"Run `color-map scale '#3b82f6'` for an 11-step scale",
+						'Run `color-map <command> --help` for one command'
+					]
+				}
+			)
+		}
+	})
+	for (const c of commands) app = app.command(c)
+	return app.command(schemaCommand(commands))
+}

package/src/cli/commands/contrast.ts

@@ -0,0 +1,36 @@
+import { type cli, command, t } from 'clibuilder'
+import { result } from 'clibuilder/axi'
+import { contrast as contrastOf, meets } from '../../color/index.js'
+import { readColor, round } from '../shared.js'
+
+const definition = command({
+	name: 'contrast',
+	description: 'WCAG 2 contrast ratio of a text color on a background, with the AA and AAA verdicts',
+	arguments: [
+		{ name: 'fg', description: 'The text (foreground) color', type: t.string() },
+		{ name: 'bg', description: 'The background color', type: t.string() }
+	],
+	run(args) {
+		const fg = readColor(args.fg, 'fg')
+		const bg = readColor(args.bg, 'bg')
+		const pass = (level: string) => meets(fg, bg, level)
+		const out = {
+			fg: args.fg,
+			bg: args.bg,
+			algorithm: 'wcag2',
+			ratio: round(contrastOf(fg, bg)),
+			AA: pass('AA'),
+			'AA-large': pass('AA-large'),
+			AAA: pass('AAA'),
+			'AAA-large': pass('AAA-large')
+		}
+		return result(out, {
+			help: out.AA
+				? undefined
+				: `Run \`color-map find-contrast '${args.bg}' --target 4.5\` for a text color that passes AA`
+		})
+	}
+})
+
+/** Typed as the plain command so its declaration does not name args-minus' internals. */
+export const contrast: cli.Command = definition

package/src/cli/commands/convert.ts

@@ -0,0 +1,37 @@
+import { type cli, command, t } from 'clibuilder'
+import { fullOption, result } from 'clibuilder/axi'
+import { convert as convertColor, inGamut, toGamut } from '../../color/index.js'
+import { describe, GAMUTS, readColor, SPACES } from '../shared.js'
+
+const definition = command({
+	name: 'convert',
+	description: 'Convert a CSS color to another color space',
+	arguments: [
+		{ name: 'color', description: 'Any CSS color, such as "#3b82f6" or "oklch(0.7 0.15 250)"', type: t.string() }
+	],
+	options: {
+		to: { description: 'Target color space', type: t.enum([...SPACES]), default: 'srgb' },
+		gamut: {
+			description: 'Map the result into this gamut (CSS gamut mapping) when it falls outside',
+			type: t.enum([...GAMUTS]).optional()
+		},
+		full: fullOption
+	},
+	run(args) {
+		const input = readColor(args.color)
+		const converted = convertColor(input, args.to)
+		const mapped = args.gamut ? toGamut(converted, { gamut: args.gamut }) : converted
+		const out = {
+			input: args.color,
+			to: args.to,
+			...describe(mapped, args.full === true),
+			...(args.full ? { inSrgb: inGamut(mapped, 'srgb'), inDisplayP3: inGamut(mapped, 'display-p3') } : {})
+		}
+		return result(out, {
+			help: `Run \`color-map mix '${args.color}' '<other color>'\` to blend it with another color`
+		})
+	}
+})
+
+/** Typed as the plain command so its declaration does not name args-minus' internals. */
+export const convert: cli.Command = definition

package/src/cli/commands/export.ts

@@ -0,0 +1,102 @@
+import { readFileSync } from 'node:fs'
+import { type cli, command, t } from 'clibuilder'
+import { CliError, document, exitCodes, isCliError } from 'clibuilder/axi'
+import type { ColorSpaceId } from '../../color/index.js'
+import { semanticPalette } from '../../palette/index.js'
+import { createScale } from '../../scale/index.js'
+import { toCssVariables, toDtcg, toTailwindTheme } from '../../tokens/index.js'
+import { EXPORT_SOURCES, EXPORT_TARGETS, MODES, readColor, SPACES } from '../shared.js'
+
+function usage(code: string, message: string, help: string, details: CliError.Details = {}) {
+	return new CliError(message, { code, exitCode: exitCodes.usage, details, help })
+}
+
+function readTokens(path: string): unknown {
+	let text: string
+	try {
+		text = readFileSync(path, 'utf8')
+	} catch {
+		throw usage(
+			'file-not-found',
+			`cannot read the token file "${path}"`,
+			'Pass a JSON file of CSS color strings, nested as you like',
+			{ path }
+		)
+	}
+	try {
+		return JSON.parse(text)
+	} catch {
+		throw usage(
+			'invalid-json',
+			`"${path}" is not valid JSON`,
+			'Pass a JSON file of CSS color strings, nested as you like',
+			{ path }
+		)
+	}
+}
+
+const definition = command({
+	name: 'export',
+	description: 'Write a palette, a scale or your own tokens as DTCG JSON, CSS variables or a Tailwind v4 theme',
+	arguments: [
+		{
+			name: 'color',
+			description: 'The brand color to build tokens from; leave out with --tokens',
+			type: t.string().optional()
+		}
+	],
+	options: {
+		to: { description: 'Output format', type: t.enum([...EXPORT_TARGETS]), default: 'css' },
+		source: { description: 'What to build from the color', type: t.enum([...EXPORT_SOURCES]), default: 'palette' },
+		mode: { description: 'light or dark, for --source palette', type: t.enum([...MODES]), default: 'light' },
+		tokens: {
+			description: 'A JSON file of CSS color strings, nested as you like, instead of a color',
+			type: t.string().optional()
+		},
+		space: { description: 'Convert every color to this space (css, tailwind)', type: t.enum([...SPACES]).optional() },
+		prefix: { description: 'Variable name prefix (css; tailwind uses --namespace)', type: t.string().optional() },
+		selector: { description: 'The CSS rule selector (css)', type: t.string().optional() },
+		namespace: { description: 'The Tailwind theme namespace (tailwind)', type: t.string().optional() },
+		inline: { description: 'Write @theme inline (tailwind)', type: t.boolean().optional() },
+		precision: { description: 'Decimal places in printed numbers', type: t.int({ min: 0, max: 10 }).optional() },
+		hex: { description: 'Add the hex fallback to DTCG values; --hex=false drops it', type: t.boolean().optional() }
+	},
+	run(args) {
+		if ((args.color === undefined) === (args.tokens === undefined))
+			throw usage(
+				'input-required',
+				'give exactly one of a color or --tokens <file>',
+				"Run `color-map export '#3b82f6' --to css`, or `color-map export --tokens tokens.json --to dtcg`"
+			)
+		try {
+			const space = args.space as ColorSpaceId | undefined
+			let tree: Parameters<typeof toDtcg>[0]
+			if (args.tokens !== undefined) tree = readTokens(args.tokens) as typeof tree
+			else {
+				const color = readColor(args.color as string)
+				tree =
+					args.source === 'scale'
+						? { primary: createScale({ seed: color }) }
+						: semanticPalette({ brand: color, mode: args.mode })
+			}
+			if (args.to === 'dtcg') return document(`${JSON.stringify(toDtcg(tree, { hex: args.hex }), null, 2)}\n`)
+			if (args.to === 'css')
+				return document(
+					toCssVariables(tree, { space, prefix: args.prefix, selector: args.selector, precision: args.precision })
+				)
+			return document(
+				toTailwindTheme(tree, { space, namespace: args.namespace, inline: args.inline, precision: args.precision })
+			)
+		} catch (e) {
+			if (isCliError(e)) throw e
+			throw usage(
+				'export-failed',
+				(e as Error).message,
+				'The tokens must be CSS color strings, color objects, or arrays and objects of them'
+			)
+		}
+	}
+})
+
+/** Typed as the plain command so its declaration does not name args-minus' internals. */
+export const exportCommand: cli.Command = definition

package/src/cli/commands/find-contrast.ts

@@ -0,0 +1,37 @@
+import { type cli, command, t } from 'clibuilder'
+import { fullOption, result } from 'clibuilder/axi'
+import { findContrast } from '../../color/index.js'
+import { describe, readColor, round } from '../shared.js'
+
+const definition = command({
+	name: 'find-contrast',
+	description: 'Find the color closest in lightness to a background that reaches a WCAG 2 contrast target',
+	arguments: [{ name: 'bg', description: 'The background color', type: t.string() }],
+	options: {
+		target: { description: 'The contrast ratio to reach, 1 to 21', type: t.number({ min: 1, max: 21 }), default: 4.5 },
+		hue: {
+			description: "OKLCH hue of the result in degrees (default: the background's hue)",
+			type: t.number().optional()
+		},
+		chroma: { description: 'OKLCH chroma of the result (default 0, a gray)', type: t.number({ min: 0 }).optional() },
+		direction: { description: 'Which way to look first', type: t.enum(['lighter', 'darker']).optional() },
+		full: fullOption
+	},
+	run(args) {
+		const found = findContrast(readColor(args.bg, 'bg'), args.target, {
+			hue: args.hue,
+			chroma: args.chroma,
+			direction: args.direction
+		})
+		return result({
+			bg: args.bg,
+			target: args.target,
+			...describe(found.color, args.full === true),
+			ratio: round(found.contrast),
+			met: found.met
+		})
+	}
+})
+
+/** Typed as the plain command so its declaration does not name args-minus' internals. */
+export const findContrastCommand: cli.Command = definition

package/src/cli/commands/harmony.ts

@@ -0,0 +1,30 @@
+import { type cli, command, t } from 'clibuilder'
+import { result } from 'clibuilder/axi'
+import { toCss, toHex } from '../../color/index.js'
+import { harmony as harmonyOf } from '../../palette/index.js'
+import { GAMUTS, POLAR_SPACES, readColor } from '../shared.js'
+
+export const SCHEMES = ['complementary', 'split', 'analogous', 'triadic', 'tetradic'] as const
+
+const definition = command({
+	name: 'harmony',
+	description: 'The colors of a harmony scheme: the color rotated around the hue wheel',
+	arguments: [{ name: 'color', description: 'The base color', type: t.string() }],
+	options: {
+		scheme: { description: 'The harmony scheme', type: t.enum([...SCHEMES]), default: 'complementary' },
+		space: { description: 'The space whose hue is rotated', type: t.enum([...POLAR_SPACES]), default: 'oklch' },
+		gamut: { description: 'The gamut every color must fit', type: t.enum([...GAMUTS]), default: 'srgb' }
+	},
+	run(args) {
+		const colors = harmonyOf(readColor(args.color), args.scheme, { space: args.space, gamut: args.gamut })
+		return result({
+			color: args.color,
+			scheme: args.scheme,
+			space: args.space,
+			colors: colors.map((c, i) => ({ index: i + 1, hex: toHex(c), css: toCss(c) }))
+		})
+	}
+})
+
+/** Typed as the plain command so its declaration does not name args-minus' internals. */
+export const harmony: cli.Command = definition

package/src/cli/commands/mix.ts

@@ -0,0 +1,29 @@
+import { type cli, command, t } from 'clibuilder'
+import { fullOption, result } from 'clibuilder/axi'
+import { mix as mixColors } from '../../color/index.js'
+import { describe, HUE_METHODS, readColor, SPACES } from '../shared.js'
+
+const definition = command({
+	name: 'mix',
+	description: 'Mix two CSS colors, as color-mix() does',
+	arguments: [
+		{ name: 'a', description: 'The first color', type: t.string() },
+		{ name: 'b', description: 'The second color', type: t.string() }
+	],
+	options: {
+		amount: { description: 'How far from a to b, 0 to 1', type: t.number({ min: 0, max: 1 }), default: 0.5 },
+		in: { description: 'The space to interpolate in', type: t.enum([...SPACES]), default: 'oklab' },
+		hue: { description: 'How hues travel in a polar space', type: t.enum([...HUE_METHODS]), default: 'shorter' },
+		full: fullOption
+	},
+	run(args) {
+		const mixed = mixColors(readColor(args.a, 'a'), readColor(args.b, 'b'), args.amount, { in: args.in, hue: args.hue })
+		return result(
+			{ a: args.a, b: args.b, amount: args.amount, in: args.in, ...describe(mixed, args.full === true) },
+			{ help: `Run \`color-map contrast '${describe(mixed, false).hex}' '#ffffff'\` to check it against white` }
+		)
+	}
+})
+
+/** Typed as the plain command so its declaration does not name args-minus' internals. */
+export const mix: cli.Command = definition