为 Tooltip 提供可访问名称Front-End-Checklist 的 ARIA Tooltip Name 规则详解与实现指南【免费下载链接】Front-End-Checklist The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-ChecklistTooltip提示框常承载对完成操作至关重要的补充信息若未能正确命名或与触发元素建立关联屏幕阅读器用户将完全失去这些信息。本文以 Front-End-Checklist 仓库中aria-tooltip-name规则SKILL.md、references/rule.md 与 aria-tooltip-name.mdx为骨架讲解 tooltip 可访问名称的原理、正确写法、例外情况与验证方法并结合仓库内基于 Radix UI 的真实实现tooltip.tsx与相邻规则 accessible-tooltips.mdx帮助你写出可被搜索引擎、Agent 与人工审查一致理解和执行的 tooltip 无障碍代码。规则速览Quick Referencearia-tooltip-name是一条位于accessibility/aria分类下的中优先级、中等难度规则预计修复耗时约 10 分钟元数据定义见 SKILL.mdTooltip 必须有可访问名称accessible name或被触发元素通过aria-describedby引用确保 tooltip 内容对辅助技术assistive technology真正可访问验证 tooltip 与其触发元素trigger之间的关联是否正确建立。该规则对应的中文原义即为 tooltip 提供可访问名称。规则源文件 aria-tooltip-name.mdx 给出了完整的前端元数据priority: medium、difficulty: intermediate、estimatedTime: 10并引用了WAI-ARIA 1.2规范与MDN: ARIA参考文档作为主权威来源sources 中authority: primary。为什么 Tooltip 名称会消失Tooltip 往往只在悬停hover时出现且默认是视觉呈现而非文本节点。在 DOM 中roletooltip的元素本身并不会自动向辅助技术暴露其内容——屏幕阅读器不会因为页面上存在一个 tooltip 就主动朗读它。真正把 tooltip 内容递到屏幕阅读器面前的是以下两条通路之一触发元素通过aria-describedby引用 tooltip 的 id——此时 tooltip 内容会作为触发元素描述的一部分在聚焦/进入无障碍树时被播报tooltip 自身拥有可访问名称如aria-label、aria-labelledby——使其在无障碍树中成为有名节点。如果两条通路都不存在tooltip 内容对屏幕阅读器用户就是隐形的。规则文件 references/rule.md 在Why It Matters中明确了四点价值信息平等Information Equality让不使用鼠标的用户也能获得 tooltip 中隐藏的文本触发感知Trigger Awareness帮助用户理解某个元素为何重要、如何使用WCAG 合规WCAG Compliance满足悬停或聚焦时内容呈现的成功标准对应 WCAG 1.4.13 Content on Hover or Focus 等准则上下文帮助Contextual Help让非视觉用户获得与视觉用户相同的提示信息。正确的代码写法references/rule.md 给出了两条正确的实现路径代码示例完整继承如下!-- ✅ Correct: Trigger references tooltip via aria-describedby -- button aria-describedbytooltip-save Save /button div idtooltip-save roletooltip Saves your current changes to the cloud /div !-- ✅ Correct: Tooltip with its own name -- div roletooltip aria-labelKeyboard shortcuts info Press CtrlS to save /div两种方式都满足规则第一种通过aria-describedby建立触发元素与 tooltip 的关联第二种为 tooltip 自身提供aria-label作为可访问名称。实际项目中两者常常结合——aria-describedby用于把内容交给辅助技术roletooltip用于声明语义角色工具类检查如 axe 的aria-tooltip-name检查项会据此判定是否合规。语义细节为什么要roletooltiproletooltip是 WAI-ARIA 1.2 中定义的 widget 角色语义为作为上下文提示的、非关键的补充信息容器。它本身不要求子元素可交互因此 tooltip 内容中的文本会被计算为可访问名称的来源。与之对照aria-describedby建立的是描述关系described-by描述关系不会覆盖元素自身的可访问名称而是作为补充信息在名称之后被播报——这正是 tooltip 的使用场景按钮的名称是 Savetooltip 是额外的保存当前更改到云端描述。仓库中的真实实现Radix UI Tooltip 组件Front-End-Checklist 前端应用apps/web使用 monorepo 中的设计系统包提供 Tooltip 能力实现在 packages/design-system/src/ui/tooltip.tsxuse client import * as TooltipPrimitive from radix-ui/react-tooltip import { cn } from repo/utils import * as React from react const TooltipProvider TooltipPrimitive.Provider const Tooltip TooltipPrimitive.Root const TooltipTrigger TooltipPrimitive.Trigger const TooltipContent React.forwardRef React.ComponentReftypeof TooltipPrimitive.Content, React.ComponentPropsWithoutReftypeof TooltipPrimitive.Content (({ className, sideOffset 4, ...props }, ref) ( TooltipPrimitive.Portal TooltipPrimitive.Content ref{ref} contenteditable="false">【免费下载链接】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），仅供参考 为 Tooltip 提供可访问名称：Front-End-Checklist 的 ARIA Tooltip Name 规则详解与实现指南
为 Tooltip 提供可访问名称Front-End-Checklist 的 ARIA Tooltip Name 规则详解与实现指南【免费下载链接】Front-End-Checklist The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-ChecklistTooltip提示框常承载对完成操作至关重要的补充信息若未能正确命名或与触发元素建立关联屏幕阅读器用户将完全失去这些信息。本文以 Front-End-Checklist 仓库中aria-tooltip-name规则SKILL.md、references/rule.md 与 aria-tooltip-name.mdx为骨架讲解 tooltip 可访问名称的原理、正确写法、例外情况与验证方法并结合仓库内基于 Radix UI 的真实实现tooltip.tsx与相邻规则 accessible-tooltips.mdx帮助你写出可被搜索引擎、Agent 与人工审查一致理解和执行的 tooltip 无障碍代码。规则速览Quick Referencearia-tooltip-name是一条位于accessibility/aria分类下的中优先级、中等难度规则预计修复耗时约 10 分钟元数据定义见 SKILL.mdTooltip 必须有可访问名称accessible name或被触发元素通过aria-describedby引用确保 tooltip 内容对辅助技术assistive technology真正可访问验证 tooltip 与其触发元素trigger之间的关联是否正确建立。该规则对应的中文原义即为 tooltip 提供可访问名称。规则源文件 aria-tooltip-name.mdx 给出了完整的前端元数据priority: medium、difficulty: intermediate、estimatedTime: 10并引用了WAI-ARIA 1.2规范与MDN: ARIA参考文档作为主权威来源sources 中authority: primary。为什么 Tooltip 名称会消失Tooltip 往往只在悬停hover时出现且默认是视觉呈现而非文本节点。在 DOM 中roletooltip的元素本身并不会自动向辅助技术暴露其内容——屏幕阅读器不会因为页面上存在一个 tooltip 就主动朗读它。真正把 tooltip 内容递到屏幕阅读器面前的是以下两条通路之一触发元素通过aria-describedby引用 tooltip 的 id——此时 tooltip 内容会作为触发元素描述的一部分在聚焦/进入无障碍树时被播报tooltip 自身拥有可访问名称如aria-label、aria-labelledby——使其在无障碍树中成为有名节点。如果两条通路都不存在tooltip 内容对屏幕阅读器用户就是隐形的。规则文件 references/rule.md 在Why It Matters中明确了四点价值信息平等Information Equality让不使用鼠标的用户也能获得 tooltip 中隐藏的文本触发感知Trigger Awareness帮助用户理解某个元素为何重要、如何使用WCAG 合规WCAG Compliance满足悬停或聚焦时内容呈现的成功标准对应 WCAG 1.4.13 Content on Hover or Focus 等准则上下文帮助Contextual Help让非视觉用户获得与视觉用户相同的提示信息。正确的代码写法references/rule.md 给出了两条正确的实现路径代码示例完整继承如下!-- ✅ Correct: Trigger references tooltip via aria-describedby -- button aria-describedbytooltip-save Save /button div idtooltip-save roletooltip Saves your current changes to the cloud /div !-- ✅ Correct: Tooltip with its own name -- div roletooltip aria-labelKeyboard shortcuts info Press CtrlS to save /div两种方式都满足规则第一种通过aria-describedby建立触发元素与 tooltip 的关联第二种为 tooltip 自身提供aria-label作为可访问名称。实际项目中两者常常结合——aria-describedby用于把内容交给辅助技术roletooltip用于声明语义角色工具类检查如 axe 的aria-tooltip-name检查项会据此判定是否合规。语义细节为什么要roletooltiproletooltip是 WAI-ARIA 1.2 中定义的 widget 角色语义为作为上下文提示的、非关键的补充信息容器。它本身不要求子元素可交互因此 tooltip 内容中的文本会被计算为可访问名称的来源。与之对照aria-describedby建立的是描述关系described-by描述关系不会覆盖元素自身的可访问名称而是作为补充信息在名称之后被播报——这正是 tooltip 的使用场景按钮的名称是 Savetooltip 是额外的保存当前更改到云端描述。仓库中的真实实现Radix UI Tooltip 组件Front-End-Checklist 前端应用apps/web使用 monorepo 中的设计系统包提供 Tooltip 能力实现在 packages/design-system/src/ui/tooltip.tsxuse client import * as TooltipPrimitive from radix-ui/react-tooltip import { cn } from repo/utils import * as React from react const TooltipProvider TooltipPrimitive.Provider const Tooltip TooltipPrimitive.Root const TooltipTrigger TooltipPrimitive.Trigger const TooltipContent React.forwardRef React.ComponentReftypeof TooltipPrimitive.Content, React.ComponentPropsWithoutReftypeof TooltipPrimitive.Content (({ className, sideOffset 4, ...props }, ref) ( TooltipPrimitive.Portal TooltipPrimitive.Content ref{ref} contenteditable="false">【免费下载链接】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），仅供参考