agentleFS
wonderslifewonderslife/pdd-skills-v3/skills/core/pdd-design-spec/SKILL.md

pdd-design-spec

Skill15 starsChanged 28 days agoMITView on GitHub

生成界面设计规范(DESIGN.md)。在 PRD 与 specs 生成之后,把 PRD 第4章「界面原型」和 spec.md 第4/6章「前端页面设计/前端实现约定」中的散落约定,收敛成一份 AI 可读、可执行、可审计的设计契约。支持中文触发:界面规范、设计规范、UI规范、设计系统、DESIGN.md。

The file

Files
SKILL.md

PDD-Design Spec - 界面设计规范生成技能

核心概念

一句话:把"这个系统长什么样、怎么交互"从散落在 PRD 和 spec 里的碎片,收敛成一份放在仓库根目录、AI 编码 agent 每次都会读的 DESIGN.md。

为什么需要独立于 PRD 存在:

文档读者回答什么变更频率
AGENTS.md编码 agent怎么建(技术栈/目录/命令)低
PRD 第4章人这个页面要放哪些字段和按钮高(随需求变)
spec.md 第4/6章人 + 后端这个功能调什么接口、字段什么类型高
DESIGN.mdAI + 人全系统统一的颜色/字号/间距/状态/密度极低

PRD 回答"有什么",spec 回答"怎么调",DESIGN.md 回答"长什么样、什么感觉、什么规则"。三者正交,不能互相替代。

输入: PRD 第4章界面原型 | spec.md 第4章前端页面设计 + 第6章前端实现约定 | 技术栈(RuoYi/Element Plus 或前端框架) | 可选:领域预设 输出: ui/DESIGN.md(界面设计规范)| ui/page-{slug}.md(单页规范,按需) 不负责: 需求分析 / 接口设计 / 代码实现 / 原型图绘制

在流水线中的位置

PRD ──→ dev-specs ──→ specs/spec.md ──→ 【DESIGN.md】 ──→ generate/实现 ──→ verify
                                          ↑                    │
                                    本技能在这里        pdd-implement-feature Step 2 强制读取

消费闭环:本技能产出 ui/DESIGN.md 后,pdd-implement-feature(v2.1+)在前端编码前会强制读取并对齐。

触发时机:specs/spec.md 已生成之后、开始写前端代码之前。也可在项目任意阶段单独触发(如已有系统要补规范)。

可重复执行:DESIGN.md 是增量文档。需求变更时只需 diff 出新状态/新组件,补进对应章节,不需要重写。


一、与 PRD 第4章的映射关系(本技能的定位)

PRD 第4章是逐页列举,DESIGN.md 是横向收敛。同一批信息,两种切法:

PRD 第4章DESIGN.md 对应章节转换动作
4.1 页面列表不在 DESIGN.md(留在 PRD)—
4.2 页面说明§5 布局原则抽出共性布局骨架,而非逐页描述
4.3 界面线框图§4 组件规范从线框里反推"用了哪些组件、每个组件什么状态"
4.4 表单字段组件映射表§4 组件规范(表单族)归纳组件选型规则:什么时候 Select、什么时候 Radio、什么时候 TreeSelect
4.5 Options API 定义不在 DESIGN.md(留在 PRD/spec)—

判断准则:PRD 里"只对某一个页面成立"的内容留在 PRD;"对两个以上页面成立"的内容必须上升到 DESIGN.md。这条准则决定了 90% 的取舍。


二、生成流程

Step 0. 前置检查

  1. 定位 PRD:*.prd / *PRD*.md / my-feature.prd(与 gen-spec.mjs 的探测规则保持一致)
  2. 定位 spec:specs/spec.md
  3. 确认技术栈:读 .pdd/config.yaml 的 template 字段
    • ruoyi → Element Plus + Vue3,必须产出 §11 组件库映射
    • 其他 → 按实际 UI 库产出映射;无 UI 库则跳过 §11 但保留 §4

Step 1. 抽取现状(不要凭空设计)

先用脚本做确定性抽取,再由你组织成文。 状态枚举是最容易漏的环节,不要凭印象写。

node skills/core/pdd-design-spec/scripts/gen-design-scaffold.js \
  --prd <PRD> --spec <specs/spec.md> --out ui/DESIGN.md

脚本做三件事:

  1. 抽取状态枚举——从 PRD 的 EARS 需求、状态流转描述里抽(显式),再用语表兜底(标 vocabulary,需人工确认)
  2. 抽取页面清单 / 渠道 / 字段组件映射——只认表头严格匹配的 Markdown 表格,避免误匹配需求表
  3. 算法配色——语义组 → 组内变体 → 冲突顺延,保证产出天生能通过 check-design.js

不加 --out 时可用 --dry-run 只看统计、--json 看完整清单。

脚本产出的是骨架(含 TODO 与"待确认"占位),你在此之上做三件事:

  • 归纳布局类型:从页面清单归纳出列表页 / 表单页 / 详情页 / 看板页 / 配置页
  • 确认状态真实性:vocabulary 置信度的状态逐条核对,删掉误命中的
  • 补语义三列:状态表的"可编辑 / 可发布 / 谁可操作"

Step 2. 定状态机色板(必须早于定主色)

这是本技能与原版 awesome-design-md 最大的差异点,也是最有价值的一步。

设计系统的一致性瓶颈从来不在主色,而在业务状态怎么表达。所以顺序必须是:

业务状态枚举 → 每个状态的颜色 + 图标 + 是否可编辑 → 再定品牌主色

gen-design-scaffold.js 已按此顺序自动配色(语义组 → 组内变体 → 冲突顺延)。你只需核对:

状态颜色 token图标形状/附加标记权限(谁能改)

硬性要求:颜色不能是唯一编码。每个状态必须同时有颜色 + 图标/形状,否则色盲用户和黑白打印不可用。

语义组容量不足时:不要新增无关色相,沿 GROUP_CHAIN 降级到邻近语义组(info → accent → success),并在文档中说明理由。

Step 3. 定 token(YAML front matter)

按 references/token-spec.md 的命名规则写 front matter。核心原则:

  • 引用式而非硬编码:组件里写 {colors.primary},不写 #165DFF
  • 角色命名而非外观命名:写 state-rejected,不写 red-2
  • 状态色与品牌色分离:live 必须是独立命名空间,不与 primary 混用

Step 4. 定数据密度(后台项目必做)

按 references/density-spec.md 给出可测量的数字:一屏行数、行高、分页条数、操作列宽度、截断规则。

融媒体/巡检/审批这类后台,用户一天看 500 条记录。"好看"的优先级低于"一屏能看多少"。密度规范比配色规范更影响效率。

Step 5. 写组件规范(每个组件必须写全状态)

按 references/pattern-library.md 的组件清单,逐个写:rest / hover / active / focus / disabled / loading / error / 权限不足态。

缺任何一个状态,实现者就会自己发明一个,系统从此开始分裂。

Step 6. 写 Do's / Don'ts + 审计清单

Don'ts 必须是可机器判定的("不要用 primary 填充按钮" 可以判定;"要美观" 不可判定)。

Step 7. 输出

项目根/ui/DESIGN.md                    # 主产物
项目根/ui/page-{slug}.md               # 单页规范(仅当某页有超出全局的特例)
项目根/ui/design-audit-report.md       # 首次生成时的现状审计(见 Step 8)

目录约定:所有界面相关产出统一落在 ui/ 下,与 specs/、dev-specs/ 平级。

可选:若需 AI 编码 agent 在根目录自动发现设计契约,在 项目根/DESIGN.md 放一行指针:

# DESIGN.md 已移至 ui/ 目录
> 界面设计规范见 [ui/DESIGN.md](ui/DESIGN.md)

Step 8. 自检(必做)

node skills/core/pdd-design-spec/scripts/check-design.js <项目根>/ui/DESIGN.md

脚本检查 7 项:front matter 合法性 / 必需顶层键 / 裸 hex / token 引用完整性 / 状态色数量 / 状态色冲突(色相 × 明度双重判定) / 对比度。退出码 0 通过、1 严重、2 有警告。

再把不通过项按 references/audit-checklist.md 的 12 项写入 design-audit-report.md。


三、领域预设

技能本身通用,但不同领域的状态机差异极大。references/presets/ 下按领域提供预设,生成时按项目性质选用并改写(不是照抄):

预设适用提供什么
media.md融媒体 / 内容发布 / CMS稿件状态机色板、栏目色条体系、直播子系统、多渠道分发状态、内容模型映射

新增领域时只加 presets/{domain}.md,不改 SKILL.md。这是技能能跨项目复用的关键。


四、Guardrails / 质量护栏

必须遵守:

  • 状态色必须同时用颜色 + 图标双编码
  • 状态色只用于圆点/色块,不用于 12px 文字(高明度橙/绿做文字必然对比度不足)
  • 状态超过 9 个时,收敛成色族(≤8),靠明度差 ≥18 + 图标细分,不要靠挤色相
  • 每个组件必须写全 8 个状态(rest/hover/active/focus/disabled/loading/error/无权限)
  • 数据密度必须给出可测量数字(行高 px、一屏行数、分页条数)
  • 组件规范必须引用 token({colors.x}),禁止裸写 hex
  • 技术栈为 RuoYi 时,必须产出 Element Plus 变量映射表
  • 品牌主色不得用于业务状态(红不能既表示"加急"又表示"驳回")

避免事项:

  • ❌ 把 DESIGN.md 写成 PRD 第4章的复制品(逐页描述)
  • ❌ 只给色值不给角色("主色 #165DFF" 而不说它什么时候能用、什么时候不能用)
  • ❌ 用营销站那套大留白/大标题套后台(后台要密度,不要呼吸感)
  • ❌ 状态色超过 7 个且无分组(超过就要考虑合并或引入形状维度)
  • ❌ 只写正常态,不写空/错/加载/无权限
  • ❌ 引用第三方品牌色卡(Tailwind 的 blue-500 之类),必须自定义语义名

五、与其他技能协作

协作技能协作方式传入数据期望输出
pdd-generate-specSequential(前置)PRD 第4章 + spec 第4/6章页面清单、字段组件映射、按钮矩阵
pdd-baConsultation业务状态定义状态枚举全集
pdd-extract-featuresConsultation功能点矩阵页面归属与优先级
expert-vue3Consultation组件选型疑问Element Plus 组件能力边界
pdd-implement-featureSequential(后续)DESIGN.md实现时遵守的视觉契约
pdd-code-reviewerSequential(后续)DESIGN.md 的 Don'ts前端 PR 的视觉一致性检查

六、人工审核规范

审核节点:DESIGN.md 首次生成后、以及任何 token 级变更后 审核内容:状态色板是否覆盖全部业务状态 | 密度数字是否与实际屏幕匹配 | 组件状态是否完整 | 是否与技术栈 UI 库能力冲突 审核粒度:全量审核 front matter(token 是地基,错一处全局歪);章节正文可抽审 输出文件:review-design.md | 结果类型:passed / rejected / conditional


七、Iron Law / 铁律

  1. 状态优先于品牌:先定业务状态机色板,再定品牌主色。顺序颠倒会导致品牌色侵占状态语义,最终所有颜色都失去信息量。
  2. 一色一义:同一个色相在同一系统内只能承担一个语义。红色要么表示"危险/驳回",要么表示"直播/进行中",不能两者兼有。
  3. 双编码强制:任何状态表达必须同时具备颜色与图标/形状,禁止纯色编码。且颜色只能出现在色块/圆点上,不能作为 12px 标签文字色——高明度色做文字必然对比度不足。
  4. 色族优先于色相数量:状态超过 9 个时,不要新增色相(会把色相距离挤到 15° 内),而是收敛成 ≤8 个色族,用明度差 ≥18 + 图标区分。
  5. 引用不硬编码:组件定义必须引用 token,禁止裸写色值。这是"改一处全局生效"的前提。
  6. 密度可测量:数据密度必须写成数字(px / 行数 / 条数),禁止"紧凑""宽松"这类形容词。
  7. 状态必须闭环:每个交互组件必须写全 8 态,缺态即缺陷。
  8. PRD 只留个例:只对一个页面成立的约定留在 PRD,两个以上页面成立的必须上升到 DESIGN.md。

违规示例: ❌ 品牌主色是红色,同时用红色标记"驳回"状态 ❌ 状态标签只有背景色,没有图标和文案差异 ❌ 组件里写 background: #165DFF 而不是 {colors.primary} ❌ 写"列表页要紧凑"而不给行高 ❌ 按钮只写了默认态和 hover 态 ❌ 把 PRD 第4章逐页复制过来当成 DESIGN.md

合规示例: ✅ 品牌主色为蓝,业务状态独立成 state-* 命名空间,红色专属"驳回/失败" ✅ 每个状态标签 = 色块 + 图标 + 文案("● 已驳回 ⚠") ✅ 组件写 backgroundColor: "{colors.primary}" ✅ 写"列表默认行高 40px,1080p 下一屏 ≥15 行,分页默认 20 条" ✅ 按钮写全 8 态,含"无权限时置灰 + tooltip 说明原因" ✅ 从 PRD 的 12 个页面里归纳出 5 类布局,写进 §5


八、Rationalization / 理性化对照

常见自我说服与反驳:

自我说服反驳
"项目还早,先不定规范,边做边定"边做边定的结果是每个模块各定一套,后期统一成本是现在的 10 倍。规范只需要 1 小时,返工需要 1 周。
"我们有 Element Plus,默认样式够用了"Element Plus 默认样式只保证"不难看",不保证"你的系统一致"。状态色、密度、业务语义它一概不管。
"设计规范是设计师的事,开发不用管"这份文档的读者是 AI 编码 agent 和新加入的开发。它是一份工程契约,不是视觉稿。
"状态色用红黄绿就够了"红黄绿只能表达 3 个态,融媒体稿件有 9 个态。要么扩色板,要么引入图标维度,二者必选其一。
"写这么细,需求一变就全废"变的是 PRD 第4章(页面与字段),DESIGN.md 定的是 token 与规则,变更频率低一个数量级。这正是要拆开的原因。
"先写一版,以后再说"可以,但必须在 front matter 里标 version: 0.1 并写明"未定项清单",否则未定项会被实现者各自填补。

九、Red Flags / 红旗警告

Layer 1: 输入检查

  • INPUT-DS-001: PRD 第4章界面原型为空或只有模板占位 → 🔴 终止,提示先完成界面原型
  • INPUT-DS-002: spec.md 缺少第6章前端实现约定 → 🟡 降级:仅基于 PRD 生成,在报告中标注"组件映射未经 spec 校验"
  • INPUT-DS-003: 无法确定技术栈/UI 库 → 🟡 跳过 §11 组件库映射,保留 §4 抽象组件规范
  • INPUT-DS-004: PRD 中状态枚举缺失或只写"正常/异常" → 🔴 回退到 pdd-ba 补状态机,不得自行编造状态

Layer 2: 执行检查

  • EXEC-DS-001: 品牌主色与任一业务状态色同色相 → 🔴 冲突,必须改其一
  • EXEC-DS-002: 状态色纯色编码无图标/形状 → 🔴 补第二编码维度
  • EXEC-DS-003: 组件定义出现裸 hex 而非 token 引用 → 🔴 改为引用
  • EXEC-DS-004: 数据密度写形容词而非数字 → 🟡 改写为 px / 行数
  • EXEC-DS-005: 组件缺少 disabled / loading / error / 无权限 任一状态 → 🟡 补齐
  • EXEC-DS-006: 状态色数量 > 7 且未分组 → 🟡 引入分组(流程态/终态/异常态)或合并
  • EXEC-DS-007: 直接套用营销站风格(大留白/超大标题)到后台 → 🔴 按 density-spec 重写布局章节

Layer 3: 输出检查

  • OUTPUT-DS-001: ui/DESIGN.md 未落在 ui/ 目录 → 🔴 移动到 ui/,与 specs 平级
  • OUTPUT-DS-002: front matter 非法 YAML(未加引号的 hex、缩进错) → 🔴 修正后重生成
  • OUTPUT-DS-003: 缺 Do's and Don'ts 章节 → 🔴 补齐,且每条必须可判定
  • OUTPUT-DS-004: 缺审计清单章节 → 🟡 补 references/audit-checklist.md 的 12 项
  • OUTPUT-DS-005: 技术栈为 RuoYi 但缺 Element Plus 变量映射 → 🟡 补 §11
  • OUTPUT-DS-006: DESIGN.md 与 PRD 第4章字段/页面数量不一致 → 🟡 记录差异,以 PRD 为准并说明

处理流程: 🔴 CRITICAL → 立即停止,报告问题详情,等待指示 | 🟡 WARN → 记录警告,尝试自动修复,在最终报告中标注 | 🔵 INFO → 记录信息,正常继续

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.