用途
UI Verification Skill 用于在创建任何新 UI 组件后，快速验证生成的界面是否满足可访问性标准。它需要与 ui-web.md 或 ui-mobile.md 一起加载使用。
主要能力
该技能提供一份发布前检查清单（Pre-Flight Checklist），在交付任何 UI 之前逐项核对：
可见性检查
- 所有按钮都有可见背景或边框
- 没有文字与其背景颜色相同
- 所有文字满足 4.5:1 对比度
- Ghost/文字按钮有可见边框
触摸/点击目标
- 所有按钮最小高度 44px
- 图标按钮最小 44x44px
- 可点击元素之间有足够间距
状态
- 悬停状态可见（Web）
- 按下状态可见（移动端）
- 键盘导航时有焦点环
- 禁用状态视觉上可区分（不透明度 0.5）
- 加载状态显示指示器
深色模式（如适用）
- 文字在深色背景上可读
- 深色模式下边框可见
- 深色背景上不使用 gray-400 文字
响应式（Web）
- 移动端（320px）无横向滚动
- 所有断点下内容可读
- 移动端触摸目标足够大
使用方式
快速对比度检查
使用浏览器 DevTools：
- 右键元素 → Inspect
- 在 Styles 面板中点击颜色值
- 查看对比度比值显示
- 必须显示 ✓ 表示符合 AA 标准（文字 4.5:1）
在线工具：
- https://webaim.org/resources/contrastchecker/
- https://coolors.co/contrast-checker
Tailwind 安全配色组合
浅色模式（白色背景上）：
- ✓ text-gray-900 (#111827) = 16:1
- ✓ text-gray-800 (#1F2937) = 12:1
- ✓ text-gray-700 (#374151) = 9:1
- ✓ text-gray-600 (#4B5563) = 6:1
- ✗ text-gray-500 (#6B7280) = 4.6:1（勉强）
- ✗ text-gray-400 (#9CA3AF) = 2.6:1（不合格）
深色模式（gray-900 背景上）：
- ✓ text-white (#FFFFFF) = 16:1
- ✓ text-gray-100 (#F3F4F6) = 13:1
- ✓ text-gray-200 (#E5E7EB) = 11:1
- ✓ text-gray-300 (#D1D5DB) = 8:1
- ✗ text-gray-400 (#9CA3AF) = 5:1（勉强）
- ✗ text-gray-500 (#6B7280) = 3:1（不合格）
常见修复
不可见按钮：
// PROBLEM: No visible boundary
<button className="text-gray-500">Click</button>
// FIX: Add background OR border
<button className="bg-gray-100 text-gray-900 px-4 py-3 rounded-lg">
Click
</button>
// OR
<button className="border border-gray-300 text-gray-700 px-4 py-3 rounded-lg">
Click
</button>
低对比度文字：
// PROBLEM: Light gray on white
<p className="text-gray-400">Secondary text</p>
// FIX: Use darker gray
<p className="text-gray-600">Secondary text</p>
缺少焦点状态：
// PROBLEM: Focus removed without replacement
<button className="outline-none">Submit</button>
// FIX: Add visible focus ring
<button className="outline-none focus-visible:ring-2 focus-visible:ring-blue-500 focus-visible:ring-offset-2">
Submit
</button>
触摸目标过小：
// PROBLEM: Too small for fingers
<button className="p-1 text-sm">×</button>
// FIX: Minimum 44px
<button className="w-11 h-11 flex items-center justify-center">×</button>
深色模式破损：
// PROBLEM: Same colors in both modes
<p className="text-gray-400">Text</p>
// FIX: Adjust for dark mode
<p className="text-gray-600 dark:text-gray-300">Text</p>
自动化检查（可选）
ESLint 插件：
npm install -D eslint-plugin-jsx-a11y
// .eslintrc
{
"extends": ["plugin:jsx-a11y/recommended"]
}
Playwright 快速测试：
// e2e/accessibility.spec.ts
import { test, expect } from '@playwright/test';
import AxeBuilder from '@axe-core/playwright';
test('no accessibility violations', async ({ page }) => {
await page.goto('/');
const results = await new AxeBuilder({ page }).analyze();
expect(results.violations).toEqual([]);
});
适用场景
- 在交付任何 UI 之前做快速自查
- 生成新 UI 组件后的可访问性验证
- 需要检查按钮可见性、对比度、触摸目标、状态与深色模式时
限制
- 该技能为快速验证清单，并非完整测试方案
- 当构建组件库、多名开发者协作 UI、UI 频繁变更或需要强制执行设计系统时，应加入更全面的视觉测试（Playwright 截图、Storybook）
- 对于个人项目或 MVP，上述检查清单已足够
- 官方文本暂未提供