减少AI生成前端代码的粗糙度：语义化与可访问性检查清单

当 AI 代码生成工具在 8 秒内产出一个 React 侧边栏组件时，视觉层面的完成度往往令人印象深刻：流畅的悬停状态、协调的间距、精致的动画过渡。但打开浏览器的无障碍树（Accessibility Tree）查看，你可能会发现根元素的角色是generic，名称为none，不可聚焦 —— 对于屏幕阅读器用户、键盘导航者和语音控制用户而言，这个组件实际上不存在。

这就是 AI 生成前端代码的核心问题：大语言模型优化的是视觉输出（渲染树），却为辅助技术实际读取的语义层（无障碍树）生成了接近零的信息。

语义鸿沟：渲染树与无障碍树

浏览器在接收 HTML 和 CSS 后会构建两个主要表示。渲染树（Render Tree）决定屏幕上绘制的内容：布局、颜色、排版、悬停状态和过渡动画。这是视觉层，也是 AI 生成代码表现良好的层面。

但浏览器同时构建另一个并行结构：无障碍树（Accessibility Tree）。这是一个经过过滤、语义增强的 DOM 表示，按照 WAI-ARIA、HTML-AAM 和 Core AAM 规范构建。当屏幕阅读器遍历页面时，它读取的是这棵树，而非 DOM 或渲染树。

无障碍树的每个节点具有四个关键属性：

• 角色（Role）：这是什么？（button、link、navigation、tab）
• 名称（Name）：它叫什么？（从文本内容、aria-label 或 alt 计算）
• 状态（State）：它处于什么状态？（expanded、selected、checked）
• 值（Value）：它包含什么数据？

CSS 可以让<div>看起来像个按钮，但只有 HTML 语义能让它真正成为一个按钮。

AI 生成代码的常见缺陷模式

研究表明，通用 AI 工具生成的代码普遍存在以下结构性问题：

语义缺失

• 使用<div onClick>代替<button>或<a>
• 缺少地标元素（nav、main、aside、header、footer）
• 标题层级（h1-h6）混乱或完全缺失
• 列表不使用<ul>/<ol>配合<li>

无障碍属性遗漏

• 切换按钮缺少aria-expanded和aria-controls
• 图标按钮无aria-label，SVG 图标未设置aria-hidden
• 表单输入框缺少关联的<label>
• 动态内容未使用aria-live区域

键盘交互缺失

• 自定义控件无法通过 Tab 键聚焦
• 缺少onKeyDown处理（Enter 和 Space 无效）
• 模态框无焦点陷阱和 Escape 关闭处理
• 无focus-visible样式替代方案

视觉与运动

• 颜色对比度不足（WCAG AA 标准 4.5:1 未达标）
• 未处理prefers-reduced-motion偏好
• 占位符文本对比度过低

一个典型的 AI 生成导航侧边栏可能在 29 行代码中包含 10 个不同的无障碍缺陷，且缺陷密度极高 —— 几乎每个元素的语义都是错误的。

五层质量防护体系

与其事后修复，不如在生成阶段建立约束。以下五层体系可将每个组件的质量检查时间控制在 3-8 分钟，而事后修复通常需要 45-90 分钟。

第一层：提示词约束

将语义化规则固化到工作区配置中。Cursor 读取.cursorrules文件，GitHub Copilot 支持.github/copilot-instructions.md。核心约束包括：

# 组件生成规则
- 操作使用<button>，禁止<div onClick>或<span onClick>
- 导航使用<a href="...">，禁止<span onClick={navigate}>
- 使用<nav>、<main>、<aside>、<header>、<footer>作为地标
- 正确使用<h1>-<h6>，禁止跳级
- 列表使用<ul>/<ol>配合<li>
- 表单使用<form>、<fieldset>、<legend>、<label>
- 模态框使用<dialog>及其showModal() API
- 复杂模式（标签页、组合框、对话框）使用Headless UI、Radix UI或React Aria

当模型忽略约束时，采用针对性追问而非重新生成："将 Account 切换按钮改为 button 元素，并添加 aria-expanded 和 aria-controls 属性。"

第二层：静态分析

使用 ESLint 配合eslint-plugin-jsx-a11y插件在编码时捕获结构性问题：

export default [
  {
    plugins: { 'jsx-a11y': jsxA11y },
    rules: {
      'jsx-a11y/click-events-have-key-events': 'error',
      'jsx-a11y/no-static-element-interactions': 'error',
      'jsx-a11y/alt-text': 'error',
      'jsx-a11y/anchor-is-valid': 'error',
      'jsx-a11y/interactive-supports-focus': 'error',
      'jsx-a11y/label-has-associated-control': 'error',
    },
  },
];

在 CI 中将规则设为error级别，确保不合规代码无法合并。

第三层：运行时测试

使用 axe-core 配合 Playwright 或 Jest 进行浏览器内测试：

import { axe, toHaveNoViolations } from 'jest-axe';
expect.extend(toHaveNoViolations);

it('has no axe violations', async () => {
  const { container } = render(<SettingsSidebar />);
  expect(await axe(container)).toHaveNoViolations();
});

it('supports full keyboard navigation', async () => {
  render(<SettingsSidebar />);
  const user = userEvent.setup();
  await user.tab();
  expect(screen.getByRole('button', { name: /account/i })).toHaveFocus();
});

注意：axe-core 能检测缺失的 ARIA 属性、无效用法、表单标签缺失、文本替代缺失、颜色对比失败等问题，但无法评估标签是否有意义、焦点是否移动到正确位置、阅读顺序是否与视觉顺序一致。

第四层：CI 集成

在 GitHub Actions 中配置三层检查：

name: Accessibility Checks
on: [push, pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - name: ESLint a11y rules
        run: npx eslint 'src/**/*.{ts,tsx}' --max-warnings 0

  test:
    runs-on: ubuntu-latest
    steps:
      - run: npm ci
      - name: Component accessibility tests
        run: npx jest --testPathPattern='\\.test\\.'

  e2e:
    runs-on: ubuntu-latest
    steps:
      - run: npm ci
      - name: Playwright axe audit
        run: npx playwright test --grep @a11y

第五层：无障碍组件抽象

最深层的解决方案是架构层面的：使用将无障碍性编码到 API 契约中的库，而非依赖每次提示都生成正确的原语。

• Headless UI：约 10 个组件，最轻量，适合快速集成
• Radix UI：约 30 个无样式原语，可组合 API，适合大多数项目
• React Aria：40 + 个 hooks，涵盖几乎所有 ARIA 模式，适合构建设计系统

通过使用这些组件，AI 的工作缩减为视觉组合，而无障碍性由库的结构保证。

可落地的检查清单

在每次 AI 生成代码后，运行以下 2 分钟检查：

语义结构

• 所有交互元素是<button>或<a>，而非<div>
• 页面包含 nav、main、aside、header、footer 地标
• 标题层级 h1-h6 连续无跳级
• 列表使用 ul/ol+li，表格使用 table+thead+tbody

无障碍属性

• 切换按钮有 aria-expanded 和 aria-controls
• 图标按钮有 aria-label，SVG 有 aria-hidden
• 表单输入有关联的 label 或 aria-label
• 装饰性图片 alt=""，信息性图片有描述性 alt

键盘与焦点

• 所有交互元素可通过 Tab 键聚焦
• 有 focus-visible 样式（不单纯移除 outline）
• 模态框有焦点陷阱和 Escape 关闭
• 复合控件支持方向键导航

视觉与运动

• 颜色对比度≥4.5:1（正文）和≥3:1（大文本 / UI 组件）
• 空间移动动画（transform、position 变化）使用 prefers-reduced-motion
• 焦点状态清晰可见

结语

AI 生成代码的 "粗糙度" 并非无法克服。通过将语义化约束固化到提示词、静态分析规则、运行时测试和 CI 流程中，开发者可以在不牺牲效率的前提下，系统性地提升代码质量。最高杠杆的干预措施是将eslint-plugin-jsx-a11y设为 CI 中的error级别，以及采用 Headless UI、Radix 或 React Aria 等无障碍组件库 —— 它们无论 AI 工具生成什么代码、是否涉及提示词、开发者是否考虑无障碍性，都能防止大多数失败。

无障碍树反映的是你提供的 DOM。让它变得有用。

参考来源

• Frontend Masters: "AI-Generated UI Is Inaccessible by Default"
• arXiv: "CodeA11y: Making AI Coding Assistants Useful for Accessible Web Development" (2025)
• WebAIM Million Report (2024)

web