UI 视觉设计 / 系统课时

检查键盘导航与颜色对比度

检查键盘导航与颜色对比度

这一课把 Figma 中的颜色与交互规范落实到浏览器验收:先用可计算的阈值排除低对比度,再用自动测试检查语义和键盘路径,最后亲自操作键盘与屏幕阅读器,确认真实用户能够看见焦点、完成操作并理解结果。

学习目标

  • 按 WCAG 2.2 AA 核查文字、控件边界与焦点状态。
  • 使用 Playwright 和 axe-core 运行可复现的键盘及语义检查。
  • 用人工键盘操作和屏幕阅读器补齐自动化无法判断的问题。

将设计规范转换为验收条件

检查对象 WCAG 2.2 AA 判定 具体做法
普通文字 对比度至少 4.5:1 核对正文、占位文字及悬停提示的实际前景与背景色
大号文字 对比度至少 3:1 常规字重至少 24 CSS px,或粗体约 18.7 CSS px
必需的控件边界与状态图标 与相邻颜色至少 3:1 检查输入框边框、选中标识,不将纯装饰图标算入
键盘焦点 焦点可见,且不被作者内容完全遮挡 检查 :focus-visible、固定顶栏和弹窗遮挡

例如,普通文字 #94A3B8 放在白色 #FFFFFF 上约为 2.56:1,不合格;改成 #64748B 后约为 4.76:1,满足普通文字 AA。应修改对应的语义颜色 Token,而不是只给单个页面打补丁。

Figma 变量中的色值只是起点。最终要检查浏览器计算后的颜色、透明度、背景叠加,以及 Light、Dark、Hover、Focus、Error 各状态。禁用控件的文字有标准豁免,不可据此放宽正常可交互控件的要求。

用 Playwright 同时检查键盘与自动扫描

在安装有 Node.js 20 或更高版本的空目录,依次执行 npm init -y、npm install -D @playwright/test @axe-core/playwright 和 npx playwright install chromium。创建文件 tests/a11y.spec.js。示例使用内嵌页面,不依赖业务服务器;接入真实项目时将 page.setContent(...) 改为指向待测页面的 page.goto(...)。

js
const { test, expect } = require('@playwright/test');
const AxeBuilder = require('@axe-core/playwright').default;

test('键盘顺序、语义和可检测的对比度问题', async ({ page }) => {
  await page.setContent(`
    <!doctype html>
    <html lang="zh-CN">
      <head>
        <title>偏好设置</title>
        <style>
          body { font: 16px Arial, sans-serif; background: #fff; color: #0f172a; }
          input { border: 2px solid #64748b; padding: 8px; }
          button { background: #1d4ed8; color: #fff; border: 0; padding: 12px 16px; }
          :focus-visible { outline: 3px solid #0f172a; outline-offset: 3px; }
          .skip { position: absolute; left: -9999px; }
          .skip:focus { left: 16px; top: 16px; background: #fff; }
        </style>
      </head>
      <body>
        <a class="skip" href="#main">跳到主要内容</a>
        <main id="main" tabindex="-1">
          <h1>偏好设置</h1>
          <label for="email">邮箱</label>
          <input id="email" type="email">
          <button id="save">保存设置</button>
          <p id="status" role="status"></p>
        </main>
        <script>
          document.querySelector('#save').addEventListener('click', () => {
            document.querySelector('#status').textContent = '已保存';
          });
        </script>
      </body>
    </html>
  `);

  const skip = page.getByRole('link', { name: '跳到主要内容' });
  const email = page.getByRole('textbox', { name: '邮箱' });
  const save = page.getByRole('button', { name: '保存设置' });

  // 用真实按键事件检查顺序,避免只验证元素存在
  await page.keyboard.press('Tab');
  await expect(skip).toBeFocused();
  await page.keyboard.press('Tab');
  await expect(email).toBeFocused();
  await page.keyboard.press('Tab');
  await expect(save).toBeFocused();

  // 原生按钮应支持空格激活,结果由状态区域表达
  await page.keyboard.press('Space');
  await expect(page.getByRole('status')).toHaveText('已保存');
  await page.keyboard.press('Shift+Tab');
  await expect(email).toBeFocused();

  // axe 扫描可自动发现的 WCAG A/AA 问题
  const result = await new AxeBuilder({ page })
    .withTags(['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'wcag22aa'])
    .analyze();
  expect(result.violations.map(item => item.id)).toEqual([]);
});

预期结果:在项目根目录运行 npx playwright test tests/a11y.spec.js --reporter=line,通过后控制台包含:

text
1 passed (<TIME>)

<TIME> 是实际耗时,因环境而异。若失败,先检查焦点断言位置,再读取 result.violations 的规则 ID 与节点信息;扫描结果为空不代表整页完全符合 WCAG。

用真实键盘与屏幕阅读器补测

自动扫描可以发现部分颜色和名称问题,但无法可靠判断焦点顺序是否符合业务意图、焦点提示是否足够清晰,或屏幕阅读器朗读是否易懂。验收应分成自动检查与人工操作两路,最后合并缺陷。

设计与代码无障碍验收的自动及人工双路径

对实际业务页面按以下顺序走一遍;建议至少覆盖一个表单页和一个含 Dialog 的页面。

  1. 不碰鼠标,从地址栏回到页面,按 Tab 逐项检查焦点顺序;按 Shift+Tab 逆向返回。跳转链接应能跳过重复导航,焦点不应跳入隐藏控件。
  2. 对按钮分别用 Enter 或 Space 激活;对原生链接用 Enter;对有弹窗的页面检查 Escape 关闭行为、弹窗内焦点约束及关闭后焦点返回触发按钮。
  3. 在 Windows 使用 NVDA,或在 macOS 使用 VoiceOver,核对输入框朗读的名称与角色,例如“邮箱,编辑框”;确认错误提示与保存结果能被感知。朗读措辞随系统和版本变化,核查语义即可,不逐字比对。
  4. 切到深色主题并放大页面,逐个检查焦点轮廓、底部固定栏遮挡、滚动后焦点位置、错误态提示。颜色不能成为唯一的错误信号。

记录可复现的缺陷并回归

一个有效缺陷需要留下:页面路径、组件及状态、主题、视口、复现按键、实际表现、期望表现和对应标准。例如:“偏好设置 / 输入提示 / Light / 375px;灰字 #94A3B8 对白色仅 2.56:1,低于 4.5:1”。修复时把语义 Token 改为 #64748B 并确认其他引用处仍适用,而非仅替换截图颜色。

修复后重新运行自动测试,并用键盘走完原路径;涉及弹窗、主题切换和动态错误消息时,还需重新做人工朗读检查。可把 WCAG 2.2 与 Playwright 可访问性测试指南 作为验收依据。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

检查键盘导航与颜色对比度

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通