ColorwayKit

面向 Agent 的 ColorwayKit

为你的 AI 编码 Agent 提供一套真正可遵循的品牌配色系统。

ColorwayKit 可将一种品牌色转化为完整且易于访问的明暗网页主题——包含 23 个语义角色、WCAG 2.1 + APCA 对比度检查，以及可直接粘贴到项目中的导出内容。

• 网站：https://www.colorwaykit.com
• 构建并导出主题：https://www.colorwaykit.com/brand

它要解决的问题

编码 Agent 能写出可运行的 UI，却会随意编造颜色：这里一个蓝色按钮，那里一个不同的灰色，而且没人检查对比度。每次在提示词里重新描述配色方案，无法扩展。

DESIGN.md 是一种开放格式，已被 AI 编码工具采用。它将设计系统放在一个纯文本文件中：YAML 设计令牌（机器可读的值）加上 Markdown 正文（说明何时以及为何使用这些值）。将它放在项目根目录中，Agent 就会读取它，而不是凭空猜测。

本仓库收集了我们使用 ColorwayKit 生成的模板和示例，帮助你将该文件接入已在使用的 Agent。

为 Agent 提供配色的两种方式

	MCP 服务（实时）	文件（本仓库）
Agent 获取的内容	按需提供的测量令牌，以及成对对比度检查结果	提交到仓库中的版本化 DESIGN.md
设置方式	一条命令 + 一个令牌	将两个文件复制到项目根目录
适用场景	日常开发、跨项目使用	将品牌规范融入代码库、CI、离线使用
配额	按账户计量（免费版每天 5 次 · Plus 每月 1,000 次 · Pro 不限量）	无——它是一个文件

两种方式都可通过 ColorwayKit 账户免费使用。任选一种，也可以将文件用作版本化来源，并将 MCP 用作实时接口。

选项 A：MCP 服务（实时）

1. 在 colorwaykit.com 创建免费账户，然后前往 My Projects → Agent tab → Generate token。

2. 连接（Claude Code 示例）：

   claude mcp add --transport http colorwaykit https://www.colorwaykit.com/api/mcp --header "Authorization: Bearer ck_YOUR_TOKEN"
   

3. 向 Agent 提问：“列出 #4F46E5 的颜色令牌”——如果它返回带名称的角色和测量得出的对比度数值，就说明已连接。Cursor / Codex / Gemini CLI 的完整设置说明：https://www.colorwaykit.com/mcp

工具：get_theme（一个十六进制颜色 → 完整且经过验证的明暗主题）， check_pair（即时验证任意文字/背景颜色组合）， get_theme_by_project（你保存的云端项目）， list_projects（按最新优先顺序列出你保存的项目）。

选项 B：使用文件（快速开始）

1. 打开 Brand Theme Engine，粘贴你的品牌十六进制颜色值（取自徽标或品牌指南）。
2. 前往 Take it to dev 选项卡，复制或下载 DESIGN.md。这是一种免费的导出格式，也支持 CSS 变量、Tailwind 配置、Tokens Studio JSON 和 W3C DTCG 令牌。
3. 将其保存为项目根目录下的 DESIGN.md。
4. 告诉 Agent 使用该文件——参见 templates/。

导出的文件包含什么

• YAML 前置元数据中的 colors：两个主题的语义角色 （primary、on-primary、surface、on-surface、outline、error 等）， 深色主题的角色以 dark- 为前缀。
• 使用 {colors.x} 语法引用这些颜色的 components，因此一处更改即可传递到所有引用处。
• Markdown 的 Colors 部分列出每组文本/背景颜色对的测量结果：与对应阈值对比的 WCAG 2.1 比率，以及与使用场景阈值对比的 APCA Lc。未通过的颜色对会标记为未通过——文件只报告工具计算出的结果，不作其他说明。
• typography、rounded 和 spacing 声明为 omitted：颜色引擎没有这些项目的测量值，因此保留框架默认值，而不凭空编造。

参见 examples/DESIGN.md——该文件由 ColorwayKit 根据品牌颜色 #4F46E5 生成，并非手写。

模板

文件	用途
templates/SKILL.md	Agent 技能/工具说明
templates/AGENTS.md	仓库级 Agent 说明（许多工具会读取此文件）
templates/CLAUDE.md	Claude Code 项目记忆
templates/cursorrules.md	Cursor 规则（安装时重命名为 .cursorrules）

每个模板只说明如何使用 DESIGN.md。将其中一个复制到你的项目中，并调整路径。现在每个模板都附带一个可执行的验证步骤——见下文。

使用检查器验证（CLI）

使用配套检查器确保新增颜色符合规范——扫描非预期颜色，并验证 WCAG 2.1 颜色对；还会返回供 CI 使用的退出码。检查器包含在此仓库中——使用 Node 18+ 即可运行，无需安装：

node cli/index.js --tokens DESIGN.md --target .

退出码为 0 表示检查通过；退出码为 1 表示存在非预期的十六进制颜色值或未通过的颜色对。添加 --apca 还可报告每组颜色对的 APCA Lc。源代码位于 cli/——将其接入 CI 步骤，让新增颜色先经过文件检查。

已经提取了颜色？

如果你是从 DevTools 检查或提取工具开始的，那么你的十六进制颜色列表还没有角色定义和测量结果。迁移指南将带你完成最后一步： docs/migration-extracted-css.md——从原始十六进制颜色 → 语义角色 → 已测量的颜色对 → 正式的 DESIGN.md，并附有真实的完整示例 （包括一组确实未通过的颜色对）。

常见问题

模板在哪里？ 在此仓库中，可免费复制。DESIGN.md 格式本身由 Google Labs 制定（Apache-2.0）。

这些模板能在 Claude Code 之外使用吗？ 可以。模板都是纯 Markdown： Cursor 使用 .cursorrules，Codex 和大多数 Agent 使用 AGENTS.md，支持技能的客户端使用 SKILL.md。

我需要同时使用技能和 MCP 服务吗？ 两者可以配合使用。该文件是团队发布的版本化契约；MCP 是实时测量工具，可验证颜色对，并按需获取最新调优的主题。

所有内容都免费吗？ 模板、Brand Theme Engine 和对比度检查器均可免费使用。MCP 服务按账户计量：Free 每天 5 次调用，Plus 每月 1,000 次，Pro 不限量。

说明与限制

• DESIGN.md 由 Google Labs 制定，并采用 Apache-2.0 许可，详见 google-labs-code/design.md。 ColorwayKit 并非该规范的作者——我们将内容导出为该格式。
• 该规范仍处于早期版本，并将自身部分内容描述为持续演进；组件令牌结构可能会发生变化。
• 对比度数值由工具自动计算，可作为设计参考，但不构成正式的无障碍认证。
• ColorwayKit 引擎仅处理颜色。生成文件中的字体、间距和圆角由你自行定义。

许可证

此仓库中的模板和示例可供你在自己的项目中实际使用。DESIGN.md 格式本身受其自身规范和许可证约束（见上方链接）。