构建 AI 能用好的设计系统，并检查 AI 做出的组件

## 改动前先查清哪些包负责组件和文档 将设计系统视为共享的产品契约，而不是视觉片段的集合。在进行任何变更之前，先确定哪些包分别负责组件、文档、示例、预览界面、测试工具和迁移实用程序。 以仓库的当前分支作为可用 API 和约定的权威依据。不得根据通用的 Web 平台知识、其他分支或更新的库版本推断支持情况。除非任务明确变更工具链，否则应保留已配置的包管理器、运行时、模块格式和测试运行器。 ## 开始前先读当前分支的文档和组件清单 在处理组件之前： 1. 阅读适用于目标的仓库指令和包指令。 2. 查看本地命令行帮助，并列出可用的文档主题。 3. 加载设计原则、设计令牌、主题规则和组件清单。 4. 当任务涉及布局而非单个基础元素时，查看页面模板。 5. 阅读目标组件的当前 API、变体、组成结构、示例和约束。 生成的文档和受支持的 API 可能因分支而异，因此应在每个分支上重复此初始化流程。升级设计系统依赖项后，应先运行仓库的迁移实用程序，再进行无关的手动编辑。 ## 同时更新文件开头的说明和组件文档 维护两个互为补充的文档层。在每个源文件的头部放置简洁的输入、输出和架构位置元数据。将详细的属性、功能、示例、无障碍说明和组合指引保存在由组件负责的文档文件中。 实现发生变化时，应同时更新这两个文档层，并遵循用于标识关联文件的同步标记。使用渲染器实际支持的文档格式；例如，当带语言标记的示例围栏会破坏当前的自动文档解析器时，应使用不带语言标记的围栏。不要因为源代码语法有效就假定文档能够正确显示，而应验证渲染结果。 ## 记录样式工具真正支持哪些 CSS 功能 记录样式引擎版本，以及它对 @ 规则、伪类、伪元素、复合选择器、值、动画、变量、主题、动态值和条件选择器的已验证支持情况。区分受支持的语法与能够编译但会生成无效或不可用 CSS 的语法。 当矩阵确认支持某项能力时，优先采用 CSS 原生方案。常见候选项包括媒体查询、特性查询和容器查询；起始样式；作用域；交互伪类和结构伪类；生成内容伪元素；现代颜色函数和尺寸函数；过渡；以及关键帧。不得仅仅因为旧版能力表中没有某项功能，就构建 JavaScript 绕行方案。 ## 把悬停和聚焦效果限制在各自的组件内 通过样式引擎支持的条件选择器机制来表示祖先、后代和兄弟元素的状态。当该机制需要标记时，应把标记应用到实际的祖先元素，并将标记定义放在负责该行为的组件附近。 对表单控件及其他嵌套的交互元素使用组件作用域标记。当外层弹出框、面板或容器可能把悬停或聚焦状态泄漏到控件中时，绝不能使用全局默认标记。遵守选择器契约，例如祖先条件只能使用伪选择器；也不要模拟尚未支持的 CSS 嵌套。 使用悬停能力媒体查询保护仅用于悬停的效果，避免触摸设备继承无法解除的交互状态。键盘聚焦和禁用状态的行为应独立于悬停状态加以保留。 ## 布局和动画用 CSS 实现，而不是 JavaScript 在获得支持时，直接使用网格、带间距的弹性布局、宽高比、溢出控制和滚动条属性。对于随组件容器变化的响应式行为，应优先使用容器查询，而不是通过观察器测量元素；对于斑马条纹，应使用结构伪类，而不是基于索引的 JavaScript。 使用起始样式支持来实现进入过渡，而不是组合状态管理和动画帧编排。通过样式引擎的回退抽象表达有顺序的 CSS 回退方案，而不是手动检测运行时。只有在生成的 CSS 已经通过受支持浏览器集合的验证时，才使用专用定位能力。 ## 让链接和主题可以替换，使用方无需复制组件 通过带类型的样式函数传递依赖运行时的值，而不是使用内联样式。通过系统的样式属性机制组合条件样式，而不是临时切换类名。将主题变量和主题创建逻辑放在编译器要求的文件类型中，并在有助于验证时使用带类型的变量或编译期常量。 通过可注入的链接抽象渲染导航，而不是硬编码锚点元素。这样，使用方无需分叉组件就能提供自己的路由器。遵守仓库的资源、字体、公共路径和主题提供器契约，使打包后的组件保持可移植性。 ## 测试 AI 能否正确做出组件，包括长对话后期 衡量代理指引是否有助于模型生成有效的组件代码。可以运行完整的提示词套件，也可以运行分层抽样以快速获得反馈。对每个提示词使用隔离的工作器：读取任务，使用已有文档记录的系统生成组件，自行识别绕行手段，并同时保存代码和评估元数据。 增加退化模式，以测试在包含填充轮次、干扰轮次和恢复轮次的 10 轮对话中保持上下文的能力。在第 0、6、8、10 轮等代表性位置进行探测，然后比较每个提示词的变化轨迹，而不是只报告最后一轮。 使用稳定的迭代标识符关联测试提示词、生成结果和截图。可以并行处理相互独立的提示词，但不得让多个工作器共享可变的结果文件。 ## 保存每次测试结果，找出 AI 绕开设计系统的地方 保存足够的结构化元数据，以便复现和比较各个案例：迭代标识符和提示词标识符、时间戳、模型、用户画像、提示词类别、轨迹深度、提示词、生成的响应、成功判断、使用的组件，以及检测到的绕行手段。 在汇总前构建预览页面并捕获截图。既要评估功能是否成功，也要评估生成结果是否通过原始元素、内联样式、硬编码导航、不受支持的选择器、重复的基础元素，或针对已受支持 CSS 的 JavaScript 绕行方案来规避设计系统。 将模型的自我评估视为一个信号，而不是证据。结合机器检查、预览证据和抽样人工审查。只有在定位到反复出现的失败模式后，才能使用汇总结果改进文档或 API。 ## 每次改动后做小范围检查，并报告通过了哪些 修改组件之前，先查看其当前文档，并判断通过配置、组合、新变体，还是为深度定制而显式导出源代码，最能满足需求。保留公共契约；如果已有扩展点，不要创建与现有基础元素并行的另一套基础元素。 变更后，更新需要同步的文档，并运行与变更直接相关的最小范围单元测试、类型检查、代码规范检查、样式能力扫描和组件预览。只有当变更跨越共享契约时，才扩展到完整套件。如果核心包版本发生变化，应运行已有文档记录的迁移步骤并检查差异。 报告已变更的行为、已更新的文档、通过的检查、发现的不受支持能力，以及无法运行的验证。