第 一 节为什么要读这篇
传统规范的问题不是它写得不够全,而是它从发布那一刻起就在变旧。
过去十年,设计规范的主要载体是 Markdown、Figma、Notion。设计师写下按钮的圆角、间距的刻度、色彩的语义,然后发给工程师、发给新人。在"人读规范,人写代码"的时代,这是 OK 的。
但 AI 进入设计协作后,游戏变了。AI 读规范不是"阅读",而是"推断"——它把你写的文字、截图全当作输入,合成出它以为"你想要的"方案。规范对 AI 不友好,它会自己补全,而补全结果常常看起来合理,但完全不对。
怎么把规范从"给人读的文档",升级成"给 AI + 人一起用的 skill"。
并且,怎么让它不是发布就死,而是随团队一起长大。
设计规范不是文档,
是活系统。
第 二 节一个关键认知:它是路由器,不是百科全书
很多人对 skill 的第一反应是:"把所有规范塞进 SKILL.md,模型读完就什么都知道了"。这是错的。
模型的注意力有限。一份 3000 行的 SKILL.md 会消耗大量上下文,而且模型在长文档里容易走神——它可能记住了开头的色彩 token,但忘了中间的按钮规范。
好的 skill 不是把知识塞满,而是让模型在需要时能找到正确的那部分。
这个认知是后面所有结构设计的起点。如果你把 skill 当百科全书做,后面所有的最佳实践都会跑偏。
第 三 节四档演化阶梯:你的团队在哪一档
从单文件 Markdown 到能自我演化的双 skill 系统,设计规范 skill 有四档清晰的成熟度。
判断自己在哪档,靠三个维度:结构、规则、演化。对照下面四档,你应该能 30 秒内给自己团队定位。
L1/L2/L3 都还是静态系统——你写一次,它就这样了。
L4 是活系统——它会随着团队使用、随着 bug 出现、随着审查发现盲区,自己变得越来越准。这是 L3 到 L4 的本质跃迁。
大多数团队的规范,
从发布那一刻
就开始变旧。
第 四 节7 个部件:一份能用 skill 的构成
一份能达到 L3 的 skill,由 7 个部件组成。前三个是核心(骨架),后四个是支撑(血肉)。
最核心的三个:硬规则 · 路由 · 触发词
硬规则是 skill 的骨——没有它,AI 会软瘫,产出靠运气。软描述("按钮要美观")要换成可验证的断言("按钮不能用 dashed 边框")。
| 软描述 · 难以执行 | 硬规则 · 可验证 |
|---|---|
| ✗"色彩要协调" | ✓ALWAYS 状态标签使用语义色板 |
| ✗"间距要合理" | ✓ALWAYS 使用 16/24/32 的间距 token |
| ✗"页面要简洁" | ✓NEVER 卡片内使用 dashed 边框 |
路由是 skill 的血脉——决定 AI 加载什么。没有它,要么全读(爆 context),要么不读(错过关键规则)。
触发词是 skill 的门牌——决定 AI 在什么时候用这份 skill。宁可多也不要少,漏一个高频触发词,skill 就在那个场景下永远不会被激活。
第 五 节双 skill 的文件结构
讲清楚机制之前,先看一眼 skill 长什么样 —— 41 个文件,两棵树。
KED 系统由两个独立 skill 组成:ke-style(生成,33 个文件)和 ke-review(审查,8 个文件)。先有这张结构图,后面讲机制时才能对号入座。
核心文件一览:是什么、怎么用、怎么迭代
41 个文件里,大部分是具体规范文档。下面 11 个是关键机制文件,搞清楚它们,整个系统就通了。
| 文件 | 归属 | 是什么 · 怎么用 · 怎么迭代 |
|---|---|---|
| SKILL.md | ke-style | 主路由器。AI 每次对话先读它,根据用户请求里的触发词决定加载哪些 references。每次新增 references 或调整路由策略时迭代。 |
| design-tokens.css | ke-style | 数值真源。所有颜色、间距、字号 token 的唯一来源。所有组件定义都 reference 这里的变量。改 token 时只动这一个文件,全系统生效。 |
| product-lines/*.json | ke-style | 产品线差异层。贝壳和 Link 共用大部分规范,只有品牌色等少数差异。每条产品线一份 JSON,运行时动态覆盖 token。新增产品线时在这里加新 JSON,不动其他文件。 |
| page-shells/*.json | ke-style | 页面骨架数值。每种页面类型(list/detail/form 等)的关键数值(栅格、间距、导航高度)。AI 做页面时先读骨架 JSON,再做内容。稳定,极少变。 |
| GLOSSARY.md | ke-style | 术语字典。定义"卡片"、"面板"、"区块"这类易混术语的唯一含义,防止同义词野蛮生长。任何术语争议发生时迭代,保持权威性。 |
| meta-rules.md | ke-style | 规则的规则。写清楚"什么情况下可以新增硬规则"、"什么情况下必须拒绝"。这是 skill 的免疫系统。极少动,一旦动了是结构性升级。 |
| update-boundary.json | ke-style | 资产边界契约。声明哪些文件是稳定区、哪些是演化区,给 AI 明确"你可以动什么、不可以动什么"。新增文件类型时更新。 |
| SKILL.md | ke-review | 审查路由器。AI 拿到一段代码或设计,先读它,决定调用快速筛查还是完整审查,走不同路径。跟着审查策略迭代。 |
| quick-gate.md | ke-review | 快速筛查规则。20 条高频违规的二元判断,10 秒出结果。高频迭代,发现新常见违规就加。 |
| case-studies/* | ke-review | 飞轮燃料。每个真实 bug 都在这里留一份案例,四要素:现象/根因/修复/教训。审查时 AI 会检索类似 case。每周持续沉淀,这是 skill 越用越准的核心来源。 |
| compatibility.yml | ke-review | 双 skill 桥梁。记录 ke-review 能审查哪些版本的 ke-style、哪些规则需要 skip。ke-style 升级时,这里决定审查 skill 是否需要跟进。ke-style 每次大版本升级时迭代。 |
如果你只想理解核心,看这四个文件就够了:SKILL.md (ke-style)、meta-rules.md、case-studies/*、compatibility.yml。
下一节会讲这四个文件在三个机制里具体怎么运转。
第 六 节让 skill 活起来:三个核心机制
L3 到 L4 的跃迁,不是加更多文件,而是引入三个新机制:双 skill 对偶、元规则门禁、case-studies 飞轮。
这三个机制共同作用,才能让 skill 从静态变成活的。缺任何一个都不行。下面一个个拆清楚:它是什么、怎么建、AI 调用时怎么用。
机 制 一 双 skill 对偶 · 让规范自带审稿人
是什么
把规范拆成两个独立 skill:ke-style 管生成(0 到 1 做页面),ke-review 管审查(1 到 0 挑违规)。两者独立演化,互相校验。
为什么要拆?因为"生成"和"审查"的思考方式完全不同——生成需要开放联想,审查需要严格断言。放在一个 skill 里,AI 会把两种模式混起来:审查时心软放过,生成时过度自我审查。拆开,各自专注,都能做到更极致。
怎么建
两个 skill 有各自的文件树(见上一节),但它们不完全独立——通过一份 compatibility.yml 保持协同:
# ke-review/compatibility.yml
compatible-with:
# 完全兼容,所有规则都能用
- ke-style: 2026.05.06
status: native
skip-rules: []
# 向后兼容,跳过新增的 2 条规则
- ke-style: 2026.05.04
status: backward
skip-rules: [NEW-24, NEW-25]
# 部分兼容,跳过所有破坏性变更
- ke-style: 2026.04.*
status: partial
skip-rules: [NEW-*, BREAKING-*]这份文件是双 skill 的合约:当 ke-style 升级到新版本时,ke-review 不会立刻失效,而是按兼容策略优雅降级。
AI 调用时怎么用
场景:用户给了 ke-review 一段代码,想审查是否符合规范。AI 的执行流程:
- 读
ke-review/SKILL.md,看到入口规则 - 从代码推断出使用的 ke-style 版本(看 tokens 变量命名规律)
- 打开
compatibility.yml,找到对应版本的skip-rules - 执行审查时,在规则列表里剔除 skip 掉的规则,不做误判
- 按剩余规则逐条检查,产出违规报告 + 修复建议
这样即使 ke-style 升级了,历史代码也能被正确审查——不会因为版本错位而被一堆新规则"误杀"。
机 制 二 元规则门禁 · 防止 skill 被自我污染
是什么
skill 活得越久,越容易被错误规则污染。最常见的污染:有人看到一个 bug,反推出一条新规则,塞进 skill。但这条"规则"可能只是对这个特定现象的过拟合,换个场景就错了。
元规则是规则的规则——它不规定具体做什么,而是规定"什么情况下可以新增规则"。就像宪法和法律的关系:法律一直在变,但新法必须符合宪法精神。
怎么建
在 ke-style/references/meta-rules.md 里写清楚规则升级的准入条件。以下是我们的 MR-01(第一条元规则),精简摘录:
# MR-01 · 规则变更必须有规范参考
准入条件(必须满足其一):
① 外部权威规范:W3C、CSS、iOS HIG、Material Design 等
② 内部资产真源:design-tokens.css、product-lines/*.json
③ 历史通过审查的 case(且归类为元问题,非孤立事件)
拒绝条件(出现任一即拒绝):
① 依据是"AI 的视觉直觉"
② 依据是单一用户的反馈
③ 依据是"我觉得这样看起来更好"
④ 依据是"某某公司是这么做的"
落地方式:
每次 PR 新增 NEVER/ALWAYS 规则时,
PR 描述里必须写清楚"依据是什么"。
依据不符合准入条件,PR 不能合并。AI 调用时怎么用
场景 1 · 用户在 ke-style 里想加一条新硬规则:
- 用户说:"给我加一条规则,卡片间距不能用 12px。"
- AI 读
meta-rules.md,触发门禁检查 - AI 反问:"这条规则的依据是什么?design-tokens 里没有 12px 这个值,但能否告诉我是来自 W3C 规范、业务真源还是历史 case?"
- 如果用户提供了依据(如"design-tokens 定义的间距阶梯是 4/8/16/24,12 不在其中"),AI 接受并写入
- 如果没有依据,AI 拒绝升级,给出改进建议(先在 case-studies 里沉淀观察几周)
场景 2 · ke-review 在审查时发现违规:AI 给出的修复建议必须标注"依据 meta-rules MR-01 允许的参考来源",否则建议本身就被元规则挡回。
我们见过一份"L3+"的 skill,运行半年后,80 多条硬规则里有 20 多条是错的——都是当时顺手加的、没依据的过拟合规则。后期清理规则的成本,远大于当初写门禁的成本。
元规则是 skill 的免疫系统。没有它,飞轮转得越快,skill 污染得越深。
机 制 三 case-studies 飞轮 · 让 skill 自己学习
是什么
审查发现的每个问题,不是修复完就结束——要把它转化成一条永久的 case,存进 case-studies/。积累到一定数量,类似的 case 会合并成一条新规则,写进 ke-style。
这就是飞轮:真实审查 → 案例沉淀 → 归类分析 → 规则升级,每转一圈,skill 就学会一类新的识别能力。
怎么建 · case 文件的标准结构
每个 case 是 case-studies/ 下的一个独立 markdown,必须包含四要素:
# CASE-04 · home-indicator 放在可滚动容器里
## 现象
移动端原型里,屏幕底部的 home-indicator 会跟随
内容滚动,离开了屏幕底部固定位置。
## 根因
父容器 overflow: auto 导致 absolute + bottom: 0
的定位上下文失效。home-indicator 以滚动容器
为定位基准,而不是 viewport。
## 修复
把 home-indicator 提到滚动容器外层。
正确的 DOM 结构:
.page
├ .scroll-container (overflow: auto)
│ └ ...内容...
└ .home-indicator (absolute + bottom: 0)
## 教训
absolute + bottom 定位的元素,父链上不能有
overflow 不为 visible 的容器。这是 CSS 层叠上下文
的通用规则,不只 home-indicator 会踩。四要素缺一不可:
- ├─ 现象:可复现的、可观察的问题描述(不是"感觉不对")
- ├─ 根因:底层技术原因(为什么会出问题)
- ├─ 修复:具体代码/结构改法(别人能直接照抄)
- └─ 教训:抽象出的通用规则(这是飞轮燃料)
AI 调用时怎么用 · 飞轮的完整转动链路
把抽象的四节点,对应到文件层面:
- 真实审查 ·
ke-review在真实工作中发现违规。审查者(通常是设计师 + AI 一起)确认是 skill 规则没覆盖。 - 案例沉淀 · 在
ke-review/case-studies/新建一个 CASE-XX.md,填好四要素。这一步门槛很低,可以先粗略记,回头再补全。 - 归类分析 · 积累一批 case(通常 3-5 个)后,看它们是否属于同一类元问题。如果是,就具备了"升级为硬规则"的条件。
- 元规则门禁 · 新规则提交时,检查依据是否符合
meta-rules.md的准入条件。这里 case-studies 就是准入条件之一(条款 ③)。 - 规则升级 · 通过门禁的规则写进
ke-style/SKILL.md的 NEVER/ALWAYS 列表。同时ke-review/quick-gate.md补一条对应的扫描规则。
一圈转下来,一个真实 bug 变成了两处规则变更:ke-style 里禁止生成这种代码,ke-review 里自动识别这种代码。下次再有人踩坑,两个 skill 会在第一时间拦下来。
不是每次发现 bug 都要立刻升级规则。案例先沉淀,观察 2-4 周,看是否重复出现。孤立 case 不升级(会过拟合),反复出现的才归类升级(是元问题)。
这也是元规则门禁条款 ③ 要求"归类为元问题"的原因。
三个机制的关系
三个机制不是独立的,它们构成一个自我进化的闭环:
- 对偶 提供发现能力 —— ke-review 在真实工作中发现违规
- 飞轮 提供学习能力 —— 违规转化为案例,案例积累为规则
- 门禁 提供免疫能力 —— 防止过拟合规则污染系统
三者缺一不可。有对偶但没飞轮,发现的问题不沉淀,只能零散修复;有飞轮但没门禁,规则会被错误样本污染;有门禁但没对偶,没人发现问题,门禁守着空城。
飞轮每转一次,
skill 就变准一点。
第 七 节一个真实案例:飞轮如何转动
讲完三个机制,来看它们在真实工作里怎么配合。下面是内部真实发生的一个 case——一个小 bug 驱动飞轮转动一整圈,最终沉淀为一条新的硬规则。
移动端原型里,home-indicator(屏幕底部的"小黑条")被放在了可滚动容器里面——滚动时跟着内容一起动,离开屏幕底部,违反 iOS/Android 原生行为。
一个真实 bug,变成了一条会持续生效的规则。飞轮转动一圈花了一周。下次再有人踩中类似陷阱,skill 会在第一时间拦下来——这就是活系统的意义。
第 八 节建议的演化节奏
从零到 L4 不用一次完成——分三个阶段,每阶段 2 到 3 个月,循序渐进。
关键不是"多快做完",而是每个阶段都有清晰的完成标志,确认到位了再进入下一阶段。下面每个阶段都给出:目标、关键动作、常见卡点、完成标志、升档信号。
- 写
SKILL.md骨架,只含 frontmatter + 路由表 + 最基本速查 - 建
references/目录,先写 3-5 个核心页面类型(list、detail、form) - 定
design-tokens.css作为数值真源,所有颜色间距走变量 - 触发词至少 15 个,覆盖团队常说的场景话术
- 不急着写硬规则——这阶段先让 AI 能"做对大方向"
- 从 真实产出的违规 里归纳出 20 条左右 NEVER/ALWAYS 硬规则(不要凭空想)
- 加
CHANGELOG.md+ 版本号(YYYY.MM.DD 格式) - 路由机制升级为三层:骨架层(互斥)+ 通用层(伴随)+ 叠加层(按需)
- 写"输出前自检清单",让 AI 产出后自己勾选 30 条
- 开始记录
case-studies/—— 即使还没 ke-review,也先沉淀案例
- 拆出
ke-review作为独立审查 skill,不在 ke-style 里做审查 - 建
compatibility.yml,记录版本兼容关系 - 写第一版
meta-rules.md,至少有 MR-01 规则升级门禁 - 把之前沉淀的 case-studies 转化成第一批规则升级
- 建立每周 review 机制:review 新 case、判断是否归类为元问题、决定是否升级规则
不要跳阶段。L1 直接往 L4 冲,十有八九会退回 L2 从头来过——因为骨架没搭稳,上层机制无处附着。
每个阶段的"完成标志"比"时间"更重要。如果某个阶段 3 个月还没到位,说明前一个阶段的骨架没打牢,回头去补。
结 语规范不是交付物,是旅程
读到这里,应该明白这篇文章的核心观点了:
规范不是一份交付物,是一段旅程。
做 L1 的单文件 Markdown 也行,做 L4 的活系统也行——重要的是,你知道自己在哪一档,知道下一档是什么样子,知道怎么走过去。
三件事值得一直记住:
希望这份速览,让你在做自己团队的 skill 时能少走一些弯路。