Front-End-Checklist 无障碍规则实战确保活动元素拥有唯一 IDduplicate-id-active【免费下载链接】Front-End-Checklist The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-Checklist导读本文围绕 Front-End-Checklist 仓库中的duplicate-id-active无障碍规则展开系统讲解页面中所有可获得焦点的活动元素链接、按钮、输入框等必须拥有全局唯一 ID这一核心要求。你将掌握该规则对应的 HTML 示例、失效原因、修复策略、最佳实践、验证手段以及它在当前仓库中从 MDX 规则内容生成 Agent Skill 的实现链路并能在自己的前端项目中落地为可检查、可修复、可验证的工程实践。一、规则定位与适用场景duplicate-id-active是 Front-End-Checklist 内容体系中一条高优先级priority: high、难度中等intermediate、预计耗时10 分钟的无障碍检查规则归属于accessibility分类下的document-structure文档结构子类。它的权威规则定义位于 packages/content/rules/en/accessibility/duplicate-id-active.mdx在仓库总览 README.md 中也以Use unique IDs for active elements条目被收录进检查清单。该规则的适用时机非常具体当审查渲染后的 HTML、交互组件或设计系统模式时优先检查原生语义再观察键盘行为、焦点流转、可访问名称以及屏幕阅读器输出。换句话说这不是一句别写重复 ID的空泛建议而是一条要求开发者针对可交互、可聚焦的活动元素逐项核验的工程规则。规则的一句话定义是所有可获得焦点或处于活动状态的元素都必须拥有唯一的id属性。在 skills/duplicate-id-active/SKILL.md 中这条规则以 Agent Skill 的形式提供了四组可直接用于代码审查的操作提示操作提示内容Check搜索可获得焦点或活动的 HTML 元素上的重复id属性Fix为每个活动元素分配唯一id确保焦点处理和无障碍正确Explain解释唯一 ID 如何防止键盘用户与屏幕阅读器用户的导航错误Code Review审查渲染后的标记与交互状态标出违反规则的具体元素、角色、标签、焦点行为或键盘交互并说明如何用浏览器无障碍工具或辅助技术验证修复二、规则如何演化为 Agent Skill生成链路解析要真正理解这份 SKILL 文档的用途需要知道它在仓库中的来源。Front-End-Checklist 使用一个专门的生成脚本 scripts/generate/generate-skills.ts把规则 MDX 的 frontmatter 元数据自动转化为两件套结构SKILL.md—— 面向 Agent 的意图匹配 操作指令文件由buildSkillMd()函数生成references/rule.md—— 规则的完整正文由buildReferencesMd()函数把 MDX 正文转换为纯 Markdown。从 generate-skills.ts 的源码可以看出生成逻辑的关键设计description 必须符合 Use when ... 格式脚本会检查 frontmatter 中的aiContext或description若不以Use when开头会自动补齐前缀这是为了skill-check的 Agent 意图匹配要求对应 generate-skills.ts。这也解释了为什么duplicate-id-active/SKILL.md的 description 以 Use when reviewing rendered HTML... 开头。metadata 继承规则元数据category、priority、difficulty、estimatedTime以及指向规则页面的url全部来自 MDX frontmatter对应 generate-skills.ts因此 SKILL.md 中priority: high、estimatedTime: 10与规则 MDX 完全一致。SKILL.md 末尾固定指向 referencesFor full implementation details, code examples, and framework-specific guidance, see references/rule.md.是模板固定输出对应 generate-skills.ts提示 Agent 需要深入细节时读取完整规则正文。因此当你看到duplicate-id-active目录下这两个文件时它们并非手工维护的两份重复文档而是同一规则源MDX在不同消费端Agent 指令 / 人类参考的两种呈现。三、Why It Matters重复 ID 为什么是灾难规则文档明确指出活动元素上的重复 ID 会导致浏览器和辅助技术跳过条目、错误引导焦点或无法触发正确的操作。具体拆解为三个层面焦点管理Focus Management浏览器依赖id来追踪当前获得焦点的元素。当两个活动元素共享同一个id时焦点可能丢失或被移动到错误的元素上用户明明按了 Tab焦点却跳到意想不到的位置。键盘导航Keyboard Navigation使用键盘导航的用户会发现某些交互元素不可达——因为它们与另一个元素共享 ID浏览器无法正确解析目标。辅助技术Assistive Technology屏幕阅读器通常用 ID 构建页面交互控件的地图。重复 ID 会直接破坏这张地图导致控件被跳过、顺序错乱或读出的名称与操作不匹配。此外从同仓库的配套规则 packages/content/rules/en/html/unique-id.mdx 可以补充一个更广的视角重复 ID 还意味着表单标签失效label的for无法正确关联输入框、ARIA 关系断裂aria-labelledby/aria-describedby/aria-controls指向歧义以及getElementById返回错误元素导致的静默 Bug。而duplicate-id-active规则聚焦的是其中对活动元素影响最致命的部分。四、Check Fix如何检查、如何修复4.1 检查方法规则给出的检查指令非常简单直接在可获得焦点或活动的 HTML 元素上搜索重复的id属性。聚焦范围是关键不需要扫描全文档所有元素而是重点覆盖链接a、按钮button、输入框input、select、textarea、[tabindex]元素等可获得焦点的活动元素。4.2 修复示例规则参考文档 skills/duplicate-id-active/references/rule.md 提供了标准的正反例!-- ✅ Good: Unique IDs for each input -- label forfirst-nameFirst Name/label input idfirst-name typetext label forlast-nameLast Name/label input idlast-name typetext !-- ❌ Bad: Duplicate IDs on active elements -- button idsubmit-btnSave/button button idsubmit-btnCancel/button !-- Error: ID must be unique --反例中两个按钮共用submit-btn点击Cancel时浏览器与辅助技术无法确定究竟该触发哪个行为焦点与事件都可能落到错误的按钮上。修复方式就是给每个按钮分配互不相同的 ID。4.3 修复时的三个最佳实践自动化检查Automate Checks在开发期使用 linter 或无障碍审计工具提前捕获重复 ID而不是等上线后由真实用户踩坑。组件前缀 / 生成 IDUse Prefixes在组件化框架中同一组件被渲染多次时极易产生 ID 碰撞。应使用唯一前缀或自动生成 ID 来隔离不同实例。语义标签配对Semantic Labels始终确保label的for属性与对应输入框的id完全匹配——这正是duplicate-id-active与表单无障碍最直接的交汇点。五、组件化框架下的唯一 ID 实战方案规则文档将Use Prefixes列为最佳实践但具体怎么做仓库中的配套规则 packages/content/rules/en/html/unique-id.mdx 给出了跨框架的完整示例这里提炼出与活动元素最相关的三种方案。5.1 ReactuseId是首选React 18 内置的useId专为生成稳定的唯一 ID 设计适合label/input配对和 ARIA 引用import { useId } from react function ContactForm() { const formId useId() const nameId ${formId}-name const emailId ${formId}-email return ( form id{formId} div label htmlFor{nameId}Name/label input typetext id{nameId} namename / /div div label htmlFor{emailId}Email/label input typeemail id{emailId} nameemail / /div /form ) } // 同一页面渲染多个实例也不会冲突 export default function ContactPage() { return ( div ContactForm / {/* IDs: :r1:-name, :r1:-email */} ContactForm / {/* IDs: :r2:-name, :r2:-email */} /div ) }5.2 Vue组件级随机前缀Vue 3 Composition API 下可以在setup中生成一次组件级随机前缀再基于前缀派生所有子 ID保证同一组件多次渲染时互不冲突完整示例见 unique-id.mdxscript setup const componentId reviews-${Math.random().toString(36).substr(2, 9)} const getTabId (tabId) ${componentId}-tab-${tabId} const getPanelId (tabId) ${componentId}-panel-${tabId} /script5.3 动态内容JS 生成器模式当使用原生 JavaScript 动态创建表单字段或弹窗时可以用计数器加时间戳生成唯一 ID并配合Set登记已用 ID完整实现见 unique-id.mdxclass IDManager { constructor() { this.usedIds new Set() } isIdUnique(id) { return !this.usedIds.has(id) !document.getElementById(id) } registerID(id) { if (!this.isIdUnique(id)) throw new Error(ID ${id} is already in use) this.usedIds.add(id) return id } generateUniqueId(prefix auto) { let counter 1 let id ${prefix}-${counter} while (!this.isIdUnique(id)) { counter; id ${prefix}-${counter} } this.registerID(id) return id } }六、Tools Validation验证工具矩阵规则文档推荐的验证工具与配套检查手段如下工具 / 手段用途仓库对应证据W3C HTML Validator校验文档级 ID 唯一性面向完整文档unique-id.mdx 中推荐的 Nu Html Checkeraxe-core rule:duplicate-id-active专门检查活动元素的重复 ID是这条规则的自动化化身duplicate-id-active.mdx 明确列出axe DevTools / Lighthouse浏览器内自动审计生成可读报告规则 MDX 的resources字段登记了 axe DevTools浏览器 DevTools Console运行时快速扫描可通过document.querySelectorAll([id])聚合统计6.1 自动化检查要点按规则文档的 Verification 章节自动检查应做到检查浏览器**无障碍树accessibility tree**或无障碍面板中相关元素、角色、可访问名称是否正确在适用处运行 axe、Lighthouse 等自动检查器优先检查最终渲染后的 HTML而不是源码中的框架抽象——这正是aiContext强调Check native semantics first的原因。6.2 手动检查要点自动检查无法覆盖所有真实交互场景因此规则要求用纯键盘导航测试受影响的 UI确认焦点顺序与行为符合预期如果该规则影响关键交互用屏幕阅读器重新测试一条代表性用户流程。一个可复用的 DevTools 运行时扫描脚本来自 unique-id.mdxfunction findDuplicateIds() { const ids {} const duplicates [] document.querySelectorAll([id]).forEach(element { const id element.id if (ids[id]) { if (ids[id] 1) duplicates.push(id) ids[id] } else { ids[id] 1 } }) return duplicates } console.log(Duplicate IDs:, findDuplicateIds())七、Exceptions何时不把静态告警当阻塞项规则文档特别给出三条例外原则防止过度教条化以渲染后的实际体验为准在把静态代码告警当作阻塞问题之前先评估交互时机、浏览器行为与辅助技术输出严重程度往往由这些真实表现决定。按影响排序并非每个次要无障碍问题都值得同等权重优先处理最直接阻碍感知、操作或理解的问题。避免为满足规则而堆砌冗余标记当更简单的语义实现能彻底消除问题时不要为了过规则而添加多余标签或 ARIA。这与duplicate-id-aria规则的例外精神一致见 packages/content/rules/en/accessibility/duplicate-id-aria.mdx能优先用原生 HTML 语义解决的就不要依赖 ARIA 修补。八、Standards 与关联规则8.1 对齐的标准规则要求实现对齐以下标准且必须验证渲染后的体验而非仅看源码W3C WAI: WCAG Overview对应规则 MDX 的sources中role: standard、authority: primary的 W3C WCAG 22 链接见 duplicate-id-active.mdxMDN: Accessibility作为权威参考来源。8.2 关联规则在规则内容体系中duplicate-id-active与以下规则同属accessibility/document-structure区域、常被一起评审见 duplicate-id-active.mdxempty-heading空标题listitem列表项语义table-duplicate-name表格重名lang-attribute语言属性同时需要区分两个容易混淆的规则duplicate-id-active聚焦活动/可聚焦元素的重复 ID破坏焦点与交互duplicate-id-aria聚焦被 ARIA 属性引用的 ID如aria-labelledby、aria-describedby、aria-controls重复时导致关系歧义、屏幕阅读器读到错误标签见 duplicate-id-aria.mdx。两者的最佳实践高度互补duplicate-id-aria同样建议动态内容用useId等工具保证生成 ID 唯一且强调验证Accessibility Tree中引用是否解析正确。九、常见误区与排查清单结合仓库规则内容最后给出一份可直接对照的排查清单场景典型症状修复方向同一组件渲染多次表单label点击无法聚焦对应输入框用useId或组件级随机前缀派生 ID动态插入 DOMgetElementById取到第一个元素事件绑定错乱用 ID 管理器登记并校验唯一性弹窗 / Tab 模式aria-labelledby指向的标题重复读屏读出错误标题为每次实例生成带前缀的标题 ID硬编码通用 ID如idcontent、idbox页面多处复用语义不清晰且易冲突改用描述性、语义化的唯一命名结语duplicate-id-active看似只是一条ID 必须唯一的小规则但在 Front-End-Checklist 中它背后串联起了一整条工程链路从规则 MDX 的元数据定义到generate-skills.ts将其编译为可供 Agent 直接执行的 SKILL 指令再到references/rule.md提供的人类可读实现细节。开发者在使用这条规则时应当同时做到三件事用自动化工具拦截重复 ID、在组件化框架中设计唯一的 ID 生成策略、最后回到真实浏览器中用键盘和读屏验证渲染结果——只有把检查、修复、验证三个环节都走通这条规则才能真正保护键盘用户与屏幕阅读器用户的体验。【免费下载链接】Front-End-Checklist The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-Checklist创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Front-End-Checklist 无障碍规则实战：确保活动元素拥有唯一 ID（duplicate-id-active）
Front-End-Checklist 无障碍规则实战确保活动元素拥有唯一 IDduplicate-id-active【免费下载链接】Front-End-Checklist The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-Checklist导读本文围绕 Front-End-Checklist 仓库中的duplicate-id-active无障碍规则展开系统讲解页面中所有可获得焦点的活动元素链接、按钮、输入框等必须拥有全局唯一 ID这一核心要求。你将掌握该规则对应的 HTML 示例、失效原因、修复策略、最佳实践、验证手段以及它在当前仓库中从 MDX 规则内容生成 Agent Skill 的实现链路并能在自己的前端项目中落地为可检查、可修复、可验证的工程实践。一、规则定位与适用场景duplicate-id-active是 Front-End-Checklist 内容体系中一条高优先级priority: high、难度中等intermediate、预计耗时10 分钟的无障碍检查规则归属于accessibility分类下的document-structure文档结构子类。它的权威规则定义位于 packages/content/rules/en/accessibility/duplicate-id-active.mdx在仓库总览 README.md 中也以Use unique IDs for active elements条目被收录进检查清单。该规则的适用时机非常具体当审查渲染后的 HTML、交互组件或设计系统模式时优先检查原生语义再观察键盘行为、焦点流转、可访问名称以及屏幕阅读器输出。换句话说这不是一句别写重复 ID的空泛建议而是一条要求开发者针对可交互、可聚焦的活动元素逐项核验的工程规则。规则的一句话定义是所有可获得焦点或处于活动状态的元素都必须拥有唯一的id属性。在 skills/duplicate-id-active/SKILL.md 中这条规则以 Agent Skill 的形式提供了四组可直接用于代码审查的操作提示操作提示内容Check搜索可获得焦点或活动的 HTML 元素上的重复id属性Fix为每个活动元素分配唯一id确保焦点处理和无障碍正确Explain解释唯一 ID 如何防止键盘用户与屏幕阅读器用户的导航错误Code Review审查渲染后的标记与交互状态标出违反规则的具体元素、角色、标签、焦点行为或键盘交互并说明如何用浏览器无障碍工具或辅助技术验证修复二、规则如何演化为 Agent Skill生成链路解析要真正理解这份 SKILL 文档的用途需要知道它在仓库中的来源。Front-End-Checklist 使用一个专门的生成脚本 scripts/generate/generate-skills.ts把规则 MDX 的 frontmatter 元数据自动转化为两件套结构SKILL.md—— 面向 Agent 的意图匹配 操作指令文件由buildSkillMd()函数生成references/rule.md—— 规则的完整正文由buildReferencesMd()函数把 MDX 正文转换为纯 Markdown。从 generate-skills.ts 的源码可以看出生成逻辑的关键设计description 必须符合 Use when ... 格式脚本会检查 frontmatter 中的aiContext或description若不以Use when开头会自动补齐前缀这是为了skill-check的 Agent 意图匹配要求对应 generate-skills.ts。这也解释了为什么duplicate-id-active/SKILL.md的 description 以 Use when reviewing rendered HTML... 开头。metadata 继承规则元数据category、priority、difficulty、estimatedTime以及指向规则页面的url全部来自 MDX frontmatter对应 generate-skills.ts因此 SKILL.md 中priority: high、estimatedTime: 10与规则 MDX 完全一致。SKILL.md 末尾固定指向 referencesFor full implementation details, code examples, and framework-specific guidance, see references/rule.md.是模板固定输出对应 generate-skills.ts提示 Agent 需要深入细节时读取完整规则正文。因此当你看到duplicate-id-active目录下这两个文件时它们并非手工维护的两份重复文档而是同一规则源MDX在不同消费端Agent 指令 / 人类参考的两种呈现。三、Why It Matters重复 ID 为什么是灾难规则文档明确指出活动元素上的重复 ID 会导致浏览器和辅助技术跳过条目、错误引导焦点或无法触发正确的操作。具体拆解为三个层面焦点管理Focus Management浏览器依赖id来追踪当前获得焦点的元素。当两个活动元素共享同一个id时焦点可能丢失或被移动到错误的元素上用户明明按了 Tab焦点却跳到意想不到的位置。键盘导航Keyboard Navigation使用键盘导航的用户会发现某些交互元素不可达——因为它们与另一个元素共享 ID浏览器无法正确解析目标。辅助技术Assistive Technology屏幕阅读器通常用 ID 构建页面交互控件的地图。重复 ID 会直接破坏这张地图导致控件被跳过、顺序错乱或读出的名称与操作不匹配。此外从同仓库的配套规则 packages/content/rules/en/html/unique-id.mdx 可以补充一个更广的视角重复 ID 还意味着表单标签失效label的for无法正确关联输入框、ARIA 关系断裂aria-labelledby/aria-describedby/aria-controls指向歧义以及getElementById返回错误元素导致的静默 Bug。而duplicate-id-active规则聚焦的是其中对活动元素影响最致命的部分。四、Check Fix如何检查、如何修复4.1 检查方法规则给出的检查指令非常简单直接在可获得焦点或活动的 HTML 元素上搜索重复的id属性。聚焦范围是关键不需要扫描全文档所有元素而是重点覆盖链接a、按钮button、输入框input、select、textarea、[tabindex]元素等可获得焦点的活动元素。4.2 修复示例规则参考文档 skills/duplicate-id-active/references/rule.md 提供了标准的正反例!-- ✅ Good: Unique IDs for each input -- label forfirst-nameFirst Name/label input idfirst-name typetext label forlast-nameLast Name/label input idlast-name typetext !-- ❌ Bad: Duplicate IDs on active elements -- button idsubmit-btnSave/button button idsubmit-btnCancel/button !-- Error: ID must be unique --反例中两个按钮共用submit-btn点击Cancel时浏览器与辅助技术无法确定究竟该触发哪个行为焦点与事件都可能落到错误的按钮上。修复方式就是给每个按钮分配互不相同的 ID。4.3 修复时的三个最佳实践自动化检查Automate Checks在开发期使用 linter 或无障碍审计工具提前捕获重复 ID而不是等上线后由真实用户踩坑。组件前缀 / 生成 IDUse Prefixes在组件化框架中同一组件被渲染多次时极易产生 ID 碰撞。应使用唯一前缀或自动生成 ID 来隔离不同实例。语义标签配对Semantic Labels始终确保label的for属性与对应输入框的id完全匹配——这正是duplicate-id-active与表单无障碍最直接的交汇点。五、组件化框架下的唯一 ID 实战方案规则文档将Use Prefixes列为最佳实践但具体怎么做仓库中的配套规则 packages/content/rules/en/html/unique-id.mdx 给出了跨框架的完整示例这里提炼出与活动元素最相关的三种方案。5.1 ReactuseId是首选React 18 内置的useId专为生成稳定的唯一 ID 设计适合label/input配对和 ARIA 引用import { useId } from react function ContactForm() { const formId useId() const nameId ${formId}-name const emailId ${formId}-email return ( form id{formId} div label htmlFor{nameId}Name/label input typetext id{nameId} namename / /div div label htmlFor{emailId}Email/label input typeemail id{emailId} nameemail / /div /form ) } // 同一页面渲染多个实例也不会冲突 export default function ContactPage() { return ( div ContactForm / {/* IDs: :r1:-name, :r1:-email */} ContactForm / {/* IDs: :r2:-name, :r2:-email */} /div ) }5.2 Vue组件级随机前缀Vue 3 Composition API 下可以在setup中生成一次组件级随机前缀再基于前缀派生所有子 ID保证同一组件多次渲染时互不冲突完整示例见 unique-id.mdxscript setup const componentId reviews-${Math.random().toString(36).substr(2, 9)} const getTabId (tabId) ${componentId}-tab-${tabId} const getPanelId (tabId) ${componentId}-panel-${tabId} /script5.3 动态内容JS 生成器模式当使用原生 JavaScript 动态创建表单字段或弹窗时可以用计数器加时间戳生成唯一 ID并配合Set登记已用 ID完整实现见 unique-id.mdxclass IDManager { constructor() { this.usedIds new Set() } isIdUnique(id) { return !this.usedIds.has(id) !document.getElementById(id) } registerID(id) { if (!this.isIdUnique(id)) throw new Error(ID ${id} is already in use) this.usedIds.add(id) return id } generateUniqueId(prefix auto) { let counter 1 let id ${prefix}-${counter} while (!this.isIdUnique(id)) { counter; id ${prefix}-${counter} } this.registerID(id) return id } }六、Tools Validation验证工具矩阵规则文档推荐的验证工具与配套检查手段如下工具 / 手段用途仓库对应证据W3C HTML Validator校验文档级 ID 唯一性面向完整文档unique-id.mdx 中推荐的 Nu Html Checkeraxe-core rule:duplicate-id-active专门检查活动元素的重复 ID是这条规则的自动化化身duplicate-id-active.mdx 明确列出axe DevTools / Lighthouse浏览器内自动审计生成可读报告规则 MDX 的resources字段登记了 axe DevTools浏览器 DevTools Console运行时快速扫描可通过document.querySelectorAll([id])聚合统计6.1 自动化检查要点按规则文档的 Verification 章节自动检查应做到检查浏览器**无障碍树accessibility tree**或无障碍面板中相关元素、角色、可访问名称是否正确在适用处运行 axe、Lighthouse 等自动检查器优先检查最终渲染后的 HTML而不是源码中的框架抽象——这正是aiContext强调Check native semantics first的原因。6.2 手动检查要点自动检查无法覆盖所有真实交互场景因此规则要求用纯键盘导航测试受影响的 UI确认焦点顺序与行为符合预期如果该规则影响关键交互用屏幕阅读器重新测试一条代表性用户流程。一个可复用的 DevTools 运行时扫描脚本来自 unique-id.mdxfunction findDuplicateIds() { const ids {} const duplicates [] document.querySelectorAll([id]).forEach(element { const id element.id if (ids[id]) { if (ids[id] 1) duplicates.push(id) ids[id] } else { ids[id] 1 } }) return duplicates } console.log(Duplicate IDs:, findDuplicateIds())七、Exceptions何时不把静态告警当阻塞项规则文档特别给出三条例外原则防止过度教条化以渲染后的实际体验为准在把静态代码告警当作阻塞问题之前先评估交互时机、浏览器行为与辅助技术输出严重程度往往由这些真实表现决定。按影响排序并非每个次要无障碍问题都值得同等权重优先处理最直接阻碍感知、操作或理解的问题。避免为满足规则而堆砌冗余标记当更简单的语义实现能彻底消除问题时不要为了过规则而添加多余标签或 ARIA。这与duplicate-id-aria规则的例外精神一致见 packages/content/rules/en/accessibility/duplicate-id-aria.mdx能优先用原生 HTML 语义解决的就不要依赖 ARIA 修补。八、Standards 与关联规则8.1 对齐的标准规则要求实现对齐以下标准且必须验证渲染后的体验而非仅看源码W3C WAI: WCAG Overview对应规则 MDX 的sources中role: standard、authority: primary的 W3C WCAG 22 链接见 duplicate-id-active.mdxMDN: Accessibility作为权威参考来源。8.2 关联规则在规则内容体系中duplicate-id-active与以下规则同属accessibility/document-structure区域、常被一起评审见 duplicate-id-active.mdxempty-heading空标题listitem列表项语义table-duplicate-name表格重名lang-attribute语言属性同时需要区分两个容易混淆的规则duplicate-id-active聚焦活动/可聚焦元素的重复 ID破坏焦点与交互duplicate-id-aria聚焦被 ARIA 属性引用的 ID如aria-labelledby、aria-describedby、aria-controls重复时导致关系歧义、屏幕阅读器读到错误标签见 duplicate-id-aria.mdx。两者的最佳实践高度互补duplicate-id-aria同样建议动态内容用useId等工具保证生成 ID 唯一且强调验证Accessibility Tree中引用是否解析正确。九、常见误区与排查清单结合仓库规则内容最后给出一份可直接对照的排查清单场景典型症状修复方向同一组件渲染多次表单label点击无法聚焦对应输入框用useId或组件级随机前缀派生 ID动态插入 DOMgetElementById取到第一个元素事件绑定错乱用 ID 管理器登记并校验唯一性弹窗 / Tab 模式aria-labelledby指向的标题重复读屏读出错误标题为每次实例生成带前缀的标题 ID硬编码通用 ID如idcontent、idbox页面多处复用语义不清晰且易冲突改用描述性、语义化的唯一命名结语duplicate-id-active看似只是一条ID 必须唯一的小规则但在 Front-End-Checklist 中它背后串联起了一整条工程链路从规则 MDX 的元数据定义到generate-skills.ts将其编译为可供 Agent 直接执行的 SKILL 指令再到references/rule.md提供的人类可读实现细节。开发者在使用这条规则时应当同时做到三件事用自动化工具拦截重复 ID、在组件化框架中设计唯一的 ID 生成策略、最后回到真实浏览器中用键盘和读屏验证渲染结果——只有把检查、修复、验证三个环节都走通这条规则才能真正保护键盘用户与屏幕阅读器用户的体验。【免费下载链接】Front-End-Checklist The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-Checklist创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考