design-md

design-md · 可追溯的项目设计规范

让后续实现者知道应遵循哪些视觉与交互规则。文档描述有依据的设计约束；代码现状、网站重建结果与新设计提案不能相互冒充。

确定范围与产物

输入	处理方式	默认产物
项目仓库	提炼生效的设计约束，或更新已有规范	目标产品现有设计文档；没有时用产品根目录 DESIGN.md
网站 URL	观察并重建该网站可见的设计语言	工作区 docs/design/<站点>-design-draft.md，标为重建草稿
用户明确接受的设计决策	按已确定的范围纳入规范，保留决策来源	对目标规范的局部更新

先确定目标产品、页面范围、输出位置及是否仅做分析。用户指定的位置优先；外部网站草稿不能覆盖当前产品的规范。多产品仓库仅在目标确实不明时追问。

默认只修改选定设计文档。用户只要分析时在对话中交付；已有继续实现的授权则在文档交接后继续原任务，不把本技能边界当成停工理由。

新风格探索由 design-reference 类流程处理；代码抽取由 extract 类流程处理。它们不是运行依赖。Portal 初始化已有 xgent-init 模板时保留其产品边界，不替换成通用风格。

1. 收集能约束实现的证据

**仓库输入：**先读现有规范与用户明确决策，再读当前产品实际使用的主题、token、共享原语及代表页面。沿导入、样式入口或运行结果确认来源生效；未接入的旧目录、展示 demo 和未来方案不当作当前事实。

可用 Phoenix CLI 时，运行 phoenix-ui context --target <明确目标> --json，先核对 projectRoot、target.path 与适用产品；status: selection_required 时确认 target.candidates，不能取第一个候选。读取 product、design、surfaceBrief 的原始 body 和 provenance 的路径、section、hash、显式/继承关系。parseCoverage 中 coverage: partial 只说明有限解析；普通 Markdown、未支持的 YAML、主题和响应式规则仍按原文核实。conflicts 逐项处理，空数组不证明正文没有矛盾；missing 不补模板值。CLI 缺失或输出不可用时，根据明确目标直接找产品及适用仓库的原文件，不自动安装工具，也不声称加载了 profile。

读取 JSON 时，仅当 surfaceBrief.status: accepted 且 usable: true，才把原 brief 在适用目标内的方向视为已接受；核对 path、sha256、acceptedSha256 和 acceptedDecision。present 只是未接受提案；stale、有接受记录的 missing 或 ambiguous 保留原接受来源，核实漂移、缺失或候选，不按修改时间替换、自动重新接受或改抽方向。无 CLI 时从原 brief 核实适用目标与真实接受决定，仍可沿用方向，不声称机器映射已校验。

defaultAdvice 是独立的 generic 流程建议，不代表 profile 已启用，不提供缺失设计值。仅 profile.status: enabled 表示项目显式选择了该版本；其规则仍为 advisory。核对 profile.source、version、definitionSha256、可选的 acceptedDefinitionSha256 及 tokenBindings 的原规范路径/hash；present 绑定也要追踪原 token 引用，unresolved、无效或循环引用不能用模板色值填补。version_mismatch、definition_mismatch 或 profile_definition_mismatch 冲突只给升级候选；upgrade.comparison: unavailable 时须找原定义才能说明差异，不能编造 diff 或自动接受、改配置。

按 precedence 核对当前用户决定、冻结单元目标/已接受项目规范、已选择 profile、工具默认建议；这是裁定政策，context 没有验证正文冲突或改变目标。当前决定与冻结目标矛盾时明确变更范围并取得决定；profile 规则只有被接受为项目规范后才可参与新目标，不回套已冻结目标。规范写入仍遵循本 skill 的授权与证据规则；Phoenix document 请求也按同一边界处理。

检查构建品牌、租户配置和运行时注入是否覆盖样式变量。有覆盖链时记录默认值与覆盖范围；只读到基础 CSS，不能声称所有部署和租户最终使用同一个值。

区分两种权威：规范表达「应该如何」，源码和运行结果表达「目前如何」。实现不符时报告偏差；只有本次授权或明确取代旧约定的证据才能改写规范。重复出现的硬编码值是模式线索，不自动获得正式 token 或品牌意图的地位。

**URL 输入：**查看真实渲染、DOM、计算样式和加载的 CSS。根据请求覆盖桌面、移动端及相关主题、组件状态；只看一个页面的规则限于该页面，跨站规则需在不同模板上核对。精确数值来自实测或对应样式声明；由截图估计的值不写进正式 token。

无法渲染时可记录已读的公开说明、截图观察和缺口，交付有限分析或有明确标记的草稿。没有精确数值不妨碍描述可见结构；不能声称已提取完整规范或验证交互。拿到源码时优先追踪代码，网页补充实际呈现。

为准备写入的规则保留最小证据：规则或值、来源位置、适用页面/组件、主题/视口/状态、证据类型。来源可为文件行号、URL 与元素，或用户已接受的决定；记录在本轮工作记录或交付说明中，不强制另建台账。

2. 筛选与表达

• 写能改变实现选择的规则：颜色的用途、字体角色、布局密度、主题切换、组件变体及必要交互状态。不要把组件清单或所有 CSS 值搬进来。
• 复用有依据的 token 名、层级、单位和语义。确需映射到另一格式时保留映射来源；重建名只表示草稿中的观察角色，不声称是原站内部命名。
• 只纳入已观察或已规定的主题、状态与断点。保留全部已知模式的差异，不靠机械反色补 dark，也不为凑齐字号/间距阶梯生成数值。
• 只把有明确依据的限制写成禁止项。审美偏好、推测的品牌性格和待接受建议留在交付说明中。
• 未知部分省略或说明范围不足，不用默认品牌色、组件库惯例或外部模板填空。

3. 写入或更新

沿用已有文档结构和项目契约；无实质变更则保持文件不动。新建时从产品范围、视觉规则及必要组件指导开始，只添加有内容的部分。

已接受 brief 只提供其明确范围内的设计决定；原文漂移、缺失或多方向冲突先核对接受来源，不重新接受。用户决定与已冻结单元目标矛盾时，明确需变更的基线并取得决定，不能借规范维护或 profile 升级改写旧目标。

需要机器可读 token、Google DESIGN.md 格式或导出时，读 格式与验证。纯 Markdown 项目不必迁移格式；已有 YAML 也不能为了过工具检查而删掉设计信息。

同一文件同时含规范与有限观察时，明确标出观察范围。网站重建草稿在开头说明输入 URL、采样范围和未知项；未经用户接受不自动升级为当前产品规范。草稿供当前产品参考时，可单列一节「对当前产品的借鉴」：把观察到的原则对应到现有规范的角色或 token，标出冲突和待决定项；这一节是建议，不写成原站事实或当前规范。证据较多时在交付说明中集中列出，避免正文被调查过程淹没。

4. 验证与交付

1. 回读每条新增或变更的规则，核对来源、适用范围与主题/状态；抽查代表消费者是否实际使用所引 token 或原语。
2. 检查 YAML 可解析、token 引用可解析、相对链接可用；有既定校验器或导出要求时执行相应检查。工具不支持的部分如实报告，不能把退出成功当作语义完整。
3. 对照修改前后，保留未被取代的约定，单列实现偏差和不能确认的范围。文档更新不等于产品样式已经修复。
4. 回复说明目标与模式、文件或无变更结果、证据、变化理由、检查结果与限制。未跑浏览器或导出时明确标记；仅做源码核查不宣称视觉一致性通过。

维护本 skill 时使用 行为场景，普通文档任务无需加载。