MonkeyCode 无障碍设计：让AI编程工具对每个人都友好

无障碍（Accessibility，简称a11y）是软件工程中最容易被忽视的维度。但对于一个开源项目来说，无障碍不仅关乎道德，更关乎社区规模——每多支持一种辅助技术，就多一批潜在用户。

MonkeyCode 从v1.5开始系统性地推进无障碍设计。本文分享实践经验和踩过的坑。

为什么AI编程工具需要无障碍？

几个你可能没想过的场景：

• 视力障碍开发者 — 使用屏幕阅读器，需要AI编程工具提供语音反馈
• 运动障碍开发者 — 使用键盘或语音控制，无法使用鼠标
• 色觉障碍开发者 — 无法区分代码中的红色错误和绿色成功标记
• 认知障碍开发者 — 需要清晰的导航和简单的操作流程

全球有超过10亿残障人士，其中不少是开发者或正在学习编程的人。

WCAG合规清单

MonkeyCode 参照WCAG 2.1 AA标准，逐项检查：

可感知性

• ✅ 所有非文本内容有替代文本
• ✅ 颜色不是传递信息的唯一方式
• ✅ 文字和背景对比度至少4.5:1
• ✅ 文字可以放大到200%不丢失功能

可操作性

• ✅ 所有功能可通过键盘操作
• ✅ 焦点顺序逻辑清晰
• ✅ 有足够的操作时间（不自动消失的提示）
• ✅ 提供跳过重复内容的方式

可理解性

• ✅ UI元素的行为可预测
• ✅ 错误提示清晰且提供修复建议
• ✅ 帮助文档易于查找

MonkeyCode 的无障碍实践

1. 键盘导航

代码编辑器的键盘导航是最复杂的部分。MonkeyCode 定义了完整的键盘快捷键方案：

快捷键	功能
Ctrl+Shift+P	打开命令面板
Ctrl+B	切换侧边栏
Ctrl+`	切换终端
Ctrl+Shift+A	打开AI对话面板
Ctrl+1/2/3	切换编辑器标签
F2	重命名文件
Alt+上下箭头	移动当前行

所有快捷键都可以在设置中自定义，满足不同用户的使用习惯。

2. ARIA标签

每个交互元素都有完整的ARIA标签：

// ❌ 不好\n<button onClick={handleRun}>\n  <img src="run.svg" />\n</button>\n\n// ✅ 好\n<button\n  onClick={handleRun}\n  aria-label="运行代码"\n  aria-keyshortcuts="F5"\n  role="button"\n>\n  <img src="run.svg" alt="运行" aria-hidden="true" />\n</button>

3. 屏幕阅读器支持

AI对话内容对屏幕阅读器的适配：

// AI消息使用live region\n<div role="log" aria-live="polite" aria-label="AI对话">\n  {messages.map(msg => (\n    <div role="article" aria-label={`${msg.role === 'ai' ? 'AI' : '你'}的消息`}>\n      {msg.content}\n    </div>\n  ))}\n</div>\n\n// 流式输出时\n<div aria-live="polite" aria-atomic="false">\n  正在生成代码... {streamingContent}\n</div>

关键：使用aria-live="polite"而不是"assertive"，避免打断用户的屏幕阅读器。

4. 色觉无障碍

代码编辑器中的语法高亮和错误标记不能仅靠颜色区分：

// 错误标记同时使用颜色和下划线\n.editor-error {\n  color: #ef4444;          /* 红色 */\n  text-decoration: wavy underline;  /* 波浪下划线 */\n  text-decoration-color: #ef4444;\n}\n\n// 成功标记同时使用颜色和图标\n.editor-success::before {\n  content: "✓";           /* 对勾图标 */\n  color: #22c55e;         /* 绿色 */\n}

5. 高对比度模式

MonkeyCode 支持高对比度主题：

@media (prefers-contrast: high) {\n  .editor {\n    border: 2px solid;    /* 更粗的边框 */\n  }\n  .syntax-keyword {\n    font-weight: bold;    /* 加粗关键词 */\n  }\n}

无障碍测试方法

MonkeyCode 使用的无障碍测试工具：

• axe-core — 自动化无障碍检测（集成到CI）
• Lighthouse Accessibility — 每次发布前运行
• NVDA/VoiceOver — 手动测试屏幕阅读器兼容性
• 键盘-only测试 — 不使用鼠标完成所有操作

CI中的无障碍检查

# .github/workflows/a11y.yml\nname: Accessibility Check\non: [pull_request]\njobs:\n  a11y:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - run: npm install\n      - run: npm run build\n      - run: npx playwright test --grep @a11y\n      # axe-core扫描\n      - run: npx axe http://localhost:3000 --exit

踩过的坑

坑1：Monaco Editor的无障碍支持

Monaco Editor本身有无障碍支持，但需要额外配置：

const editor = monaco.editor.create(container, {\n  // 开启无障碍支持\n  accessibilitySupport: 'auto',\n  // 屏幕阅读器优化的行高\n  lineNumbers: 'on',\n  // 焦点指示器\n  renderLineHighlight: 'all',\n});

坑2：终端的无障碍化

xterm.js默认对屏幕阅读器不友好。解决方案是在终端旁边提供一个"终端内容文本区域"，实时同步终端输出：

<div className="terminal-container">\n  {/* 视觉用户看到的终端 */}\n  <div className="terminal-visual" aria-hidden="true">\n    <xterm />\n  </div>\n  \n  {/* 屏幕阅读器读取的内容 */}\n  <div className="terminal-a11y" role="log" aria-live="polite">\n    {terminalContent}\n  </div>\n</div>

给开源项目的无障碍建议

1. 从ARIA标签开始 — 投入最小，效果最大
2. 键盘导航优先 — 如果只能做一项，做键盘支持
3. 自动化检测 — axe-core集成到CI，零成本
4. 标记为good first issue — 无障碍改进非常适合社区贡献
5. 不要追求完美 — 渐进式改进比什么都不做好

总结

无障碍不是慈善项目，而是产品设计的基本要求。MonkeyCode通过系统性的无障碍设计，让更多开发者能够使用AI编程工具。这些改进也随开源代码一起发布，任何使用MonkeyCode的项目都能受益。

如果你正在维护开源项目，今天就添加一个"无障碍改进"的good first issue吧。

GitHub：github.com/chaitin/MonkeyCode