Tinted UI Tokens 技能（品牌色 UI 设计 Token 技能）

概述

将单一品牌色转化为一整套设计 Token 系统，使品牌色“贯穿”整个界面，而非简单地“叠加”于其上。核心方法（源自文章《你的UI廉价，错在颜色》）是：绝不使用纯中性色——将品牌色相以 2–3% 的比例混合进每一个背景、表面、边框、文字层、阴影、语义色、渐变和图标中。最终效果呈现出“经过精心设计”的观感，而非“拼凑而成”。

配套生成器（scripts/generate_tokens.py）与品牌无关：它通过将每条中性色阶朝给定品牌色相方向混合，推导出整套系统的“温度”，因此适用于任意颜色，而不仅限于原文中提到的两套配色方案。

Cross-agent · 跨 agent

本技能是agent-agnostic（与具体 agent 无关）的。WorkBuddy 和 Claude Code 直接读取本 SKILL.md；其余所有 agent（Cursor、OpenAI Codex、Cline、Aider、WindSurf、GitHub Copilot、Gemini CLI）均采用 INSTRUCTIONS.md 中的同一套指令，并通过 agents/ 目录下的文档完成接入——各 agent 的唯一差异仅在于规则文件的存放位置。引擎（scripts/generate_tokens.py）在所有环境中完全一致。详见 README.md 中的「Cross-Agent Compatibility」表。

中文：本技能与具体 agent 无关。WorkBuddy 与 Claude Code 直接读取本 SKILL.md； 其余 agent（Cursor、OpenAI Codex、Cline、Aider、WindSurf、GitHub Copilot、Gemini CLI） 使用 INSTRUCTIONS.md 中的同一份指令，并按 agents/ 下的文档接入——差异只在规则文件的位置。引擎（scripts/generate_tokens.py）各处一致。 详见 README.md 的「跨 Agent 兼容性」表。

中文：内置生成器（scripts/generate_tokens.py）是品牌无关的——它把每条中性色阶朝给定品牌色相方向混合，从而推导出整套系统的温度，因此对任意颜色都适用，而不局限于原文中的两套配色。

何时使用

• 用户提供品牌色 / hex，并希望获得一套完整的设计系统、CSS 变量或主题。 · 用户提供品牌色 / hex，并想要一套设计系统、CSS 变量或主题。
• 用户希望让现有 UI 显得更高级（“我的界面看起来很廉价”）。 · 用户想让现有 UI 显得更高级（"my UI looks cheap"）。
• 用户需要支持明 / 暗双模式、语义色或品牌化配色的 Token。 · 用户需要明 / 暗双模式、语义色或品牌化配色的 Token。
• 用户希望快速预览某组配色方向的视觉效果。 · 用户想要某个配色方向的快速可视化预览。

工作流

1. 收集最小输入

仅需品牌色即可启动流程。若缺失，请主动询问：

• 品牌色（如 #2563EB 这样的十六进制值）。该值定义整套系统的“温度”。
• 可选：产品 / 品牌名称（仅用于预览界面的标题标签）。
• 可选：输出目录（默认为当前工作目录）。

切勿过度索取信息。一个十六进制值足以生成整套 Token 系统。

2. 运行生成器

使用 Python 3.10+（WorkBuddy 上请使用托管运行时；其他 agent 上可使用任意系统级 python 或 python3）：

python scripts/generate_tokens.py --brand "#2563EB" --name "Acme" --out "./out"

• --brand（必需）：任意十六进制颜色值。
• --name（可选）：预览页头部显示的标签名。
• --out（可选）：输出目录，若不存在则自动创建。
• --format css|html|both|json|tailwind|scss|all（可选，默认为 both）： json = 符合 W3C DTCG 规范的 Token 格式， tailwind = 适配 tailwind.config.js 的配置格式， scss = SCSS 变量格式， all = 同时生成 css + html + json + tailwind + scss。
• --tint-strength subtle|normal|strong（可选，默认为 normal）：控制所有中性色向品牌色相偏移的强度。

脚本将生成 tokens.css（可直接注入的 :root 及 [data-theme="dark"] 自定义属性）和 preview.html（含明 / 暗模式切换功能的自包含实时演示页面）。同时输出检测到的系统“温度”（warm / cool / balanced）及关键数值。

3. 呈现结果

使用 present_files 展示 preview.html（将在实时预览面板中打开）和 tokens.css。向用户说明检测到的系统温度，并强调所有中性色均已按品牌色进行微调。同时主动提供以下选项：使用不同品牌色重新生成，或手动精细调整特定 Token。

4. 手动微调（可选）

如需解释某项取值逻辑或进行调整，请先查阅 references/principles.md（其中详述了每个 Token 的设计依据），再执行编辑。常见微调方式包括：

• 增强或减弱色调强度：传入 --tint-strength subtle|normal|strong 参数（无需修改代码）。 strong 将放大所有混合系数，使品牌存在感更突出。
• 语义色微调强度：即 semantic() 函数中使用的 0.06 混合系数。
• 对比度保障：所有文字-背景组合均自动校验 WCAG AA 合规性，并在必要时自动微调——通常无需手动修复可读性问题。

输出契约

tokens.css 在 :root / [data-theme="light"] 和 [data-theme="dark"] 下定义以下变量：

• --color-brand、--color-brand-subtle、--color-on-brand （可在 --color-brand 上清晰显示的文字 / 图标颜色）
• --color-bg、--color-surface、--color-surface-2、--color-border、--color-border-strong
• --color-text、--color-text-2、--color-text-muted
• --color-error / -subtle、--color-warning / -subtle、--color-success / -subtle
• --shadow-sm、--shadow-md、--shadow-lg

输出中不包含任何纯 #FFFFFF、#000000 或 #808080。所有文字-背景组合均满足 WCAG AA 标准（已自动校验并按需微调）。

参考文档

• references/principles.md —— 生成器所遵循的设计规则，以及用于验证整套系统有效性的灰度测试方法。