Langflow 前端无障碍合规IBM Equal Access Level 1 标准与 WCAG 2.2 工程落地指南【免费下载链接】langflowLangflow is a powerful tool for building and deploying AI-powered agents and workflows.项目地址: https://gitcode.com/GitHub_Trending/la/langflow本文基于 Langflow 仓库中ibm-a11y-level1-audit审计技能的参考文档 ibm-level1-criteria.md完整讲解 IBM Equal Access Toolkit v7.3 的 Level 1 无障碍标准三大递进节奏等级、四原则下的 Level 1 需求清单、工程实现模式与测试工具链并结合 Langflow 前端真实仓库中的 Playwright 扫描规范、批量路由扫描脚本与报告模板给出从标准理解到 CI 验证的可复制落地路径。1. 什么是 IBM Level 1按完成节奏分级的无障碍标准IBM 将无障碍需求划分为三个递进的**完成节奏pace of completion**等级。IBM 不是把每一条 WCAG 成功标准整体映射到某个等级而是将每条需求下 Design、Develop、Test 各领域的具体任务分配到不同等级让团队可以增量地采用无障碍能力等级目标Level 1基础任务——用户影响最大、投入最少解决残障用户最核心的痛点Level 2次优先级问题不解决可能导致部分用户无法完整使用产品Level 3完整 WCAG 2.2 A/AA 合规——三个等级必须合并完成后才构成完整合规重要前提仅完成 Level 1 并不等于达到完整 WCAG 合规它代表发布规划周期中的第一优先级阶段。但仅完成 Level 1 的产品仍然能获得可观的无障碍收益且许多需求在合规声明中可标记为 Support。该指南的适用范围是仅覆盖 IBM Level 1 节奏内的需求即 WCAG 2.0 Level A/AA 的基础标准加上唯一的 WCAG 2.1/2.2 新增项1.4.10 ReflowIBM 将其节奏定为 Level 1。少数保留的需求还带有 Level 2/3 的后续任务例如 1.3.1 下的数据表格要求、媒体替代方案这些后续任务不在 Level 1 范围内。所有被 IBM 整体定级为 Level 2 或 Level 3 的需求全部 WCAG 2.1/2.2 新增标准以及媒体的语音描述标准都列在第 4 节推迟到 Level 2 与 Level 3中。2. Level 1 需求快速核对清单按 WCAG 四原则2.1 原则一可感知Perceivable编号需求关键规则Level 1 任务1.1.1Non-text Content所有非文本内容必须有文本替代图片、图标、图形、CAPTCHA 的 alt 文本1.3.1Info and Relationships视觉传达的结构必须可编程获取语义化 HTML标题、列表、表格、表单1.3.2Meaningful Sequence阅读顺序必须在程序上正确DOM 顺序与视觉阅读顺序一致1.3.3Sensory Characteristics指令不能只依赖形状/位置形状/位置指示旁附带文字标签1.4.1Use of Color颜色不能是唯一的视觉线索颜色指示旁增加图标、纹理或文字1.4.2Audio Control自动播放超过 3 秒的音频需停止/暂停控件提供独立于系统的音量或静音控件1.4.3Contrast (Minimum)文本必须满足对比度比例正文 4.5:1 · 大文本 3:118pt / 14pt 粗体1.4.4Resize Text文本放大 200% 不丢失内容200% 缩放下不裁剪、不重叠、不隐藏1.4.5Images of Text用真实文本代替图片文字图片文字替换为 HTML/CSS 文本1.4.10Reflow内容重排无水平滚动布局在 320px 宽度下正常工作桌面 400% 缩放2.2 原则二可操作Operable编号需求关键规则Level 1 任务2.1.1Keyboard所有功能必须可键盘操作每个交互元素可被键盘到达并使用2.1.2No Keyboard Trap焦点绝不能被困住用户总能 Tab 离开Escape 关闭模态/浮层2.2.1Timing Adjustable时间限制必须可调会话超时允许 10 倍延长或关闭2.2.2Pause, Stop, Hide移动/自动更新内容必须可暂停轮播、跑马灯、自动切换幻灯片的暂停控件2.3.1Three Flashes内容闪烁不超过每秒 3 次消除或阈值测试所有闪烁内容2.4.1Bypass Blocks必须可跳过代码块实现 ARIA 地标main、nav、banner、footer2.4.2Page Titled每个页面需要描述性标题唯一title页面名 – 应用名 模式2.4.3Focus OrderTab 顺序必须保持语义DOM 顺序与视觉顺序一致不随意使用tabindex2.4.4Link Purpose链接文本必须描述目的地避免 click here / read more用描述性文本或aria-label2.4.5Multiple Ways提供多种导航方式搜索 导航菜单2.4.6Headings and Labels标题和标签必须描述性每个标题唯一描述其所辖章节2.4.7Focus Visible键盘焦点指示必须可见不得抑制outline而无可见替代2.3 原则三可理解Understandable编号需求关键规则Level 1 任务3.1.1Language of Page页面语言必须可编程识别在html上设置lang属性3.1.2Language of Parts内容中的语言切换必须标记内嵌不同语言文本加lang属性3.2.1On Focus获得焦点不能引发上下文变化禁止聚焦触发表单自动提交或页面跳转3.2.2On Input改变 UI 设置不能自动改变上下文下拉框切换导致跳转时必须警告用户3.2.3Consistent Navigation重复导航必须同序出现各页面的导航菜单、页眉、页脚保持一致3.2.4Consistent Identification相同功能的组件识别方式一致Search 的图标与 alt 文本跨页面相同3.3.1Error Identification错误必须指明字段并描述问题仅红色边框不够——需文字错误信息3.3.2Labels or Instructions所有输入必须有标签或说明每个输入框可见label或aria-label3.3.3Error Suggestion已知时提供修正建议请输入有效邮箱如 userexample.com3.3.4Error Prevention法律/财务/数据操作必须可逆或可确认破坏性操作加确认步骤或撤销选项2.4 原则四健壮Robust编号需求关键规则Level 1 任务4.1.2Name, Role, Value所有 UI 组件必须向辅助技术暴露名称、角色和状态使用语义化 HTML 或正确的 ARIA roles/states/properties3. 实现模式从语义结构到 ARIA 的工程清单参考文档给出了一组可直接套用的实现模式大多数支撑 Level 1 标准个别标注 IBM Level 2/3 的模式也一并保留以便集中查阅。3.1 语义化 HTML 结构!-- 正确语义结构 -- main h1Page Title/h1 nav aria-labelPrimary navigation.../nav section aria-labelledbysection-heading h2 idsection-headingSection Name/h2 /section /main footer.../footer !-- 正确规范的表单标签 -- label foremailEmail address/label input idemail typeemail autocompleteemail required aria-describedbyemail-error / span idemail-error rolealertPlease enter a valid email address./span3.2 颜色对比度规则正文文本: contrast ≥ 4.5:1 (1.4.3 — Level 1) 大文本: contrast ≥ 3:1 (1.4.3 — Level 1≥18pt 常规或 ≥14pt 粗体) UI 组件: contrast ≥ 3:1 (1.4.11 — Level 2边框、图标、焦点环) 禁用状态: 豁免 Logo/品牌: 豁免推荐工具IBM Equal Access CheckerChrome/Firefox 浏览器扩展、axe DevTools、Colour Contrast Analyser。3.3 焦点管理/* 不要这样做没有可见替代就移除 outline */ :focus { outline: none; } /* 应该这样做 */ :focus-visible { outline: 2px solid #0f62fe; /* IBM Blue — 满足 3:1 对比度 */ outline-offset: 2px; }// 打开模态时把焦点移入模态内第一个可聚焦元素 dialog.addEventListener(open, () { dialog.querySelector(button, [href], input, [tabindex]).focus(); }); // 模态打开期间困住焦点 // 关闭时释放焦点并归还给触发元素3.4 自定义交互组件的键盘要求组件必需按键ButtonEnter、SpaceLinkEnterCheckboxSpaceRadio 组组内方向键Tab离开Select/Listbox方向键、Home、End、EnterDialog/ModalEscape关闭、焦点陷阱Tabs方向键切换Tree/Menu方向键、Home、End、Escape3.5 ARIA 使用模式!-- 状态消息用 live region -- div rolestatus aria-livepoliteFile uploaded successfully./div div rolealert aria-liveassertiveError: Session expired./div !-- 自定义按钮要有有意义的标签 -- button aria-labelClose dialog×/button button aria-expandedfalse aria-controlsmenu-idMenu/button !-- 纯图标按钮必须有可访问名称 -- button aria-labelSearch svg aria-hiddentrue focusablefalse.../svg /button !-- 加载状态 -- button aria-disabledtrue aria-busytrueSaving.../button3.6 图片与媒体!-- 有意义的图片 -- img srcchart.png altBar chart showing Q4 revenue increased 30% YoY / !-- 装饰性图片 -- img srcdivider.png alt rolepresentation / !-- 复杂图片配长描述 -- figure img srcarchitecture.png altSystem architecture aria-describedbyarch-desc / figcaption idarch-desc Three-tier system: frontend React app calls REST API, which connects to PostgreSQL database. /figcaption /figure3.7 触控目标支撑 2.5.8 Target Size — IBM Level 2/* 保证所有交互元素满足 24×24px 最小值 */ button, a, [rolebutton], input[typecheckbox], input[typeradio] { min-width: 24px; min-height: 24px; } /* 推荐44×44px 以获得舒适的移动端交互 */ .btn-touch { min-width: 44px; min-height: 44px; }3.8 文本间距鲁棒性支撑 1.4.12 Text Spacing — IBM Level 3布局必须在用户通过浏览器/操作系统应用以下覆盖值时保持不破损/* 你的 CSS 必须能优雅处理这些值同时生效 */ line-height: 1.5 !important; letter-spacing: 0.12em !important; word-spacing: 0.16em !important; /* 段落间距2× 字号 */可用 WCAG 1.4.12 的 bookmarklet 注入测试验证内容不被裁剪或重叠。4. 推迟到 Level 2 与 Level 3 的标准以下标准不属于Level 1不在第 2 节核对清单中。节奏等级取自 IBM v7.3 release notesWCAG 2.1 标准于 v7.1 加入WCAG 2.2 于 v7.3 加入应在后续发布阶段处理编号需求IBM 节奏等级1.3.4Orientation21.4.11Non-text Contrast21.4.13Content on Hover or Focus22.4.11Focus Not Obscured (Minimum)WCAG 2.222.5.1Pointer Gestures22.5.3Label in Name22.5.4Motion Actuation22.5.7Dragging MovementsWCAG 2.222.5.8Target Size (Minimum)WCAG 2.224.1.3Status Messages21.3.5Identify Input Purpose31.4.12Text Spacing32.1.4Character Key Shortcuts32.5.2Pointer Cancellation33.2.6Consistent HelpWCAG 2.233.3.7Redundant EntryWCAG 2.233.3.8Accessible Authentication (Minimum)WCAG 2.23媒体1.2.x说明仅适用于预录/实时音视频。完整起见字幕1.2.2 Prerecorded、1.2.4 Live是 IBM Level 1而纯音频/纯视频替代方案与语音描述1.2.1、1.2.3、1.2.5是 Level 3。5. Section 508 软件专用要求说明这些 Section 508 软件要求针对非 Web 软件与上文 WCAG 节奏等级分开跟踪不分配 Level 1/2/3 节奏。对 Web UI 而言这些要求大多由4.1.2 Name, Role, Value满足。以下要求适用于非 Web 软件和桌面/移动应用编号需求关键规则502.2.1User Control of Accessibility Features平台无障碍设置对比度、字号必须保持用户可控502.2.2No Disruption of Accessibility Features应用不得覆盖操作系统无障碍特性或键盘快捷键502.3.1Object Information所有 UI 对象必须通过平台 API 暴露角色、状态、名称、边界和描述502.3.2Modification of Object Information用户可设置的状态/属性必须可通过辅助技术编程设置502.3.3Row, Column, and Headers数据表必须编程暴露行/列表头502.3.4Values当前值和允许范围必须可编程获取502.3.5Modification of Values辅助技术必须能在交互控件中设置值6. WCAG 2.2 新增标准IBM v7.3WCAG 2.2 新增六条标准自 2024 年 10 月起全部要求生效但均不属于 Level 1都列在第 4 节推迟表中标准摘要IBM 节奏等级2.4.11Focus Not Obscured (Minimum)聚焦元素不得被粘性 UI 完全遮挡22.5.7Dragging Movements拖拽操作必须有单指针替代22.5.8Target Size (Minimum)触控目标至少 24×24 CSS px23.2.6Consistent Help帮助机制跨页面位于同一位置33.3.7Redundant Entry同一会话中不重复索取已提供的信息33.3.8Accessible Authentication (Minimum)登录框允许粘贴、支持密码管理器3注意4.1.1 Parsing 已被 WCAG 2.2 移除不再是 IBM v7.3 中的要求。7. Langflow 如何把这份标准接入仓库审计技能与测试基础设施Langflow 把上述指南工程化为一套审计 → 报告 →按需修复 → 验证的闭环。核心载体是 ibm-a11y-level1-audit 技能其默认交付物是报告而非代码 diff只有当用户在同一请求中明确要求修复时才会执行修复步骤。7.1 三份事实来源Sources of Truth技能定义了三份权威材料均位于当前仓库Level 1 标准工程指南即本文主体 ibm-level1-criteria.md——完整核对清单、推迟清单、常见失败模式与实现模式。Langflow 捕获的 IBM Level 1 过滤器快照ibm-able-level-1-requirements.md从 IBM Able UI 的 Level 1 过滤器捕获的21 条需求含 1.2.2/1.2.4 字幕、1.4.11 Non-text Contrast 等。当两份材料对节奏划分不一致时优先以工程指南为准发现项映射时同时标注两套 ID。验证宿主src/frontend/tests/a11y/ 目录下的 Playwright 规范、基线与 README。其中 21 条快照中的若干条与工程指南的节奏划分不同例如 1.4.11 在快照中列入 Level 1 过滤器而工程指南将其标为 Level 2这正是技能文档提醒以工程指南为准的原因。快照文件还记录了针对 Langflow 具体页面的落地备注如禁用的分页控件不得成为键盘 Tab 停靠点API Key 名称单元格必须可通过键盘打开而非仅指针输入Global Variables 表格Space 切换行勾选框、Enter 打开编辑模态2.1.1Global Variables 编辑模态关闭时把焦点恢复到上次聚焦的表格单元格2.4.3。7.2 七步审计工作流技能的进度清单是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 report仅当第 5 步执行第 3 步映射要求每个发现项标注WCAG / IBM 编号来自本文第 2 节清单如2.1.1、4.1.2IBM ruleId当来自 Equal Access 引擎时如aria_accessiblename_exists、element_tabbable_role_valid严重度violation/potentialviolation/manual是否在当前范围内凡出现在Deferred to Level 2 Level 3中的发现项除非用户扩大范围否则丢弃或推迟。第 4 步的报告遵循 report-template.md 结构必含六个章节Summary发现数统计与验证结论、Scope范围与排除项、Findings 表ID / 标准 / 规则证据 / 位置 / 严重度 / 状态 / 备注、Fixes、Verification实际执行的命令、Remaining risk未决 Level 1 问题、已接受的基线、尚未做的手工检查。7.3 扫描命令Playwright 双引擎与批量路由工具Langflow 的扫描基础设施见 src/frontend/tests/a11y/README.md# Playwright IBM 扫描实时 DOM / 有状态页面断言模式 cd src/frontend RUN_A11Ytrue RUN_A11Y_ASSERTtrue npx playwright test tests/a11y/feature.a11y.spec.ts --projectchromium --workers5 # 可选生成 HTML 分诊报告 npm run a11y:html-report --silent # → coverage/accessibility-reports/index.html # 临时批量路由扫描默认加载页面 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要点双引擎交互式 UI 表面应同时跑 IBM Equal AccessPlaywright 的page.runA11yScan实现在 src/frontend/tests/fixtures.ts与 axe组件级 Jest 测试__tests__/*.a11y.test.tsx。HTML 报告按路由 → 规则两级分组附带 IBM 消息、目标、DOM 路径、ARIA 路径、元素边界、代码片段与 IBM 规则说明输出至coverage/accessibility-reports/index.html。静态路由由 static-routes.a11y.spec.ts 镜像 a11y_routes.json 的权威路由列表每路由带稳定的ready检查路由重定向或停止渲染时 CI 直接失败。有状态覆盖画布、配置面板、认证校验、Toast、Dialog、Playground放在各自的聚焦规范中保持静态路由廉价且可预测。7.4 基线Baseline机制框架级技术债的显式豁免RUN_A11Y_ASSERTtrue模式下扫描结果会与基线比对基线文件位于 src/frontend/tests/a11y/baselines/。技能明确要求不得悄悄禁用扫描基线仅用于有据可查的框架技术债且每条基线在报告的 Remaining risk 一节中需写明路径与理由。7.5 数据表格与模态的 Level 1 最佳实践AG Grid Radix技能把设置类表格尤其是/settings/global-variables的键盘行为定义为 Level 1 最佳实践2.1.1 / 2.4.3参考实现是GlobalVariablesPage与 global-variables.a11y.spec.ts可勾选行的键盘映射按键行为Space切换该行选择复选框不打开编辑Enter为聚焦行打开 Update Variable 模态实现注意只在页面级onCellKeyDown处理不要为其他网格改动共享TableComponent默认行为在该页列定义上添加suppressKeyboardEvent拦截 Enter/Space避免 AG Grid 内置的 Space 选择行为与自定义处理器冲突在node.setSelected之后同步 React 选择状态使工具栏删除按钮的启用状态读取TableOptions.hasSelection正确更新。模态开/关的焦点恢复focus restore从行/单元格打开编辑时必须记住聚焦单元格rowIndexcolId关闭编辑模态Escape、Cancel 或保存成功时必须通过api.setFocusedCell DOM.focus()把焦点恢复到同一单元格并用若干次requestAnimationFrame越过 Radix dialog 的焦点清理时序从Add New打开的创建模态应恢复到触发按钮存在真实DialogTrigger时是 Radix 默认行为用 Playwright 键盘测试验证从单元格打开 → Escape →document.activeElement仍是该单元格或其col-id随后无需鼠标再次聚焦即可用 Enter 重新打开。这些模式对应参考文档第 3.3 节焦点管理中的通用规则打开时移入焦点、关闭时归还焦点并给出了 AG Grid/Radix 场景下的具体验证方法。8. 测试工具链与 CI 集成8.1 工具选型工具用途IBM Equal Access Checker自动浏览器扫描Chrome/Firefox 扩展axe DevTools自动化无障碍审计NVDA Firefox屏幕阅读器测试WindowsVoiceOver Safari屏幕阅读器测试macOS/iOSTalkBack Chrome屏幕阅读器测试AndroidColour Contrast Analyser手工颜色对比度检查纯键盘导航手工 Tab/方向键走查8.2 自动化 Checker 的 CI 集成参考文档给出的 IBM checker 集成方式# 安装 IBM accessibility-checker npm install --save-dev accessibility-checker # 对 URL 运行 npx achecker http://localhost:3000// Jest/Playwright 集成示例 const aChecker require(accessibility-checker); test(Home page has no accessibility violations, async () { const results await aChecker.getCompliance(http://localhost:3000, home-page); expect(aChecker.assertCompliance(results)).toBe(0); });在 Langflow 仓库中这条能力对应到 Playwright 规范的page.runA11yScan(...)封装fixtures.ts与 a11y_scan.py 批量脚本GitHub Actions 会为每个调用page.runA11yScan的规范运行扫描见 tests/a11y/README.md。8.3 五阶段开发工作流设计阶段交付前确认颜色对比度、触控目标、焦点状态与信息层级满足 Level 1开发阶段优先使用语义化 HTML仅当没有原生元素时才加 ARIA组件完成运行 IBM Equal Access Checker或 axe目标零违规Pull RequestPR 描述中附无障碍章节说明验证了什么发布前对关键流程做手工键盘走查与简短屏幕阅读器测试。9. 常见失败模式速查表❌ 失败✅ 修复用div或span做按钮且无键盘/ARIA 支持用button或加rolebuttontabindex0 键盘处理器有意义的图片上alt编写传达图片用途的描述性 altplaceholder作为输入框唯一标签添加可见labelplaceholder 仅作补充提示仅用颜色表示必填项或错误颜色旁加星号 (*)、图标或文字标签CSS 全局移除 focus outline保留 outline按设计系统美化样式模态打开时焦点未移入打开时聚焦首个元素或模态标题模态关闭时焦点未归还触发元素记录触发元素并在关闭时focus()它aria-label不含按钮可见文本确保 aria-label 以可见文本开头如按钮 Save 对应aria-labelSave documentrolealert误用于非紧急消息非紧急更新用rolestatusaria-livepolite无上下文的 Click here / Learn more 链接描述目的地Learn more about pricing plans扫描器会漏掉的部分 Level 1 任务需手工点检2.1.1/2.1.2 的 Tab/ShiftTab 双向走查与 Escape 关闭浮层、2.4.3/2.4.7 的焦点顺序与焦点环可见性、1.4.10 的 320px/约 400% 缩放重排、1.4.1 的非纯颜色状态指示、3.3.1/3.3.2 的文本错误与输入标签。10. 参考文件索引文件内容ibm-level1-criteria.md本文主体IBM Level 1 工程合规指南SKILL.mdLevel 1 审计技能定义七步工作流、范围规则report-template.md审计报告模板Summary/Scope/Findings/Fixes/Verification/Remaining risksrc/frontend/tests/a11y/README.md扫描覆盖说明与本地命令ibm-able-level-1-requirements.mdIBM Able Level 1 过滤器捕获的 21 条需求快照static-routes.a11y.spec.ts静态路由扫描规范global-variables.a11y.spec.tsAG Grid 表格键盘行为 焦点恢复的参考实现与测试a11y_scan.py批量路由扫描与 Markdown/HTML 报告生成a11y_routes.json权威静态路由清单适用前提与限制本指南基于 IBM Equal Access Toolkit v7.32024 年 10 月起生效版本与 WCAG 2.2 A/AA 对齐Langflow 侧的扫描命令依赖src/frontend下的 Playwright 测试环境RUN_A11Ytrue启用扫描、RUN_A11Y_ASSERTtrue启用基线断言。仅完成 Level 1 不等同于完整 WCAG 合规Level 2/3 标准应在后续发布阶段按第 4 节节奏推进。【免费下载链接】langflowLangflow is a powerful tool for building and deploying AI-powered agents and workflows.项目地址: https://gitcode.com/GitHub_Trending/la/langflow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考