Remotion Studio 可访问性审计解读：WCAG 2.1 VPAT 报告与无障碍修复实践

本文以 Remotion 仓库中发布的 Remotion Studio 无障碍审计文档 studio/VPAT-2026-04-14.md 为骨架，全面解读这份 VPAT 2.4 Rev（WCAG 2.1 Edition） 自愿产品无障碍模板报告：它针对 Remotion Studio 的公开 HelloWorld 演示实例逐条评估了 WCAG 2.1 Level A/AA 符合性，并给出 8 项失败准则及修复建议。读完本文，你将理解 VPAT 报告的结构与一致性等级术语、掌握逐条缺陷的成因与对应源码位置，并得到可直接落地的 ARIA、标签、焦点管理与颜色对比度修复方案。

---

一、VPAT 是什么，这份报告审了什么

VPAT（Voluntary Product Accessibility Template，自愿产品无障碍模板）是业界通用的产品无障碍合规自述文档格式。本次发布的是 VPAT 2.4 Rev — WCAG 2.1 Edition，即以 WCAG 2.1 为参照标准的版本，适用于评估面向公众的 Web 应用。

报告的产品信息如下：

字段	值
产品名称	Remotion Studio（HelloWorld 演示）
产品版本	公开 HelloWorld 演示部署
报告日期	2026-04-14
评估方法	外部审计（Chrome + NVDA）；DOM / 无障碍树检查；Axe DevTools；Colour Contrast Analyser
适用标准	WCAG 2.1 Level AA
审计范围	HelloWorld 演示单页样本，属于 remotion.dev RGAA 4.1.2 审计（2026-04-14）的一部分

需要特别注意的是报告中的 Scope（范围） 声明：这是单页样本审计——只评估了 HelloWorld 演示页面中"记录了发现项"的那些准则，其余准则未被针对 Studio 逐一评估。因此这份 VPAT 属于发现问题导向的清单，而非完整的全量符合性声明。完整的 VPAT 需要更广泛地抽样 Studio 的各种视图与交互（同一目录下的 VPAT-template.md 即保留了"分页面、分准则逐项填写"的完整结构）。

仓库中与本次审计配套的资料还有：

• studio/RGAA-2026-04-14.md——基于法国 RGAA 4.1.2 标准的同一次审计记录，准则编号与 WCAG 一一映射；
• player/VPAT-2026-04-14.md 与 remotion.dev/VPAT-2026-04-14.md——针对 Remotion Player 与官网页面的同类报告；
• VPAT-template.md 与 RGAA-audit-template.md——后续复检可复用的空白模板。

二、一致性等级术语：读懂五档结论

VPAT 的核心价值在于用统一术语汇报"产品在每个无障碍准则上的表现"。本报告采用以下五档等级：

术语	定义
Supports（支持）	完全满足该准则
Partially Supports（部分支持）	部分内容满足，仍存在缺口
Does Not Support（不支持）	存在明显失败
Not Applicable（不适用）	产品中不存在对应功能或内容类型
Not Evaluated（未评估）	该准则未在本次样本范围内评估

结合正文可以看到一个典型用法：报告只列出"记录了发现项"的准则，且这些准则全部被标记为 Does Not Support。这并不代表产品整体不达标，而是受限于单页样本范围——阅读任何 VPAT 时都应先看 Scope 与 Not Evaluated 的使用方式，避免把"样本审计"误读为"全量审计"。

三、逐条审计结论：8 项失败准则与修复方案

以下按 WCAG 准则逐条展开报告中的发现项，并结合仓库源码说明成因与修复路径。

3.1 1.1.1 Non-text Content（非文本内容，Level A）— Does Not Support

发现：在 "Search" 对话框 → "Documentation" 选项卡中，若干承载信息的键盘按键图像（例如方向键）没有被读屏软件播报。

修复：为信息性图片提供文本替代方案。若箭头是内容语义的一部分，应使用带 alt 的 <img>，或对可访问性树隐藏的装饰图标设置 aria-hidden="true" 同时提供等价的文本/ARIA 说明。

对应组件位于仓库的 QuickSwitcher/QuickSwitcher.tsx，其内容区渲染在 QuickSwitcherContent.tsx。报告中提到的 "Documentation" 选项卡即该组件的 onDocSearchSelected 模式（查询前缀为 ? ）。修复时需重点检查模式切换栏与文档结果中所有非装饰性 SVG/位图元素是否都具备可编程名称。

3.2 1.3.1 Info and Relationships（信息与关系，Level A）— Does Not Support

发现："Search compositions..." 输入框没有任何 <label>，仅有一个 placeholder。

修复：通过 <label for> + id 建立编程式关联，或直接使用 aria-label。注意 1.3.1 关注的是"标签与输入框之间的关系能否被辅助技术感知"。

该输入框在源码中由 QuickSwitcherContent.tsx 中的 RemotionInput 渲染，placeholder 文本在 同一文件 按当前模式动态切换（Search assets... / Search actions... / Search documentation... / Search compositions...）。推荐的最小修复示例：

<input
  type="text"
  id="qs-input"
  placeholder={placeholder}
  aria-label={placeholder}
/>

3.3 1.4.3 Contrast (Minimum)（对比度，Level AA）— Does Not Support

发现："Search compositions" 的 placeholder 为灰色 #757575，背景为 #2F363D，实测对比度仅 2.7:1，未达到 4.5:1 的 AA 要求。

修复：加深 placeholder 前景色，使其在 #2F363D 背景上满足 4.5:1。

从颜色定义看，#2F363D 正是 Remotion Studio 的输入框背景常量，见 studio/src/helpers/colors.ts：

export const INPUT_BACKGROUND = '#2f363d';

这意味着该问题会影响所有使用 INPUT_BACKGROUND 且以浅灰 placeholder 文本呈现的输入控件，修复时应统一调整占位文本颜色常量，而非只改一处硬编码。WCAG 1.4.3 的 4.5:1 阈值针对普通文本（小于 18pt 常规字重或 14pt 加粗）；#757575 相对 #2F363D 无法达标，可选用亮度更低的浅灰（如 #9a9fa5 及以上亮度等级）并在 CI 中使用自动对比度检查防回归。

3.4 2.1.1 Keyboard（键盘可达性，Level A）— Does Not Support

发现：由 "Search" 按钮打开的对话框中，"HelloWorld" 与 "OnlyLogo" 两个交互元素无法仅用键盘操作。

修复：确保对话框中所有交互元素都可聚焦且可用 Enter / Space / 方向键触发；列表型选择（如组合切换器中的候选项）应实现标准的列表/网格键盘交互模式。

从源码结构看，搜索候选项由 QuickSwitcherContent.tsx 中的 QuickSwitcherResult 映射渲染，每个结果的"可选中性"经由 isQuickSwitcherResultSelectable 过滤（见 QuickSwitcherContent.tsx），选中索引通过 loopIndex 循环滚动。修复方向是确保每个可选项渲染为原生 <button> 或具备 role="option" + tabindex 的可聚焦节点。

3.5 2.4.3 Focus Order（焦点顺序，Level A）— Does Not Support

发现："Search" 与 "Render via CLI" 对话框未做焦点锁定，Tab 键会让键盘焦点逃逸到背后的页面内容。

修复：在模态框打开期间将焦点限制在其中，直到对话框被关闭（关闭按钮或 Escape 键），并把初始焦点移入对话框。

仓库中的模态容器 ModalContainer.tsx 声明了 role="dialog" 与 aria-modal="true"，并通过 DismissableModal.tsx 支持 Escape 与点击遮罩关闭；但从代码看当前并未实现完整的 focus trap（循环焦点）逻辑——这正是报告所指出的 2.4.3 缺陷。常见的实现方式是在对话框中维护 Tab / Shift+Tab 的首尾元素引用并循环跳转，同时监听 Escape 恢复触发按钮焦点。

3.6 3.3.2 Labels or Instructions（标签或说明，Level A）— Does Not Support

发现："Search compositions..." 输入框仅依赖 placeholder，没有持久可见标签。

修复：提供可见、持久的 <label> 元素。注意与 1.3.1 的差异：3.3.2 关心的是"标签对用户的可见性"，而 placeholder 会在输入时消失，不能充当持久标签。

这与 3.1 节所述的输入框是同一个（QuickSwitcherContent.tsx），修复要点是"可见且持久"，示例：

<label htmlFor="qs-input">Search compositions</label>
<input id="qs-input" type="text" placeholder="Search compositions..." />

视觉上可将标签放置于输入框上方，或使用"浮起式标签"（floating label）形态，保证任何输入状态下标签都不会消失。

3.7 4.1.2 Name, Role, Value（名称、角色、值，Level A）— Does Not Support

发现（两条）：

1. "Search" 按钮打开的对话框没有可访问名称——需要添加描述对话框用途与内容的 aria-label；
2. 顶部菜单按钮带有子菜单，但其展开/收起状态未通过编程方式暴露——需要为每个菜单触发器添加 aria-expanded。

修复：

<div
  role="dialog"
  aria-modal="true"
  aria-label="Search compositions and documentation"
>

模态容器虽已设置 role 与 aria-modal（见 ModalContainer.tsx），但从代码看没有 aria-label/aria-labelledby 提供可访问名称，这正是第一项发现的成因。对于第二项，仓库中部分展开控件已正确使用了 aria-expanded（例如 SegmentedButton.tsx、CompositionSelectorItem.tsx 与 CollapsibleInspectorSectionHeader.tsx），修复时应让顶部菜单触发器采用同样的模式：

<button aria-expanded={open} aria-controls="menu-submenu">

3.8 4.1.3 Status Messages（状态消息，Level AA）— Does Not Support

发现：在 "Render via CLI" 对话框中，点击 "Copy command" 后页面显示 "Copied command!"，但该状态消息不会被辅助技术播报。

修复：使用 role="status" 或 aria-live="polite" 包裹状态文本，使读屏软件在文本插入时自动播报。

源码证据非常清晰：按钮文案由 commandCopiedAt 状态驱动（ServerRenderModal.tsx），点击后文案切换为 'Copied command!'（ServerRenderModal.tsx），但该文本只是普通 <Button> 内容，未挂载 live region。修复示例：

{readOnlyStudio ? (
  <span role="status">
    {commandCopiedAt ? 'Copied command!' : 'Copy command'}
  </span>
) : (
  ...
)}

role="status"（等价于 aria-live="polite"）会在文本变化时温和地播报，且不会打断正在进行的朗读。

四、WCAG 与 RGAA 双轨记录：优先级修复计划

同一目录下的 RGAA-2026-04-14.md 用法国 RGAA 4.1.2（映射至 WCAG 2.1 AA / EN 301 549）的标准记录了同一次审计，两份文档是同一发现的两套编号体系。RGAA 报告还给出了分优先级的修复计划，可直接转化为团队 backlog：

优先级	RGAA 准则	建议行动
Critical（关键）	3.2（对比度）	加深 "Search compositions" placeholder，使其在 #2F363D 上达到 4.5:1
Critical（关键）	7.1、7.2（脚本）	为 "Search" 对话框补充可访问名称；用 aria-expanded 暴露子菜单开关状态；让 "HelloWorld" / "OnlyLogo" 可仅用键盘操作
High（高）	12.8（导航顺序）	在 "Search" 与 "Render via CLI" 对话框关闭前锁定键盘焦点
High（高）	11.1（表单标签）	为 "Search compositions" 输入框提供持久 <label>
Medium（中）	7.5（状态消息）	通过 aria-live="polite" 或 role="status" 播报 "Copied command!"
Low（低）	1.1（图片）	为 Search/Documentation 对话框内的箭头等信息性图片补充文本替代

RGAA 主题与 WCAG 准则的对照关系归纳如下：

RGAA 主题	对应 WCAG 准则（本次）	核心问题
主题 1：图片	1.1.1 Non-text Content	信息性图片缺少替代文本
主题 3：颜色	1.4.3 Contrast	placeholder 对比度 2.7:1
主题 7：脚本	4.1.2、2.1.1、4.1.3	对话框名称、键盘可操作性、状态播报
主题 11：表单	3.3.2 / 1.3.1	输入框缺少持久标签
主题 12：导航	2.4.3 Focus Order	模态框缺少焦点锁定

五、从审计结果反推的无障碍改进清单

综合两份报告，面向 Studio 类交互密集型 Web 应用，以下自查清单可以直接复用：

1. 对话框三件套：role="dialog" + aria-modal="true" + 描述用途的 aria-label/aria-labelledby；
2. 模态焦点管理：打开时把焦点移入、Tab/Shift+Tab 循环锁定、Escape 关闭后把焦点还给触发按钮；
3. 输入框标签：所有输入都必须有 <label>，placeholder 不能作为唯一标识；
4. 状态反馈 live region：复制成功、保存成功、渲染进度等动态文本用 role="status"/aria-live="polite"，错误用 role="alert"/aria-live="assertive"；
5. 展开状态：所有可展开菜单按钮维护 aria-expanded 与 aria-controls；
6. 对比度：占位文本在深色输入背景上满足 4.5:1，纳入自动化测试（如 Axe）防回归；
7. 信息性图标：承载按键提示等信息的图标必须可被读屏感知，装饰性图标 aria-hidden。

六、无障碍声明与后续合规动作

报告在 "Accessibility Statement" 一节明确指出：Remotion Studio 目前没有公开的无障碍声明（accessibility statement），应发布一份声明，说明符合性目标、已知局限与无障碍反馈的联系渠道。

这一点也与模板的预期结构对齐：VPAT-template.md 中预留了指向 /accessibility 页面声明的段落，说明无障碍声明是完整合规流程的标准组成部分。

七、总结

这份 studio/VPAT-2026-04-14.md 展示了无障碍审计在复杂工具型产品上的典型形态：样本范围 + 发现问题导向。8 项失败准则横跨感知（图片替代文本、对比度）、可操作（键盘、焦点顺序）、可理解（标签）、健壮性（名称/角色/值、状态消息）四大原则，其中 4 项集中于"搜索快速切换器与渲染对话框"这两个高频交互组件——这也提示无障碍投入应优先覆盖模态交互路径。

仓库源码提供了清晰的问题定位依据：placeholder 输入框在 QuickSwitcherContent.tsx 中动态生成，模态框基础容器 ModalContainer.tsx 已具备 dialog 语义但缺少可访问名称与焦点锁定，"Copied command!" 状态文案由 ServerRenderModal.tsx 中的 commandCopiedAt 驱动却未挂载 live region，输入框背景色常量定义于 colors.ts。对照 RGAA 审计报告 的优先级修复计划、以及 VPAT 模板 与 RGAA 模板 的完整结构，读者既可以照单修复 Studio，也可以将整套方法论迁移到自己的工具型 Web 应用无障碍建设中。