Langflow 前端 IBM Equal Access Level 1 无障碍审计实战审计流程、双引擎扫描与报告规范【免费下载链接】langflowLangflow is a powerful tool for building and deploying AI-powered agents and workflows.项目地址: https://gitcode.com/GitHub_Trending/la/langflow本文围绕 Langflow 仓库中定义在 .agents/skills/ibm-a11y-level1-audit/SKILL.md 的 IBM 无障碍 Level 1 审计技能展开完整讲解“定界 → 扫描 → 映射标准 → 写报告 → 可选修复 → 验证 → 闭环”的七步审计工作流。读完后你将掌握如何在 Langflow 前端指定路由、组件或 PR 范围内执行 IBM Equal Access Toolkit v7.3 Level 1 合规审计如何使用 Playwrightpage.runA11yScan与 Python 路线扫描器双引擎取证如何把扫描结果映射到 WCAG/IBM 标准编号以及如何按仓库既定的报告模板产出可验证的审计结论。一、技能定位默认只审计、只报告不修代码该审计技能对选定 Langflow 前端表面路由、组件或一个 PR执行范围受限的 IBM Equal Access Level 1 合规审计交付物映射到 WCAG/IBM Level 1 标准。SKILL.md 对边界做了两条硬约束范围只限 Level 1。标准基准是 IBM Equal Access Toolkit v7.3 的 Level 1除非用户明确要求不扩展到 Level 2/3默认交付物是报告不是 diff。只有当用户在同一条请求中明确要求修复如“audit and fix”“fix what you find”时才进入修复步骤。仓库里与它配套的还有三个相邻技能构成完整的无障碍工作流分工技能用途ibm-a11y-testing-guide如何编写/运行 axe IBM 扫描、基线机制、组件陷阱ibm-a11y-route-scanPython 路线扫描器 Markdown/HTML 报告生成批量扫路由但不产出审计结论ibm-a11y-pr-remediation对整个 PR/分支“扫描并默认修复”frontend-i18n新增/变更可访问名称或 UI 文案时走国际化流程三份“事实来源”Sources of truth决定了审计的判定依据Level 1 标准工程指南.agents/skills/ibm-a11y-level1-audit/references/ibm-level1-criteria.md —— 完整清单、缓延到 L2/L3 的条目、常见失败模式与实现范式Langflow 抓取的 IBM Level 1 过滤结果src/frontend/tests/a11y/ibm-able-level-1-requirements.md —— 从 IBM Able UI Level 1 过滤器抓取的 21 条要求对应 IBM 版本 7.3。两者节奏不一致时以工程指南为准但结果应尽可能映射到两套编号验证宿主src/frontend/tests/a11y/ —— Playwright 规格、基线、README。技能明确要求“在声称覆盖之前先确认该路径存在”。二、审计基准IBM Level 1 到底审哪些标准2.1 Level 1 的定位IBM 把无障碍要求按“完成节奏”pace of completion划分为三个渐进级别Level 1 是最高用户影响、最低投入的关键任务集Level 2 是可能阻止部分用户完整使用产品的次优先问题Level 3 对应完整的 WCAG 2.2 A/AA 合规。工程指南中特别强调只做 Level 1 不等于达成完整 WCAG 合规它是发布规划周期中的第一优先级阶段但许多要求仍可判定为“Support”符合度。Level 1 的覆盖范围是基础 WCAG 2.0 A/AA 标准 1.4.10 ReflowIBM 在 v7.3 中唯一按 Level 1 节奏排期的 WCAG 2.1/2.2 新增项。2.2 四大原则下的 Level 1 标准清单以下清单完整继承自 references/ibm-level1-criteria.md是审计时给每条发现finding编号的依据原则 1可感知Perceivable#要求关键规则Level 1 任务1.1.1非文本内容所有非文本内容必须有文本替代图片、图标、图形、CAPTCHA 的 alt 文本1.3.1信息与关系视觉传达的结构必须是程序化的语义化 HTML标题、列表、表格、表单1.3.2有意义的顺序阅读顺序必须程序化正确DOM 顺序匹配视觉阅读顺序1.3.3感官特征指令不能只依赖形状/位置形状/位置引用旁附文字标签1.4.1颜色使用颜色不能是唯一的视觉提示颜色指示器旁加图标、图案或文字1.4.2音频控制自动播放超 3 秒的音频需停止/暂停控制提供独立于系统的音量/静音控制1.4.3对比度最低文本须满足对比度比例正文4.5:1大文本18pt/14pt 粗体3:11.4.4文本缩放文本须可放大至 200% 而不丢失200% 缩放下不得裁剪、重叠、隐藏文本1.4.5文本图片用真实文本代替文本图片图像文字替换为 HTML/CSS 文本1.4.10回流内容不得出现水平滚动320px 宽度桌面 400% 缩放下布局成立原则 2可操作Operable#要求关键规则Level 1 任务2.1.1键盘所有功能必须可键盘操作每个交互元素可被键盘触达并使用2.1.2无键盘陷阱焦点永远不能被困住用户总能 Tab 出去Escape 关闭模态/浮层2.2.1时间可调时限必须可调整会话超时允许 10 倍延长或关闭2.2.2暂停、停止、隐藏移动/自动更新内容须可暂停轮播、滚动条、自动切换幻灯片提供暂停控制2.3.1三次闪烁以下内容闪烁不得超过每秒 3 次消除或对闪烁内容做阈值测试2.4.1绕过区块必须提供跳过导航或地标区域实现 ARIA 地标main、nav、banner、footer2.4.2页面标题每个页面/文档需要描述性标题唯一title“页面名 – 应用名”模式2.4.3焦点顺序Tab 顺序必须保留语义DOM 顺序匹配视觉顺序不得随意使用tabindex2.4.4链接目的链接文本必须描述目的地避免“点击这里/”用描述性文本或aria-label2.4.5多种方式提供多种页面导航方式搜索 导航菜单2.4.6标题与标签标题和标签必须具有描述性每个标题唯一描述其统领的区块2.4.7焦点可见键盘焦点指示器必须可见不得在未提供可见替代时抑制outline原则 3可理解Understandable#要求关键规则Level 1 任务3.1.1页面语言页面语言必须程序化标识html元素设置lang属性3.1.2部分语言内容中的语言切换必须标记内嵌异语言文本加lang属性3.2.1焦点时获得焦点不得触发上下文变化焦点不触发表单自动提交或页面跳转3.2.2输入时改变 UI 设置不得自动改变上下文下拉切换导致导航时要警告用户3.2.3一致导航重复的导航必须以相同顺序出现导航菜单、页眉页脚跨页面一致3.2.4一致识别同功能组件必须以同样方式识别“搜索”的图标与 alt 文本跨页面一致3.3.1错误标识错误必须指出字段并描述问题仅红色边框不够须有文字错误消息3.3.2标签或说明所有输入必须有标签或说明每个输入字段有可见label或aria-label3.3.3错误建议已知时提供修正建议如“请输入有效邮箱如 userexample.com”3.3.4错误预防法律/财务/数据操作必须可逆或可确认破坏性操作提供确认步骤或撤销选项原则 4健壮Robust#要求关键规则Level 1 任务4.1.2名称、角色、值所有 UI 组件必须向辅助技术暴露名称、角色与状态使用语义化 HTML 或正确的 ARIA roles/states/properties缓延到 Level 2/3 的标准不属于 Level 1 发布范围审计中遇到即剔除或缓延1.3.4 Orientation、1.4.11 Non-text Contrast、1.4.13 Content on Hover or Focus、2.4.11 Focus Not Obscured (Minimum)WCAG 2.2、2.5.1 Pointer Gestures、2.5.3 Label in Name、2.5.4 Motion Actuation、2.5.7 Dragging MovementsWCAG 2.2、2.5.8 Target Size (Minimum)WCAG 2.2、4.1.3 Status Messages 均为 Level 21.3.5、1.4.12、2.1.4、2.5.2、3.2.6、3.3.7、3.3.8 均为 Level 3。媒体类 1.2.x 仅在表面含音视频时适用字幕1.2.2/1.2.4属 Level 1音频替代与音频描述1.2.1/1.2.3/1.2.5属 Level 3。Section 508 的软件专用条目502.2.1/502.2.2/502.3.1–502.3.5针对非 Web 软件单独跟踪Web UI 大体由 4.1.2 覆盖。2.3 常见失败模式速查工程指南列出了一组“高频翻车点”审计与修复时可直接对照div/span当按钮用但没有键盘/ARIA 支持 → 改用button或补rolebuttontabindex0 键盘处理有意义图片上写alt→ 写描述图片用途的 altplaceholder作为输入框唯一标签 → 必须有可见label仅用颜色指示必填/错误 → 加星号、图标或文字CSS 全局移除 focus outline → 保留并样式化模态打开时焦点未移入、关闭时焦点未还给触发元素 → 打开聚焦首个元素关闭focus()触发器aria-label不含按钮可见文本 →aria-label应以可见文本开头非紧急消息滥用rolealert→ 改用rolestatusaria-livepolite。三、七步审计工作流SKILL.md 给出了可直接复制跟踪的进度清单Level 1 Audit Progress: - [ ] 1. Scope the surface 界定审计表面 - [ ] 2. Scan (IBM axe) 双引擎扫描 - [ ] 3. Map findings to Level 1 映射到 Level 1 标准 - [ ] 4. Write the report 撰写报告 - [ ] 5. Fix violations 修复仅当用户明确要求 - [ ] 6. Verify with tests/a11y 验证仅当第 5 步执行 - [ ] 7. Re-scan and update status 复扫并更新报告状态仅当第 5 步执行步骤 1界定审计表面从用户请求中确定审计对象三类来源具体路由/页面/组件src/frontend下的待提交 git 变更缺省情况下为静态路由 触及变更表面的有状态规格。动手前先读 src/frontend/tests/a11y/README.md 并列出已覆盖该表面的既有规格——该 README 明确了 Langflow 的两层扫描体系本目录下的 Playwright 规格是回归宿主GitHub Actions 通过.github/workflows/a11y-scan.yml运行所有调用page.runA11yScan(...)的规格而scripts/a11y/a11y_scan.py是按需路线/报告工具。步骤 2双引擎扫描交互型 UI 表面必须同时跑两个引擎理由与规则差异见 ibm-a11y-testing-guideaxe-core 跑在 jsdom快且擅长对比度、标签、角色IBM Equal AccessaChecker对 ARIA 结构与键盘语义更严格能抓到 axe 静默放过的真实 WCAG Level 1 问题如aria_accessiblename_exists、aria_child_valid、aria_hidden_focus_misuse。典型命令# Playwright IBM 扫描真实 DOM / 有状态表面 cd src/frontend RUN_A11Ytrue RUN_A11Y_ASSERTtrue npx playwright test tests/a11y/feature.a11y.spec.ts --projectchromium --workers5 # 可选HTML 分诊报告package.json 中 a11y:html-report 指向 node tests/utils/build-a11y-html-report.mjs npm run a11y:html-report --silent # → coverage/accessibility-reports/index.html # 临时路线批量扫描仅默认加载页面——详见 ibm-a11y-route-scan uv run --with playwright python scripts/a11y/a11y_scan.py \ --url http://localhost:3000 \ --routes-file scripts/a11y/a11y_routes.json \ --route-group static \ --out /tmp/langflow-a11y.json \ --markdown /tmp/langflow-a11y.md \ --html /tmp/langflow-a11y.html \ --timeout-ms 45000环境要点RUN_A11Ytrue启用扫描RUN_A11Y_ASSERTtrue让新违规真正导致测试失败否则扫描仅供参考。Python 扫描器的 Playwright 依赖不在默认uv sync中需一次性执行uv run --with playwright playwright install chromium。从源码看scripts/a11y/a11y_scan.py 是一个“带 API 请求跟踪的路线感知 IBM ACE 扫描器”它支持--routes逗号分隔、--route可重复、--routes-file--route-group路线清单分组默认static、--states-file路由加载后执行模态/状态动作、--levelsviolation,potentialviolation,recommendation,manual默认violation、--timeout-ms默认 30000等参数并默认从 CDN 拉取 ACE 脚本--ace-url可覆盖。配套的路线清单 scripts/a11y/a11y_routes.json 按static/dynamic/gated/excluded四组管理static组给出 13 条可直接扫描的路由/flows、/components、/mcp、/assets/files、/assets/knowledge-bases及 7 条/settings/*路由每条附稳定的ready就绪判定如mainpage_titletestIddynamic组记录需要真实数据的路由模板flow 编辑器、共享 playground、KB 分块页gated组是登录/注册页已登录会重定向须以未登录模式扫描excluded组则逐条说明为何排除运行时重定向、仅数据不同的同组件变体等。组件级变更还应跑 Jest axe当存在__tests__/*.a11y.test.tsx时。SKILL.md 同时警告不要编造发现。优先相信扫描器输出并补做扫描器漏掉的 Level 1 人工检查双向键盘陷阱、焦点恢复、320px 回流、非纯色提示。步骤 3把发现映射到 Level 1每条问题须赋三要素WCAG / IBM 标准编号来自 references/ibm-level1-criteria.md如2.1.1、4.1.2IBM ruleId若来自 Equal Access如aria_accessiblename_exists、element_tabbable_role_valid严重级别violation|potentialviolation|manual。凡落在标准文档“缓延到 Level 2 Level 3”一节中的条目除非用户扩大范围一律剔除或缓延。步骤 4按模板撰写报告报告结构由 references/report-template.md 规定必含六个部分Summary——发现总数violation/potential/manual 分布、fixed/baselined/open 数量、验证结论PASS/FAIL/PARTIAL 及对应tests/a11y/...Scope——范围内页面/状态、范围外缓延 L2/L3 未扫描状态及原因、查阅过的规格Findings 表格——列为ID | Criterion | Rule / evidence | Location | Severity | Status | Notes状态取open | fixed | baselinedFixes——每条已修复发现写“改了什么、为什么”及触及文件Verification——执行命令、更新/新增的规格与基线、HTML 报告路径coverage/accessibility-reports/index.htmlRemaining risk——遗留 Level 1 问题、被接受基线路径原因、尚未执行的人工检查。报告默认交付在对话中只有用户给出文件路径要求时才落盘。到这里默认停止修复建议只写在报告里不动文件——除非用户的请求本来就要求修复。步骤 5修复违规仅在明确要求时继续修复的准则语义化 HTML 优先于 ARIA遵循 Langflow 既有模式见 ibm-a11y-testing-guideAG Grid、RadixasChild、焦点恢复、图标按钮aria-label新增 UI 字符串/aria-label走frontend-i18n流程不得静默禁用扫描IBM 基线src/frontend/tests/a11y/baselines/只用于有文档记录的框架级债务修复保持最小化不重构无关 UI。步骤 6用tests/a11y验证按表面选择对应规格运行/更新验证宿主目录为 src/frontend/tests/a11y/表面规格静态路由static-routes.a11y.spec.ts新增路由时同步 scripts/a11y/a11y_routes.json认证auth-pages.a11y.spec.ts核心页面core-pages.a11y.spec.ts数据密集files、API keys、globalsfiles.a11y.spec.ts、api-keys.a11y.spec.ts、global-variables.a11y.spec.ts其他数据密集data-rich-routes.a11y.spec.ts基线baselines/*.jsoncd src/frontend RUN_A11Ytrue RUN_A11Y_ASSERTtrue npx playwright test tests/a11y/relevant.a11y.spec.ts --projectchromium --workers5若修复后的状态没有测试覆盖参照files.a11y.spec.ts/api-keys.a11y.spec.ts的模式补扫描修过自定义键盘行为时还要补键盘测试。这两个“数据密集路由”规格是仓库内的参考实现mock API 数据后扫描“有数据/空/创建模态/结果模态/文本单元模态/行选中/移动端”等状态例如 files.a11y.spec.ts 覆盖assets-files-data-rich、assets-files-empty、assets-files-uploading、assets-files-error、assets-files-row-selected、assets-files-actions-menu等十余个扫描标签api-keys.a11y.spec.ts 同样按“有数据→空态→创建模态→生成模态→选中态→移动端”逐状态扫描。步骤 7闭环重跑同一批扫描把报告中每条发现更新为fixed|baselined|open并声明执行的命令与 IBM assert 模式是否通过。四、扫描器覆盖不到的 Level 1 人工检查项自动化扫描会漏掉部分 Level 1 任务审计时按下表人工抽查2.1.1 / 2.1.2Tab 与 ShiftTab 走完全表面Escape 能关闭浮层无焦点陷阱注意 ShiftTab 反向也要测2.4.3 / 2.4.7焦点顺序匹配视觉顺序焦点环可见1.4.10320px 宽度 / 约 400% 缩放下无必要水平滚动1.4.1状态/错误不得仅用颜色提示3.3.1 / 3.3.2错误以文字命名并与字段关联所有输入有标签。五、纵深案例AG Grid 数据表格 模态的 Level 1 最佳实践审计设置页表格尤其是/settings/global-variables这类“AG Grid 模态”组合时SKILL.md 把下列实践当作 Level 1 基线2.1.1 / 2.4.3而非边角陷阱。参考实现是GlobalVariablesPage与 tests/a11y/global-variables.a11y.spec.ts。5.1 可选行的键盘映射按键行为Space切换该行选择复选框不打开编辑Enter打开聚焦行的 Update Variable 模态实现要点与 ibm-a11y-testing-guide 的“Best practices (settings grids modals)”一节一致只在页面级onCellKeyDown中处理不要改动共享TableComponent默认值除非产品要求全应用同一映射对该页列定义对 Enter/Space 加suppressKeyboardEvent避免 AG Grid 内置 Space 选择行为与自定义处理器打架node.setSelected之后同步 React 选择状态保证工具栏删除按钮的可用状态正确TableOptions.hasSelection在渲染时读取。5.2 模态开闭焦点“原位保留”focus restore从行/单元格打开编辑时必须记住被聚焦的单元格rowIndexcolId关闭编辑模态Escape、Cancel 或保存成功时通过api.setFocusedCell DOM.focus()把焦点恢复到同一单元格并用若干次requestAnimationFrame压过 Radix 对话框的焦点清理时序由Add New打开的创建模态应恢复焦点到触发按钮存在真实DialogTrigger时由 Radix 默认完成用 Playwright 键盘测试验证从单元格打开 → Escape →document.activeElement仍是该单元格或其col-id→ 再次 Enter 能直接打开无需鼠标重新聚焦。仓库中的测试正是这么写的opens edit modal from a focused row with Enter用page.evaluate轮询断言关闭模态后document.activeElement的col-id仍为name随后按 Enter 期望出现名为 “Update Variable” 的对话框紧随其后的restores focus to the last table cell after edit modal closes用例则专门固化这条 2.4.3 要求。同类规格中还有大量aria-selected状态断言如选中行后delete-row-button必须变为可用说明“状态扫描 键盘测试”共同构成该页面的 Level 1 证据链。AG Grid 其他高频陷阱分页按钮禁用时保持tabindex-1但绝不用inert/disabled、图标操作列须给headerName以产生columnheader可访问名、单元格内交互控件须经onCellKeyDown激活、无边框网格恢复:focus-visible焦点环、ensureDomOrder: true等详见 ibm-a11y-testing-guide 的 Gotchas 章节。5.3 基线机制把框架债务变成可追踪资产当违规真实存在但属于框架级、无法逐页修复时例如 Radix 菜单 portal 到body触发aria_content_in_landmark正确做法不是删断言而是写入 IBM 基线文件让扫描保持绿色、债务有据可查。从源码结构看基线匹配依据path.domruleIdreasonId精确命中命中结果标记为ignored: true断言统计只数violation !ignored。仓库中现存两个基线文件即可印证命名规则{project}__{scan label}.jsonbaselines/chromium__assets-files-actions-menu.json 与 baselines/chromium__settings-mcp-servers-actions-menu.json。流程是跑一次扫描把完整报告写到coverage/accessibility-reports/{label}.json→ 把 offending 结果以{ results: [ { ruleId, reasonId, path: { dom: … } } ] }形式拷入tests/a11y/baselines/{label}.json建议附description说明原因→ 复扫通过并提交基线删除基线文件即令违规复现。六、明确的范围外除非用户要求标准参考文档中缓延到 Level 2/3 的条目Section 508 软件专用条目Web UI 已由 4.1.2 覆盖表面不含音视频时的媒体字幕1.2.x未经明确修复请求的违规修复默认只报告。小结Langflow 的这套 Level 1 审计体系由三层证据构成以 SKILL.md 为流程骨架、以 ibm-level1-criteria.md 与 ibm-able-level-1-requirements.md 双标准源为判定依据、以 src/frontend/tests/a11y/ 的 Playwright 规格/基线和 scripts/a11y/a11y_scan.py 路线扫描器为验证宿主。执行时把握三条纪律双引擎axe IBM都跑且都要零新增违规发现必须能落到标准编号 ruleId 严重级别没有明确修复请求时止步于报告。【免费下载链接】langflowLangflow is a powerful tool for building and deploying AI-powered agents and workflows.项目地址: https://gitcode.com/GitHub_Trending/la/langflow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考