在前端规则仓库中编写规则，并在发布前通过检查

## 修改规则前，分清可编辑的源文件和生成产物 将前端规则仓库视为由源内容、模式、API、审查工具、渲染页面和生成索引组成的产品。修改前，先确定哪个层级负责相应行为，并检查该层级及其直接使用方。 - 梳理内容包、共享类型与模式、应用界面、工具服务器和生成结果之间的关系。 - 如果仓库提供审查和规则搜索工具，应优先使用它们，不要凭记忆臆造指南。 - 建议修复前先审查所检查的代码；对无障碍、性能、SEO、安全、隐私、国际化或测试提出判断前，先搜索规则库。 - 只有任务明确要求全面审计时，才进行广泛审计。 - 区分可编辑的源文件、生成产物和渲染后的投影视图。 兼容性指南应依据已声明的浏览器策略和有软件包数据支持的事实推导。不要依赖记忆中的支持表，也不要暗中把生成视图当作权威来源。 ## 规定每条规则都必须有的元数据 每条规则都需要稳定的元数据契约，以支持解析、搜索、评分、审查和渲染。必填项应保持精简，确保能够一致执行。 必填元数据应包括： - 带引号的人类可读标题和一句话说明； - 允许的类别、优先级和难度； - 带已声明单位的整数工作量估算； - 用于检查、修复和解释规则的可执行提示。 有用的可选元数据包括子类别、简明要点、对用户或业务的影响、证据来源、补充资源、相关规则、工具、标签、代码审查提示，以及自动审查所需的上下文。 依据权威允许列表验证类别和枚举值。包含具有语法意义标点的值应加引号。不要仅因某个字段听起来有用就添加它；只有解析器、UI、搜索层或生成器实际使用时才添加。 提示必须明确要检查的对象和预期的修复方式。应拒绝“检查此规则”之类没有可执行审查策略的占位文本。 ## 把证据、延伸资料和相关规则链接分开放置 将权威证据放在结构化的来源元数据中，将可选读物和工具放在资源元数据中，将跨规则导航放在相关规则元数据中。不要用一种职责替代另一种职责。 - 每条规则至少提供2个相关来源，涵盖2种不同的来源角色，其中至少1个是主要权威来源。 - 如果流水线支持，应为证据使用稳定标识符。 - 不要在正文中加入泛泛的“另请参阅”或“参考资料”行。 - 如果某个具名工具确实有帮助，并且已出现在资源或工具元数据中，应在首次有实质意义地提及时添加链接。 内联链接应支持具体主张或实现选择。可采用的默认范围是每条规则2–5个链接，其中导言0–1个，主要指南部分共1–3个。内部规则链接通常保持在0–1个，只有关联格外紧密的主题才使用2个。 链接文字应描述内容，不要使用“阅读更多”之类的标签。可由构建工具安全推导的字段可以交给工具推断，但绝不能以推断为借口接受薄弱或无关的证据。 ## 规则正文中，代码示例放在理由之前，验证放在最后 按稳定顺序编写每条规则，使人员、代理和验证器都能找到相同的信息： 1. 简短、通俗的导言； 2. 现实的代码示例或示例集合； 3. 规则重要性的说明； 4. 必要的实现指南； 5. 最后的验证章节。 示例应放在理由说明之前，验证应作为最后一个顶级章节。最佳实践、常见错误、框架示例、工具、阈值、例外、浏览器支持、标准和实现说明等可选章节应放在二者之间。 只有确实存在有效的特殊情况或误报时才添加例外。只有自动检查和人工检查都具有实际意义时才将验证拆分。兼容性或合规性会改变实现决策时，应添加清晰可见的标准或支持说明。 优先给出可判定通过或失败的指示，而不是泛泛建议。说明工程师如何验证规则、哪些证据有效，以及什么条件会使检查失败。 ## 为前端规则设定可判定通过与否的阈值 只要规则可以测试，就使用可测量的阈值： - `LCP <= 2.5s`、`CLS <= 0.1`、资源大小上限等性能预算； - 对比度、目标尺寸、键盘行为、缩放和重排等无障碍标准； - 可索引性、状态码和规范URL行为等SEO状态； - 传输方式和响应头条件等安全要求。 根据后果分配优先级：最高级别仅用于导致站点不可用、安全问题或法律问题的失败；体验下降、最佳实践和可选优化应使用较低级别。 示例必须足够真实，能够揭示失败方式。应包含重要例外和支持限制，但不要为每条规则加入所有可选章节。 把验证视为规则的一部分，而不是后续编辑任务。没有可复现检查的建议是不完整的。 ## 把共享UI部件放进设计系统，而不是各个页面 将排版、图标、语义颜色、可复用组件和其他跨应用关注点放入共享设计系统。应用在使用共享契约的同时，应负责连接框架特有的集成。 - 创建页面专用变体前，先复用现有组件。 - 将共享功能应用到所有相关界面，而不只是最先提出需求的页面。 - 使用整卡拉伸链接模式时，确保次要控件仍可操作。 - 集中管理品牌图标和框架图标导出；使用方不得绕过设计系统边界。 - 优先使用达到预期完整对比度的语义主题变量，不要使用任意透明度修饰。 - CSS重置使富文本列表标记消失时，应明确恢复这些标记。 不要通过屏蔽服务器与客户端的水合警告来掩盖不一致。应修复状态边界，例如把仅客户端状态延迟到挂载后再启用。 浏览器来源的保护应留在浏览器变更操作和表单上。无法完成浏览器挑战的程序化API端点，不得应用客户端机器人检查。 ## 把新工具从定义到测试完整接通 只有定义、导出、注册、分派、实现、测试和文档彼此一致，新工具或跨软件包功能才算完成。 对于可调用工具： 1. 定义具体名称、说明和输入模式； 2. 在软件包边界导出； 3. 在服务器工具目录中注册； 4. 连接到分派路径； 5. 测试发现、验证、路由和行为。 聚合导出仅用于软件包边界；内部聚合导出会增加导航跳转并掩盖所有权。多个软件包共同使用的依赖版本应集中管理，脚本应按用途组织并配有持续维护的索引。 遵守特定版本的库契约。例如，使用已安装验证器当前的错误结构，通过仓库批准的工厂创建有状态查询客户端，并按能够保留全部返回属性的顺序组合异步配置包装器。 修改启动时加载的配置后，应重启服务。只有运行中的进程已经加载变更，成功编辑才能作为有效证据。 ## 发布前跑完所有检查，一项都不跳过 修改规则或其基础设施后，运行仓库的权威质量检查链： - 验证必填元数据、类别值、来源质量和规则结构； - 对可执行提示、证据、示例、正文深度、验证、阈值及适用的条件章节进行评分； - 运行格式化、代码检查、类型检查、软件包检查、针对性测试，以及变更界面所要求的完整构建； - 重新生成索引或技能，并确认生成结果保持同步。 不得绕过提交前检查。不要使用跳过验证的路径；应修正文档、不安全的类型转换、复杂度、导入边界、未使用代码和覆盖率问题。 将自动评分视为质量门禁，而不是语义正确性的证明。除源文件外，还要审查渲染结果和面向工具的结果。 发布前，确认必填提示可执行、证据具有权威性、示例符合建议、验证位于最后，并且没有遗留生成差异。只有完整检查链全部通过后才能发布。