企业官网建设流程全解析

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 并不等于达到完整 WCAG 合规，它代表发布规划周期中的第一优先级阶段。但仅完成 Level 1 的产品仍然能获得可观的无障碍收益，且许多需求在合规声明中可标记为 "Support"。

该指南的适用范围是仅覆盖 IBM Level 1 节奏内的需求：即 WCAG 2.0 Level A/AA 的基础标准，加上唯一的 WCAG 2.1/2.2 新增项1.4.10 Reflow（IBM 将其节奏定为 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）

2.2 原则二：可操作（Operable）

2.3 原则三：可理解（Understandable）

2.4 原则四：健壮（Robust）

3. 实现模式：从语义结构到 ARIA 的工程清单

参考文档给出了一组可直接套用的实现模式，大多数支撑 Level 1 标准，个别标注 IBM Level 2/3 的模式也一并保留以便集中查阅。

3.1 语义化 HTML 结构

<!-- 正确：语义结构 --> <main> <h1>Page Title</h1> <nav aria-label="Primary navigation">...</nav> <section aria-labelledby="section-heading"> <h2 id="section-heading">Section Name</h2> </section> </main> <footer>...</footer> <!-- 正确：规范的表单标签 --> <label for="email">Email address</label> <input id="email" type="email" autocomplete="email" required aria-describedby="email-error" /> <span id="email-error" role="alert">Please enter a valid email address.</span>

3.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 Checker（Chrome/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 自定义交互组件的键盘要求

3.5 ARIA 使用模式

<!-- 状态消息用 live region --> <div role="status" aria-live="polite">File uploaded successfully.</div> <div role="alert" aria-live="assertive">Error: Session expired.</div> <!-- 自定义按钮要有有意义的标签 --> <button aria-label="Close dialog">×</button> <button aria-expanded="false" aria-controls="menu-id">Menu</button> <!-- 纯图标按钮必须有可访问名称 --> <button aria-label="Search"> <svg aria-hidden="true" focusable="false">...</svg> </button> <!-- 加载状态 --> <button aria-disabled="true" aria-busy="true">Saving...</button>

3.6 图片与媒体

<!-- 有意义的图片 --> <img src="chart.png" alt="Bar chart showing Q4 revenue increased 30% YoY" /> <!-- 装饰性图片 --> <img src="divider.png" alt="" role="presentation" /> <!-- 复杂图片配长描述 --> <figure> <img src="architecture.png" alt="System architecture" aria-describedby="arch-desc" /> <figcaption id="arch-desc"> Three-tier system: frontend React app calls REST API, which connects to PostgreSQL database. </figcaption> </figure>

3.7 触控目标（支撑 2.5.8 Target Size — IBM Level 2）

/* 保证所有交互元素满足 24×24px 最小值 */ button, a, [role="button"], input[type="checkbox"], input[type="radio"] { 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 notes（WCAG 2.1 标准于 v7.1 加入，WCAG 2.2 于 v7.3 加入），应在后续发布阶段处理：

媒体（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 软件和桌面/移动应用：

6. WCAG 2.2 新增标准（IBM v7.3）

WCAG 2.2 新增六条标准，自 2024 年 10 月起全部要求生效，但均不属于 Level 1，都列在第 4 节推迟表中：

注意：4.1.1 Parsing 已被 WCAG 2.2 移除，不再是 IBM v7.3 中的要求。

7. Langflow 如何把这份标准接入仓库：审计技能与测试基础设施

Langflow 把上述指南工程化为一套"审计 → 报告 →（按需）修复 → 验证"的闭环。核心载体是 ibm-a11y-level1-audit 技能，其默认交付物是报告而非代码 diff：只有当用户在同一请求中明确要求修复时，才会执行修复步骤。

7.1 三份事实来源（Sources of Truth）

技能定义了三份权威材料，均位于当前仓库：

1. Level 1 标准（工程指南）：即本文主体 ibm-level1-criteria.md——完整核对清单、推迟清单、常见失败模式与实现模式。
2. 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。
3. 验证宿主：src/frontend/tests/a11y/ 目录下的 Playwright 规范、基线与 README。

其中 21 条快照中的若干条与工程指南的节奏划分不同（例如 1.4.11 在快照中列入 Level 1 过滤器，而工程指南将其标为 Level 2），这正是技能文档提醒"以工程指南为准"的原因。快照文件还记录了针对 Langflow 具体页面的落地备注，如：

• 禁用的分页控件不得成为键盘 Tab 停靠点；
• API Key 名称单元格必须可通过键盘打开，而非仅指针输入；
• Global Variables 表格：Space 切换行勾选框、Enter 打开编辑模态（2.1.1）；
• Global 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.2）；
• IBM 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_A11Y=true RUN_A11Y_ASSERT=true npx playwright test tests/a11y/<feature>.a11y.spec.ts --project=chromium --workers=5 # 可选：生成 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 Access（Playwright 的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_ASSERT=true模式下扫描结果会与基线比对，基线文件位于 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：

可勾选行的键盘映射：

实现注意：

• 只在页面级onCellKeyDown处理（不要为其他网格改动共享TableComponent默认行为）；
• 在该页列定义上添加suppressKeyboardEvent拦截 Enter/Space，避免 AG Grid 内置的 Space 选择行为与自定义处理器冲突；
• 在node.setSelected之后同步 React 选择状态，使工具栏删除按钮的启用状态（读取TableOptions.hasSelection）正确更新。

模态开/关的焦点恢复（focus restore）：

• 从行/单元格打开编辑时必须记住聚焦单元格（rowIndex+colId）；
• 关闭编辑模态（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 工具选型

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 五阶段开发工作流

1. 设计阶段：交付前确认颜色对比度、触控目标、焦点状态与信息层级满足 Level 1；
2. 开发阶段：优先使用语义化 HTML，仅当没有原生元素时才加 ARIA；
3. 组件完成：运行 IBM Equal Access Checker（或 axe），目标零违规；
4. Pull Request：PR 描述中附无障碍章节，说明验证了什么；
5. 发布前：对关键流程做手工键盘走查与简短屏幕阅读器测试。

9. 常见失败模式速查表

扫描器会漏掉的部分 Level 1 任务需手工点检：2.1.1/2.1.2 的 Tab/Shift+Tab 双向走查与 Escape 关闭浮层、2.4.3/2.4.7 的焦点顺序与焦点环可见性、1.4.10 的 320px/约 400% 缩放重排、1.4.1 的非纯颜色状态指示、3.3.1/3.3.2 的文本错误与输入标签。

10. 参考文件索引

适用前提与限制：本指南基于 IBM Equal Access Toolkit v7.3（2024 年 10 月起生效版本）与 WCAG 2.2 A/AA 对齐；Langflow 侧的扫描命令依赖src/frontend下的 Playwright 测试环境（RUN_A11Y=true启用扫描、RUN_A11Y_ASSERT=true启用基线断言）。仅完成 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