color-cli

name	color-cli
description	[Hyper] Convert colors between hex, rgb, and oklch using @kood/color-cli. Use when the user asks to convert colors, transform CSS file colors, or needs accurate oklch values. Trigger phrases — "color convert", "hex to oklch", "oklch to hex", "rgb to oklch", "CSS color conversion", "color conversion", "tell me the oklch value".
compatibility	Requires Bash tool. @kood/color-cli must be installed globally (`npm i -g @kood/color-cli`).

Color CLI

Convert colors accurately between hex, rgb, and oklch using @kood/color-cli.

<output_language>

Default all user-facing deliverables, saved artifacts, reports, plans, generated docs, summaries, handoff notes, commit/message drafts, and validation notes to Korean, even when this canonical skill file is written in English.

Preserve source code identifiers, CLI commands, file paths, schema keys, JSON/YAML field names, API names, package names, proper nouns, and quoted source excerpts in their required or original language.

Use a different language only when the user explicitly requests it, an existing target artifact must stay in another language for consistency, or a machine-readable contract requires exact English tokens. If a localized template or reference exists (for example *.ko.md or *.ko.json), prefer it for user-facing artifacts.

</output_language>

AI models often produce incorrect oklch conversions due to matrix precision errors, missing gamut mapping, and degree/radian confusion. This skill delegates color conversion to @kood/color-cli (powered by culori) for CSS Color Level 4 compliant results.

<instruction_contract>

Field	Contract
Intent	Produce deterministic color conversions instead of estimating color math in the model.
Scope	Owns single-color conversion, multi-color conversion, and CSS file color-format conversion through @kood/color-cli.
Authority	The color CLI output is authoritative for conversion values; design or palette judgment belongs to design skills.
Evidence	Report the executed command output, gamut warnings, and CSS converted/skipped summary when applicable.
Tools	Use Bash plus the installed color command; do not compute oklch/hex/rgb manually.
Output	Return hex, rgb, and oklch for color values, or the CSS conversion summary for file operations.
Verification	Check the CLI is installed, run conversions through color, and preview CSS file changes with --dry-run first.
Stop condition	Stop after converted values or CSS dry-run/apply summary are reported, or after the install blocker is clear.

</instruction_contract>

<request_routing>

Positive triggers

• "Convert #ff0000 to oklch"
• "What's the oklch value of rgb(0, 128, 255)?"
• "Convert all colors in styles.css to oklch"
• "hex to rgb", "oklch to hex", "convert this color"
• "Normalize the colors in this CSS file to hex"

Out-of-scope

• Color palette generation or design suggestions — use a design skill instead.
• Color theory explanations — answer directly without this skill.
• Creating CSS from scratch — use an implementation skill instead.

Boundary examples

• "What color is oklch(0.7 0.25 140)?" → Use this skill to get the hex/rgb equivalent.
• "Pick a good color for a button" → Do not use this skill; this is a design question.

</request_routing>

Install @kood/color-cli globally if not already available:

npm i -g @kood/color-cli

Verify installation:

color --help

If color command is not found, install it first before proceeding.

Single Color Conversion

When the user asks to convert a specific color value:

color "<value>"

Examples:

color "#ff0000"
color "oklch(0.7 0.25 140)"
color "rgb(255, 0, 0)"
color "hsl(0, 100%, 50%)"

For JSON output (useful for programmatic use):

color --json "#ff0000"

For multiple colors at once:

color "#e63946" "oklch(0.7 0.25 140)" "rgb(0, 128, 255)"

CSS File Color Conversion

When the user wants to convert all colors in a CSS file to a specific format:

Preview first (dry run):

color css <file> --to <format> --dry-run

Apply changes (in-place):

color css <file> --to <format>

Supported target formats: hex, rgb, oklch.

Examples:

# Preview oklch conversion
color css styles.css --to oklch --dry-run

# Apply hex conversion
color css src/global.css --to hex

# Convert to rgb
color css theme.css --to rgb

CSS conversion behavior

• Automatically detects hex, rgb, rgba, oklch patterns in the file
• Skips colors already in the target format
• Preserves alpha values (e.g., rgba(255,0,0,0.5) → oklch(0.628 0.258 29.23 / 0.5))
• Ignores colors inside CSS comments (/* ... */)
• Applies CSS Color Level 4 gamut mapping for out-of-gamut oklch values

<output_interpretation>

Single color output

HEX:   #ff0000
RGB:   rgb(255, 0, 0)
OKLCH: oklch(0.6280 0.2577 29.23)

Gamut mapping warning

When an oklch value is outside the sRGB gamut, the tool applies chroma-reduction and shows:

⚠ Color was outside sRGB gamut — CSS Color Level 4 chroma-reduction applied.

This means the original oklch chroma was reduced to fit sRGB while preserving lightness and hue.

CSS conversion summary

styles.css: 12 colors found, 8 converted, 4 skipped

• converted: colors that were changed to the target format
• skipped: colors already in the target format

</output_interpretation>

• Always use --dry-run first when converting CSS files, then apply if the user confirms.
• When the user provides an oklch value, always run the conversion rather than computing manually — AI models frequently produce incorrect oklch ↔ hex mappings.
• Report the full output (hex, rgb, oklch) to the user so they can pick the format they need.
• For CSS file operations, show the summary (converted/skipped counts) to the user.

<validation_checklist>

• color --help or equivalent install check has succeeded, or the missing-install blocker is reported.
• Color values are converted by color, not manually estimated.
• CSS file conversions are previewed with --dry-run before in-place changes.
• Output includes hex, rgb, and oklch for single values, or converted/skipped counts for CSS files.
• Gamut mapping warnings are preserved in the user-facing result.

</validation_checklist>