color-cli

Color CLI

使用 @kood/color-cli 在 hex、rgb 和 oklch 之间准确转换颜色。

<output_language>

默认使用韩语撰写所有面向用户的交付内容、保存的产物、报告、计划、生成的文档、摘要、交接说明、提交信息草稿和验证说明，即使此规范技能文件是用英语撰写的。

保留源代码标识符、CLI 命令、文件路径、架构键、JSON/YAML 字段名、API 名称、软件包名称、专有名词和引用的源文本摘录，使用其规定语言或原语言。

仅在用户明确要求、现有目标产物为保持一致性必须使用其他语言，或机器可读约定要求使用精确的英文词条时，才使用其他语言。如果存在本地化模板或参考文件（例如 *.ko.md 或 *.ko.json），优先将其用于面向用户的产物。

</output_language>

由于矩阵精度错误、缺少色域映射以及度数与弧度混淆，AI 模型经常无法正确转换 oklch。本技能通过 @kood/color-cli（由 culori 驱动）执行颜色转换，以获得符合 CSS Color Level 4 标准的结果。

<instruction_contract>

字段	约定
意图	生成确定性的颜色转换结果，而不是由模型估算颜色数值。
范围	通过 @kood/color-cli 处理单色转换、多色转换和 CSS 文件颜色格式转换。
权威依据	转换数值以 color CLI 的输出为准；设计或调色板判断属于设计技能的范围。
证据	在适用时报告执行的命令输出、色域警告以及 CSS 转换/跳过摘要。
工具	使用 Bash 和已安装的 color 命令；不要手动计算 oklch/hex/rgb。
循环	无循环：每个请求只执行一轮转换。仅当用户提供另一个值或文件时才重新运行。
输出	对颜色值返回 hex、rgb 和 oklch；对文件操作返回 CSS 转换摘要。
验证	检查 CLI 是否已安装，通过 color 执行转换，并先使用 --dry-run 预览 CSS 文件变更。
停止条件	报告转换后的数值或 CSS 试运行/应用摘要后停止；或在确认安装受阻后停止。

</instruction_contract>

<request_routing>

适用请求

• “将 #ff0000 转换为 oklch”
• “rgb(0, 128, 255) 的 oklch 值是什么？”
• “将 styles.css 中的所有颜色转换为 oklch”
• “hex 转 rgb”、“oklch 转 hex”、“转换这个颜色”
• “将这个 CSS 文件中的颜色统一为 hex”

不适用范围

• 生成调色板或提供设计建议——改用设计技能。
• 解释色彩理论——无需使用此技能，直接回答。
• 从头创建 CSS——改用实现技能。

边界示例

• “oklch(0.7 0.25 140) 是什么颜色？”→ 使用此技能获取对应的 hex/rgb 值。
• “为按钮挑个合适的颜色”→ 不要使用此技能；这是设计问题。

</request_routing>

如果尚未全局安装 @kood/color-cli，请先安装：

npm i -g @kood/color-cli

验证安装：

color --help

如果找不到 color 命令，请先安装，再继续操作。

单色转换

用户要求转换特定颜色值时：

color "<value>"

示例：

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

输出 JSON（适用于程序化使用）：

color --json "#ff0000"

一次转换多个颜色：

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

CSS 文件颜色转换

用户希望将 CSS 文件中的所有颜色转换为指定格式时：

先预览（试运行）：

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

应用变更（原地修改）：

color css <file> --to <format>

支持的目标格式：hex、rgb、oklch。

示例：

# 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 转换行为

• 自动检测文件中的 hex、rgb、rgba、oklch 模式
• 跳过已是目标格式的颜色
• 保留 alpha 值（例如，rgba(255,0,0,0.5) → oklch(0.628 0.258 29.23 / 0.5)）
• 忽略 CSS 注释（/* ... */）中的颜色
• 对超出色域的 oklch 值应用 CSS Color Level 4 色域映射

<output_interpretation>

单个颜色输出

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

色域映射警告

当 oklch 值超出 sRGB 色域时，工具会降低色度并显示：

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

这表示原始 oklch 色度已降低，以适配 sRGB，同时保留亮度和色相。

CSS 转换摘要

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

• converted：已转换为目标格式的颜色
• skipped：已是目标格式的颜色

</output_interpretation>

• 转换 CSS 文件时，始终先使用 --dry-run，并在用户确认后再应用更改。
• 用户提供 oklch 值时，始终运行转换，而不要手动计算——AI 模型经常会错误地转换 oklch ↔ hex。
• 向用户报告完整输出（hex、rgb、oklch），以便用户选择所需格式。
• 对于 CSS 文件操作，向用户显示摘要（已转换／已跳过的数量）。

<validation_checklist>

• color --help 或等效的安装检查已成功，或已报告缺少安装这一阻碍。
• 颜色值由 color 转换，而非手动估算。
• CSS 文件转换在原位更改前已使用 --dry-run 预览。
• 单个值的输出包含 hex、rgb 和 oklch；CSS 文件的输出包含已转换／已跳过的数量。
• 面向用户的结果中保留了色域映射警告。

</validation_checklist>