kero-system 的核心主张是：项目的设计系统应当是一个“技能”，而不是一份文档。它存放在项目内部，agent 能自行找到它，并且它的优先级高于代码——当某个界面与它不一致时，被修正的是界面。
存放位置
它位于所用 agent 的项目技能目录中：Claude Code 使用 .claude/skills/<project>-design/SKILL.md，其中 <project> 是项目短名的小写形式；Codex 使用 .agents/skills/；Cursor 使用 .cursor/skills/。当多个 agent 共用同一项目时，只保留一份真实副本；那些把链接变成静默副本的工具会留下两个文件，从而逐渐产生分歧。
技能描述中会列出所有触发条件：触及任何界面、组件或 token，选择颜色、字体、间距、图标、动效、焦点或状态，以及在界面被宣布完成之前。
旧的 DESIGN.md 仅作为历史保留，并在首行声明它不再是来源。
取值来源
来自正在运行的代码：全局样式表、主题、布局与基础组件。描述实际存在的内容，而不是原本意图的内容。
当代码尚不存在时，来自参考的 design.md 与 tokens。同时写明哪些值仍未确认。
界面请求的是角色，而不是颜色。当调色板存放在变量中时，尝试一套新配色只需改一个文件。
章节结构
按项目需要选用以下章节，并保持此顺序。每条规则用一行写明其理由。
产品在屏幕上的形态：它有哪些界面/表面，谁在什么条件下使用每一个。
品牌：只属于本产品的那一个标志性动作，以及它被允许出现的位置。
颜色：角色、每个表面上文字的可测量规则、颜色该出现在哪里以及绝不出现的地方。
字体与数字：字体、字号层级、字重、承载数字的字体（每个数字可区分，需要比较数值时使用等宽数字）以及正文的最大宽度。
间距、形状与深度：间距刻度、圆角刻度及嵌套规则（内圆角等于外圆角减去内边距），以及高度/阴影 token，全部从同一方向打光。
图像、图标与标记：统一的一套图标集、跟随相邻文字的字号、第三方 logo 与照片的摆放方式。
导航：什么保持常驻、什么折叠、每个设备上主操作位于何处。
动效：什么会动、持续多久、使用哪条曲线，以及在减少动效设置下的表现。
焦点、键盘与触控：每个表面的焦点样式（文本框显示其光标）、点击区域、缩放保持自由。
状态：每个加载数据的视图的加载、空、稀疏、密集与错误状态。
文案：语域、语言、单位，以及界面绝不对自身说的话。
自动拒绝：使用者一眼否决的内容，每条附上其给出的理由。
项目陷阱：已经付出代价的 bug 与误读，避免重复付出。
待决事项：使用者尚未决定的内容。agent 不代为决定这些。
宣布完成之前：一份审计无法回答的简短问题清单。
保持其真实有效
来自使用者的每一次纠正都会成为第 12 或第 13 节中的一条规则，写成带理由的原则，而不是一句引用。
可度量的规则同时写入 kero-audit.json（间距刻度、行宽、最小文字、图标尺寸），从而不再依赖有人去阅读它。
当代码与技能不一致且代码正确时，在同一次变更中更新技能。
对项目技能而言，篇幅长是可以的，因为它承载的是关于某一个产品的事实。通用工艺则留在 badesign-skill 中。