用 Codex 生成可访问表单 UI：7 步覆盖键盘、错误与自动测试

admin 设计创意 8小时前

15 0

Codex 可以很快生成一个外观完整的注册、结账或联系表单，但“能点击提交”不等于每个人都能完成任务。可访问表单需要同时处理标签、分组、说明、键盘顺序、错误文本、焦点去向和提交反馈。本教程把这些要求整理成七步工作流，让 Codex 在现有设计系统内生成 UI，并用 Playwright 与 axe-core 留下可重复的验证证据。

Codex 生成可访问表单 UI 的五段状态链 — 把未填写、编辑、校验失败、提交中和完成或失败都写成可验证状态。

适用场景

用 Codex 生成注册、登录、结账、预约、搜索或后台编辑表单；
现有表单看起来正常，但只靠 placeholder、红色边框或鼠标操作；
设计系统已有 Input、Select、Checkbox 等组件，需要补齐语义和错误状态；
希望把 WCAG 要求变成自动测试和人工验收清单，而不是发布前临时抽查。

如果业务规则、错误文案或提交后的去向尚未确定，先找产品、法务或后端确认。Codex 能实现规则、发现冲突和补测试，但不应替团队猜测必填条件、数据用途或授权边界。

第一步：先让 Codex 只读审计表单

把目标路由、现有组件、字段规则和测试命令交给 Codex，要求先不修改文件。审计应回答：每个控件有没有真实 label，相关选项是否使用 fieldset 与 legend 分组，帮助文本和错误文本是否与输入框程序化关联，Tab 顺序是否符合视觉与任务顺序，以及提交后焦点会去哪里。

先不要修改代码。阅读 AGENTS.md、目标表单、设计系统组件和现有测试。输出：
1. 每个字段的可访问名称、说明和必填规则；
2. 键盘顺序与提交后焦点去向；
3. 仅靠颜色、placeholder 或图标表达的信息；
4. 业务规则中仍需人工确认的项目。
不要新建组件库，不要改变接口，不要输出任何凭证。

第二步：用原生语义建立骨架

W3C WAI 建议用 label 标识控件，用 fieldset 与 legend 组织相关选项，并为完成表单提供清晰说明。优先选择原生 input、select、textarea 和 button；只有原生控件无法表达交互时才使用 ARIA。placeholder 可以给示例，但不能代替始终可见的标签。

<label for="email">电子邮箱（必填）</label>
<p id="email-hint">用于接收确认邮件，不会公开。</p>
<input id="email" name="email" type="email"
  required autocomplete="email"
  aria-describedby="email-hint email-error" />
<p id="email-error" hidden></p>

可访问表单错误提示的标签语义和焦点关系 — 错误要指出字段、说明问题并提供修复方法，同时与输入框建立程序化关联。

第三步：把错误写成“字段 + 问题 + 修复”

WCAG 2.2 的错误识别要求：自动检测到输入错误时，要指出出错项目并用文本描述错误。不要只把边框变红，也不要只写“格式错误”。更好的文案是“电子邮箱：请输入完整地址，例如 name@example.com”。校验后设置 aria-invalid，并用 aria-describedby 连接错误文本；页面有多个错误时，可在表单顶部增加错误摘要与锚点。

function applyError(input, error, message) {
  input.setAttribute("aria-invalid", "true");
  error.textContent = message;
  error.hidden = false;
}

// 不好：格式错误
// 更好：电子邮箱：请输入完整地址，例如 name@example.com

第四步：设计验证时机与五段状态

页面加载就显示一屏红字会制造噪音；只在最终提交时才发现十个错误又会增加返工。通常可以在字段离开焦点后提示格式问题，在提交时汇总所有阻断错误，用户修改后再及时撤销已解决的提示。把未填写、正在编辑、校验失败、提交中、完成或服务端失败都写进状态表，并明确每一状态的焦点、文案与可用操作。

状态	界面反馈	焦点与操作
未填写	标签、必填与格式说明可见	按任务顺序进入首字段
正在编辑	保留输入，避免无意义打断	不自动跳焦点
校验失败	文本错误 + 视觉标记	提交后到摘要或首个错误
提交中	公布忙碌状态，防重复提交	不清空输入
完成 / 失败	结果清楚、可恢复	焦点到确认信息或错误区域

Codex 可访问表单任务卡的输入边界和证据 — 提示词同时写清输入、不可越过的边界与最终证据。

第五步：把需求整理成可直接使用的 Codex 提示词

OpenAI 的前端用例强调先理解仓库与设计系统，再在真实浏览器中检查多个尺寸。下面的提示词把表单任务写成“输入—边界—证据”，可直接替换方括号内容使用。

任务：在【路由】实现【表单名称】，复用现有设计系统。
输入：字段与业务规则【粘贴或链接】；错误文案【列表】；提交接口【schema】；目标尺寸 390 / 768 / 1440。
语义：所有控件有可访问名称；相关选项用 fieldset/legend；说明和错误与字段关联；必填信息不只靠颜色或星号。
交互：覆盖未填写、编辑、无效、提交中、成功和服务端失败；Tab 顺序自然；提交失败不丢输入；提交后焦点去向明确。
边界：不改接口和业务规则；不新增 UI 框架；不删除焦点样式；不做无关重构。
证据：运行 lint、typecheck、unit、Playwright + axe；给出键盘路径、三档截图、失败项和仍需人工确认的问题。先只读审计并给最小修改计划，再开始改文件。

第六步：用 Playwright + axe-core 做自动检查

Playwright 官方示例使用 @axe-core/playwright 扫描页面，并提醒自动检查只能发现部分 WCAG 问题。测试至少覆盖表单初始状态、一个错误提交、键盘修正和成功提交；选择器优先使用 role、label 与可访问名称，这也会反向检验语义是否正确。

import { test, expect } from "@playwright/test";
import AxeBuilder from "@axe-core/playwright";

test("signup form is keyboard usable", async ({ page }) => {
  await page.goto("/signup");
  await page.getByRole("button", { name: "创建账号" }).click();
  const email = page.getByLabel("电子邮箱（必填）");
  await expect(email).toBeFocused();
  await expect(page.getByText(/请输入完整邮箱地址/)).toBeVisible();
  const results = await new AxeBuilder({ page }).analyze();
  expect(results.violations).toEqual([]);
});

Codex 表单可访问性从自动测试到真实浏览器的验证闭环 — 语义、键盘、错误焦点和真实浏览器体验需要反复验证。

第七步：人工完成一次“不碰鼠标”的真实任务

关闭测试辅助，使用真实浏览器从页面顶部开始，只用 Tab、Shift+Tab、Enter、Space、方向键和 Escape 完成任务。确认焦点始终可见，缩放到 200% 后没有内容遮挡，错误能被理解并修复，成功或失败消息能被感知；有条件时再用 VoiceOver、NVDA 或 TalkBack 复核可访问名称和动态通知。

请在真实浏览器执行并报告证据：
1. 只用键盘完成一次成功提交；
2. 制造三个错误，记录焦点顺序和读到的错误文本；
3. 在 200% 缩放与 390px 宽度复测；
4. 检查控制台、失败请求和资源 404；
5. 把每个失败写成：页面 / 操作 / 期望 / 实际。
修复后重跑相同路径，不要用视觉截图代替键盘与读屏判断。