编写能返回通过、失败或无法判定的可访问性检查规则

## 把 lint 和测试当作每次改动的一部分，而不是事后清理 将格式化、lint检查、测试、文档和提交规范视为变更本身的一部分，而不是实现完成后的清理工作。 ### 必需检查 - 提交前运行仓库指定的格式化工具和lint工具。 - 完成前运行完整测试套件，并针对行为变更提供单元测试和集成测试覆盖。 - 只有在变更不可能影响运行时行为时，才遵循已记录的例外规定。 - 将未解决的工作保留在项目的问题跟踪器中，不要把它隐藏在无关变更里。 - 不要提交临时日志或本地调试设置。 ### 代码规范 - 尽早处理错误和边界情况，让成功路径保持清晰易懂。 - 遵循既定的export位置、命名规则和import风格。 - 以一致方式命名文件和规则标识符；按照项目规范区分函数、布尔值和常量。 - 在变量首次使用的位置附近声明变量。 - 为导出的API、参数、返回值和复杂逻辑编写文档。 - 将重构与范围明确的功能开发或修复分开进行。 ## 区分虚拟节点与真实 DOM，并让依赖只朝一个方向 应有意识地在虚拟树抽象和真实DOM节点之间进行选择。抽象层能够高效处理已缓存的属性和特性，而浏览器API和布局行为则需要真实DOM。 ### 节点选择 - 访问属性、使用已缓存特性、遍历树和执行选择器操作时，优先使用虚拟节点。 - 处理布局、几何信息、根节点查找、浏览器计算行为和其他原生API时，使用真实DOM节点。 - 通过一个已记录的转换边界解决含糊不清的输入。 - 除非依赖虚拟节点具有明确的API优势或性能优势，否则通用工具应以真实DOM作为输入和输出。 - 不要把转换逻辑分散到各个规则中。 ### 依赖方向 - 将标准定义保留为不含运行时import的纯数据。 - 只允许低层工具通过明确路径依赖更低层的基础代码和标准数据。 - 将第三方模块的import集中到指定的适配器层。 - 允许共享领域辅助程序使用低层工具，但绝不允许依赖方向反转。 - 允许高层检查和规则组合下层组件，但不得形成循环依赖。 - 使用lint规则或构建规则以机械方式强制执行这些边界。 ## 返回通过、失败或无法判定，并把消息放进元数据 明确规定结果契约，使使用方能够区分合规、失败和证据不足。 ### 检查结果 - 测试条件得到满足时返回`pass`。 - 测试条件遭到违反时返回`fail`。 - 引擎无法可靠确定结果时返回`incomplete`。 - 附加结构化数据，供消息模板使用并说明产生`incomplete`结果的原因。 - 不要仅仅为了给出二元答案，就强行把不确定性归入`pass`或`fail`。 ### 规则定义 - 使用明确的`all`、`any`和`none`分组来组合检查。 - 使用选择器和可选的附加匹配器来限定候选元素的范围。 - 将影响程度限制为项目声明的严重性值。 - 从集中管理的标准数据中读取HTML和ARIA定义，不要在检查内部硬编码列表。 ### 面向用户的消息 - 将消息放在规则或检查的元数据中，而不是实现代码中。 - 使用命名数据占位符，其值由检查结果提供。 - 在语法需要时提供单数和复数变体。 - 每当源消息发生变化时，都要更新本地化模板。 ## 对颜色对比度和角色判定格外仔细地审查 有些可访问性结果依赖不完整的浏览器信息或快速演进的标准。这些领域需要保守的结果和有针对性的审查。 ### 颜色和可见性 - 考虑支持的颜色格式、不透明度、混合、堆叠上下文和文本效果。 - 无法确定有效背景或对比度时返回`incomplete`。 - 从语义层面评估屏幕阅读器的可见性，而不是只依赖CSS可见性。 - 包括隐藏状态属性、组合树和Shadow DOM边界。 ### 语义标准 - 让role和属性验证与当前可访问性规范保持同步。 - 分别解析隐式role和显式role。 - 查询集中管理的role和属性定义，确保每条规则都使用同一事实来源。 - 针对规范更新和以往被错误分类的标记添加回归测试用例。 - 当一项变更可能改变许多规则的结果时，必须进行有针对性的审查。 ## 在接近真实的页面上测试规则，包括 Shadow DOM 在单元测试树中映射源代码结构，使实现和测试的归属保持清晰。 ### 单元测试和检查测试 - 使用项目提供的标准检查上下文或测试工具框架。 - 如果共享fixture和虚拟树已由测试工具框架清除，则只重置由当前测试拥有的状态。 - 测试`pass`、`fail`和`incomplete`结果，包括附加的消息数据。 - 在增加广泛的集成测试覆盖前，先为边界条件添加有针对性的用例。 ### 集成测试 - 为每个规则fixture配套结构化的预期结果。 - 使用引擎的规范选择器表示形式，包括用于frame的嵌套选择器。 - 当文档级行为无法用片段表示时，使用完整的HTML页面。 - 为每条相关规则或检查添加一个open Shadow DOM用例。 - 当变更影响虚拟树评估时，更新虚拟规则覆盖。 - 迭代期间运行有针对性的测试，移交前运行作为权威依据的完整测试套件。 ## 在修改消息的同一次提交里重新生成翻译模板 区分生成的发布包与仓库有意跟踪的生成型源代码制品。 ### 制品政策 - 不要直接编辑已打包或已压缩的发布输出。 - 通过获准的构建流程重新生成受跟踪的模板或源代码制品。 - 将生成的本地化模板与产生它的消息源放在同一次变更中提交。 - 不要把需要同步的源代码更新和生成内容更新拆分到不同提交中。 - 不要把已忽略的发布包纳入常规功能提交。 ### 验证 - 检查生成的差异，查找意外的消息、语言区域或规则变更。 - 确认每个新占位符都存在于产生它的检查数据中。 - 消息变更后运行本地化验证和构建验证。 - 记录哪些制品是生成的、哪些受跟踪，以及哪些仅用于发布。 ## 更新变更日志和 API 文档，并避免破坏性变更 让每项变更保持范围集中，并使其公开影响对审查者和使用方清晰可见。 ### 变更文档 - 添加规则或对规则进行实质性变更时，更新变更日志。 - 公共接口发生变化时，同时更新API文档和类型定义。 - 使用仓库要求的conventional commit格式，提供简洁的主题，并在正文中说明动机。 - 通过支持的footer或拉取请求元数据关联已解决的问题。 - 移交前完成项目审查清单。 ### 兼容性 - 如果旧格式和新格式可以同时得到支持，应避免破坏性变更。 - 清楚标记已弃用的API，并提供迁移路径。 - 如果无法避免破坏性变更，应在发布元数据和变更日志中明确指出。 - 包括迁移指导、更新后的测试、同步后的生成文件，以及审查者可见的证据。 - 在格式化、lint检查、有针对性的测试、集成测试、完整测试套件和文档检查获得实际结果之前，不要声称已经准备就绪。