无障碍评审输出规范：基于 talebook 前端实践的可访问性审查报告（Findings / Verification / Verdict）写作指南-北京尧图网络

后端前端CMS【免费下载链接】talebook一个简单好用的个人书库项目地址https://gitcode.com/gh_mirrors/ta/talebook点击查看免费下载本篇指南围绕仓库内 review-output.md 定义的可访问性Accessibility / a11y评审输出格式展开完整讲解一份独立无障碍评审报告的两段式结构按原则分组的 Findings 表格以及 Verification 与 Verdict 收尾。文章同时结合 talebook 前端实际代码Vue 组件中的aria-label、rolestatus/rolealert活动区、aria-invalid错误状态、:focus-visible焦点环等展示评审结论应如何被引用、验证并形成最终裁决。读完本文你将能按统一格式撰写、评审并裁决无障碍问题让评审结果可以被团队、Agent 与自动化工具直接复用。一、这份规范在解决什么问题无障碍Accessibility审查最大的痛点不是发现不了问题而是问题如何被记录、分级、汇总并形成可执行的结论。talebook 仓库的.agents/skills/better-accessibility/目录为前端界面的可访问性工程定义了完整工作流见 SKILL.md而其中的 review-output.md 单独定义了独立评审standalone review的输出格式。这份规范明确了两件事格式归属当由better-interface跨领域界面评审编排技能见 SKILL.md统筹时评审格式、严重度、合并规则、数量上限与最终裁决都由better-interface拥有better-accessibility只负责提供领域证据与发现。而当进行一次独立standalone的无障碍评审时本规范全面接管。输出结构独立评审报告严格分为两部分——Findings发现与Verification and Verdict验证与裁决。这套设计把证据收集与格式裁决解耦既保证了单领域审查的专业深度又避免了多技能合流时格式互相冲突。从仓库的 Agent 编排文件.agents/skills/better-accessibility/agents/openai.yaml可以看到该技能以独立 Agent 形式存在负责产品界面的可访问性工程。二、Findings按原则分组的发现表独立评审的第一部分是 Findings。规范要求按原则分组所有已确认的发现必须按可访问性原则Principle归类统一表格结构每个分组使用一张 Markdown 表格列为Severity、Location、Before、After、Why禁止散行写法绝不使用独立的 Before: / After: 行一切证据都进入表格单元格合并系统性问题同一根因反复出现的系统性缺陷合并为一行并在该行内列出所有受影响位置省略无发现原则没有任何发现的原则组直接省略不保留空表格。2.1 Severity三档严重度级别判定标准HIGH阻止任务完成、对辅助技术隐藏内容或造成系统性无障碍失败MEDIUM使某个交互对用户而言明显更困难LOW孤立的打磨问题isolated polish这个三档刻度与better-interface的共享严重度一致HIGH 还涵盖误导用户、数据丢失风险、系统性重复失败MEDIUM 涵盖理解力/效率/适应性/一致性的实质性损害LOW 仅限全量模式下收录的有限影响问题。无障碍领域的HIGH 触发条件包括无访问名的交互控件、无可视焦点指示的可键盘聚焦控件、指针可达但键盘不可达的路径、无视prefers-reduced-motion的动效、320px 宽度或 200% 缩放下被裁剪/遮挡/不可达的内容、对比度不达标的正文、仅靠颜色传达的状态以及无确认/撤销/特殊处理的破坏性操作见 better-interface/SKILL.md 第 5 条。2.2 Location证据定位Location列必须给出精确引用有源码工件artifact时path/to/file:line即文件路径:行号没有源码工件时引用确切的界面与组件如设置页-设备列表-删除按钮而不是模糊的页面描述。这一要求与better-interface的证据优先原则Require Evidence呼应每一条发现都必须能追溯到具体的实现位置禁止仅凭视觉观感或仅凭源码推测下结论。2.3 Before / After现状与可执行替代方案Before展示当前实现真实代码片段After给出可操作actionable的替换写法。规范强调 After 必须是可执行的修复例如补上aria-labelClose并把图标标记为aria-hiddentrue而不是一句抽象的提升可访问性。同时修复必须使用项目自身的风格体系the projects own idiomtalebook 是 Vue 组合式 API 内联样式/Vuetify 生态修复建议就应落在该技术栈上而不是引入第二套样式系统见 SKILL.md 引言。2.4 Why指明违反的原则与用户影响Why列回答两个问题违反了哪条可访问性原则对真实用户键盘用户、屏幕阅读器用户、低视力用户、触屏用户产生了什么影响三、规范自带的四组示例原则的落地形态review-output.md 给出了四组完整示例这四组恰好对应 SKILL 中的四条核心原则是评审报告中最常见的四类发现。3.1 Accessible names everywhere访问名无处不在SeverityLocationBeforeAfterWhyHIGHsrc/Dialog.tsx:42buttonXIcon //buttonAddaria-labelClose; mark the iconaria-hiddentrueThe icon-only control has no accessible nameHIGHsrc/Nav.tsx:18a href/settingsGearIcon //aAddaria-labelSettingsThe link destination is unavailable to screen readers图标独占的按钮/链接没有可访问名屏幕阅读器只会读到空洞的button。修复要点aria-label给出名字装饰性图标用aria-hiddentrue从无障碍树中剔除绝不能加在可获得焦点的元素上见 semantics-and-aria.md。3.2 Visible focus rings可见焦点环SeverityLocationBeforeAfterWhyHIGHsrc/button.css:12button:focus { outline: none; }button:focus-visible { outline: 2px solid; outline-offset: 2px; }Keyboard users cannot see focusHIGHsrc/Menu.tsx:31focus:outline-nonefocus-visible:outline-2 focus-visible:outline-offset-2Menu navigation has no visible focus indicator焦点环应使用:focus-visible而非裸:focus——键盘与辅助技术聚焦时显示鼠标点击时通常不显示避免视觉噪音。绝不写outline: none而没有可见替代见 focus-and-keyboard.md。3.3 Errors that announce可播报的错误SeverityLocationBeforeAfterWhyHIGHsrc/EmailField.tsx:27Error shown only asborder-red-500Addaria-invalidtruearia-describedbyemail-errorwith inline error textColor alone neither explains nor announces the errorMEDIUMsrc/SignupForm.tsx:64Submit disabled until the form is validKeep submit enabled; on failure, focus the first invalid fieldA disabled action hides what must be fixed错误不能只靠颜色传达失败字段加aria-invalidtrue用aria-describedby指向行内错误文本错误信息跟随字段被屏幕阅读器播报提交按钮保持可用在提交时校验并把焦点移到第一个无效字段详见 forms.md。3.4 Minimum hit area最小点击区域SeverityLocationBeforeAfterWhyMEDIUMsrc/Toolbar.tsx:22size-4icon-only buttonExtend the hit area to 44×44px withafter:absolute after:size-11The target is too small for reliable touch input触屏目标过小导致误触。WCAG 2.5.8AA硬性底线是24×24 CSS 像素触屏上下文推荐 44×44px桌面推荐 40×40px可见元素可以保持小尺寸通过伪元素扩展命中区域且扩展区域不得与其他交互元素重叠见 hit-areas.md。四、源码证据talebook 前端的无障碍实现对照规范要求评审的 Location 引用path/to/file:line而 talebook 的 Vue 组件中恰好存在大量可被评审引用的真实实现。以下是从 app/components 提取的实现事实可作为合格实现的正面样本也可作为评审定位格式的练习素材。4.1 访问名从 i18n 取值的 aria-label图标按钮普遍使用:aria-label提供访问名且文案来自 i18n 键talebook 的中英文案见 app/i18n/locales/zh-CN.json 与 en-US.jsonAnnotationPanel.vue刷新按钮:aria-labelt(annotations.refresh)AudioJobsPage.vue刷新t(common.refresh)L114 打开书籍任务按钮t(audiobook.openBookJob, { title: job.book.title })L351 关闭按钮t(common.close)AudiobookPlayer.vue播放/暂停按钮的访问名随状态切换player.playing ? t(audiobook.pause) : t(audiobook.play)。其中AudioJobsPage.vue:114把书名动态拼进访问名打开书籍任务《xxx》正是可访问名应描述操作与对象的良好实践——评审中若发现类似的动态语义应判定为合格而非误报。4.2 活动区live regionrolestatus 与 rolealert动态内容更新需要播报机制。规范与 screen-readers.md 给出的选择顺序是焦点本身移动 →aria-describedby绑定字段 → 非紧急用rolestatuspolite→ 紧急用rolealertassertive。talebook 组件中两者皆有加载/状态播报AnnotationPanel.vue:91div rolestatus aria-livepolite、AuthorAliasPanel.vue:9、MetaList.vue:20与LibraryChipFilter.vue:69/164的rolestatus紧急错误播报BrsAccountSettings.vue:108、LibraryChipFilter.vue:129、MetaList.vue:35的rolealertPluginCapabilityTester.vue:101也使用了rolestatus。评审时可对照检查常规 toast 或结果计数用 politerolestatus只有表单级/页面级紧急错误才允许 assertiverolealert滥用assertive是常见失误见 SKILL.md Common Mistakes。4.3 表单错误状态aria-invalid 行内错误BrsAccountSettings.vue 是表单错误处理的完整样本多个字段按校验结果动态绑定:aria-invalidBoolean(fieldErrors.endpoint)L43、L58、L73、L88配合rolealert区域播报表单级错误。这正符合错误必须可播报、不能只靠颜色的规范要求——评审报告中的aria-invalid与aria-describedby建议在该组件中已有对应实现可参照。4.4 焦点环组件内 :focus-visible 样式AudioJobsPage.vue 的.job-plan-toggle:focus-visible { outline: 3px solid rgba(217,154,43,.42); outline-offset: 4px; }与 LibraryChipFilter.vue 的.library-filter-control:focus-visible均使用:focus-visible而非裸:focus且自定义环带显式颜色与偏移——符合优先保留浏览器环自定义环必须验证与相邻颜色的对比的原则见 focus-and-keyboard.md。需要说明以上仅是从源码结构可确认的实现事实。它们不代表这些组件通过了完整评审按规范第 8 条Verify What Can Be Verified最终裁决必须基于真实运行的检查键盘走查、可访问名检查、屏幕阅读器测试而非代码阅读。五、Verification and Verdict验证与裁决Findings 之后是报告的第二部分包含两个强制步骤5.1 Verification验证列出实际执行过的检查及其观察结果包括键盘遍历keyboard traversal每个流程能否脱离鼠标完成可访问名检查accessible-name inspection每个交互控件是否播报名称、角色与状态屏幕阅读器或自动化检查screen-reader / automated checks适用时记录工具与结果诚实标注未验证项如果某项检查没有运行必须明确写出仍需要验证什么而不是默认通过。这与 SKILL 的评审方法论一致——先用纯键盘走完整条流程再以屏幕阅读器用户身份走查每个控件是否播报名称、角色与状态见 SKILL.md。评审只读不改验证缺口永远不能转变成一条发现。5.2 Verdict裁决裁决只有三种规则明确裁决触发条件Block仍存在任意一条 HIGH 发现Needs changes仅剩 MEDIUM 或 LOW 发现Approve不再存在任何可操作actionable发现5.3 零发现场景当评审没有任何发现时省略所有表格不保留空表直接声明No actionable accessibility findings报告验证过程与结果以Approve结尾。六、与 better-interface 编排的关系谁拥有格式与裁决规范开头特别划清了职责边界这是报告可被多技能复用而不冲突的关键独立评审时review-output.md拥有格式、严重度、合并、上限与裁决由better-interface统筹时编排技能拥有格式、严重度、合并规则、发现上限与裁决better-accessibility只交付领域证据与发现domain evidence and findings。better-interface的编排规则进一步说明当领域技能经由它加载时要应用其原则与参考文档但忽略其 Reporting 章节及其指向的 review-output.md改用统一合并格式、共享严重度与上限若该技能不可用该领域标记为Not reviewed并写明缺失技能不得用相邻技能顶替见 better-interface/SKILL.md 第 3 条。若评审范围来自版本控制分支/PR/未提交改动则属于interface-review的变更评审范畴better-interface不代行解析变更范围。理解这层编排者 vs 领域技能的职责划分能帮助你在实际工作流中正确选择输出模板单领域深度审查用本规范的两段式独立报告跨领域综合评审用better-interface的合并报告含 Scope and Coverage、Considered but Rejected、Verification、Verdict 与变更评审扩展节。七、实操清单按本规范产出一份评审报告确定评审主体确认是独立无障碍评审用本格式还是better-interface统筹移交编排。按原则分组参考 SKILL.md 的 Quick Reference 确定检查维度——Focus Keyboard、Semantics ARIA、Forms、Screen Readers、Hit Areas、Motion Zoom。收集证据逐条确认发现Location 必须精确到path/to/file:line无源码时引用确切界面与组件。合并系统性问题同一根因的多处位置合并为一行全部列出。判定严重度对照 HIGH/MEDIUM/LOW 定义better-interface的触发清单一旦命中即 HIGH。补齐 Verification记录真实执行的检查与观察结果诚实标注未验证项。给出唯一裁决Block/Needs changes/Approve与剩余发现的严重度严格对应。按照这套流程产出的报告每一条发现都具备原则位置现状替代方案影响的完整证据链验证过程可复现裁决规则无歧义——这正是无障碍评审从主观意见走向可审查、可引用、可执行的关键。相关文档索引输出格式规范本体.agents/skills/better-accessibility/review-output.md无障碍技能总纲14 条核心原则与常见失误表.agents/skills/better-accessibility/SKILL.md领域细则focus-and-keyboard.md、semantics-and-aria.md、forms.md、screen-readers.md、hit-areas.md、motion-and-zoom.md编排者技能格式/严重度/裁决的另一个所有者.agents/skills/better-interface/SKILL.md源码对照样本app/components含 AnnotationPanel、AudioJobsPage、AudiobookPlayer、BrsAccountSettings、LibraryChipFilter、MetaList 等赞分享后端前端CMS【免费下载链接】talebook一个简单好用的个人书库项目地址https://gitcode.com/gh_mirrors/ta/talebook点击查看免费下载相关推荐Fleet一个开源设备管理平台管住数千台跨平台设备Fleet一个开源设备管理平台管住数千台跨平台设备 Fleet 是一个开源设备管理平台把 Linux、macOS、Windows、iOS/iPadOS、An后端前端CMSTalebook 前端色彩审查报告规范基于 OKLCH 的 Findings 表、验证清单与裁决机制Talebook 前端色彩审查报告规范基于 OKLCH 的 Findings 表、验证清单与裁决机制本文档是 talebook 仓库内嵌的前端设计审查技能后端前端CMSVPet 虚拟桌宠32 种动画 × 4 种状态用 PNG 序列帧免费做出你的桌面宠物VPet 虚拟桌宠32 种动画 × 4 种状态用 PNG 序列帧免费做出你的桌面宠物屏幕右下角停着一只小猫你可以摸它的头、喂它喝饮料、把它提起来晃它还桌面应用游戏开发上一篇三步给WeMod装一个本地远程控制面板Wand-Enhancer实战手记下一篇如何用SMUDebugTool解锁AMD Ryzen的隐藏性能免费调试工具从入门到进阶创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

无障碍评审输出规范：基于 talebook 前端实践的可访问性审查报告（Findings / Verification / Verdict）写作指南

相关推荐

熵权法+物元可拓模型MATLAB实现：水质综合评价与等级判定完整指南

RimSort 跨平台安装与配置实战指南：Stable/Edge 发行版选择、系统依赖与 RimWorld 路径详解

职场高效必备：5款实用办公软件助你事半功倍，TaoToken统一API接入实测

更多资讯

从零搭建UVM验证平台：以AHB SRAMC为练手项目

C++实现Prim算法生成随机迷宫：核心原理与完整代码解析

AI辅助测试真实降本指南：从用例生成到缺陷定位的省钱分析

VSCode创建Vue项目全攻略：快捷键、插件与Vite实战

SAP FICO中F.27客户对账单打印全解析：从配置到排障

Hermes Agent + Obsidian 打造第二大脑（五）：Templater、Dataview、QuickAdd 插件配置与效率提升完整指南

今日更新

CMOS设计三大物理效应：体效应、沟道长度调制与亚阈值导电

微信小程序在线阅读毕设全解析：Java后端+MySQL+避坑实战

Android音频问题五层分析法：从App到Codec的系统化诊断

本周精选

CMOS设计三大物理效应：体效应、沟道长度调制与亚阈值导电

微信小程序在线阅读毕设全解析：Java后端+MySQL+避坑实战

Android音频问题五层分析法：从App到Codec的系统化诊断

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？