tomevault-io Accessibility (A11y) Skill
技能描述
专注于 Web 无障碍标准 (WCAG) 的检查与修复。帮助开发者发现潜在的访问性问题并提供修复代码。
📝 代码示例
1. 图片无障碍
// ✅ 正确的图片无障碍实现
function AccessibleImage({ src, alt, caption }: ImageProps) {
return (
<figure>
<img
src={src}
alt={alt} // 描述性文字，装饰性图片使用 alt=""
loading="lazy"
/>
{caption && <figcaption>{caption}</figcaption>}
</figure>
);
}
// ❌ 避免
<img src="photo.jpg" /> // 缺少 alt
<img src="photo.jpg" alt="image" /> // 无意义的 alt
2. 表单无障碍
// ✅ 正确的表单关联
function AccessibleForm() {
return (
<form>
<div>
<label htmlFor="email">邮箱地址</label>
<input
id="email"
type="email"
aria-describedby="email-hint"
aria-required="true"
/>
<span id="email-hint">我们会向此邮箱发送验证码</span>
</div>
<div>
<label htmlFor="password">密码</label>
<input
id="password"
type="password"
aria-describedby="password-error"
aria-invalid={hasError ? 'true' : 'false'}
/>
{hasError && (
<span id="password-error" role="alert">
密码至少需要8个字符
</span>
)}
</div>
<button type="submit">登录</button>
</form>
);
}
3. 键盘导航
// ✅ 可键盘操作的按钮
function AccessibleButton({ onClick, children }: ButtonProps) {
return (
<button
=> {
if (e.key === 'Enter' || e.key === ' ') {
e.preventDefault();
onClick();
}
}}
>
{children}
</button>
);
}
// ✅ 焦点管理样式
const focusStyles = css`
&:focus-visible {
outline: 3px solid #005fcc;
outline-offset: 2px;
}
`;
4. 模态框焦点陷阱
// ✅ 模态框无障碍实现
function AccessibleModal({ isOpen, onClose, title, children }: ModalProps) {
const modalRef = useRef<HTMLDivElement>(null);
const previousActiveElement = useRef<Element | null>(null);
useEffect(() => {
if (isOpen) {
previousActiveElement.current = document.activeElement;
modalRef.current?.focus();
document.body.style.overflow = 'hidden';
} else {
previousActiveElement.current?.focus();
document.body.style.overflow = '';
}
}, [isOpen]);
const handleKeyDown = (e: React.KeyboardEvent) => {
if (e.key === 'Escape') onClose();
};
if (!isOpen) return null;
return (
<div
role="dialog"
aria-modal="true"
aria-labelledby="modal-title"
ref={modalRef}
tabIndex={-1}
>
<div className="modal-backdrop" aria-hidden="true" />
<div className="modal-content">
<h2 id="modal-title">{title}</h2>
{children}
<button aria-label="关闭对话框">
<CloseIcon />
</button>
</div>
</div>
);
}
5. 颜色对比度
/* ✅ 符合 WCAG AA 标准的对比度 */
.text-primary {
color: #1a1a1a; /* 与白色背景对比度 > 12:1 */
}
.text-secondary {
color: #4a4a4a; /* 与白色背景对比度 > 7:1 */
}
/* ✅ 不只依赖颜色传达信息 */
.status-success {
color: #0a8754;
}
.status-success::before {
content: '✓ '; /* 同时使用图标 */
}
/* ✅ 聚焦状态清晰可见 */
:focus-visible {
outline: 3px solid #005fcc;
outline-offset: 2px;
}
6. ARIA 地标与语义化
// ✅ 语义化页面结构
function AccessibleLayout({ children }: { children: React.ReactNode }) {
return (
<>
<header role="banner">
<nav aria-label="主导航">
<ul>
<li><a href="/">首页</a></li>
<li><a href="/about">关于</a></li>
</ul>
</nav>
</header>
<main role="main" id="main-content">
<h1>页面标题</h1>
{children}
</main>
<aside aria-label="侧边栏">
{/* 侧边栏内容 */}
</aside>
<footer role="contentinfo">
{/* 页脚内容 */}
</footer>
</>
);
}
♿ 常用指令
1. 快速审查 (Audit)
/ui-design 审查这段代码的无障碍问题
# 关注点:
# - 语义化标签 (nav, main, aside)
# - ARIA 属性使用
# - 键盘可访问性 (tabindex, focus)
# - 图片 Alt 文本
2. 对比度检查 (Contrast)
/ui-design 检查这个配色的对比度是否符合 WCAG AA 标准
3. 修复建议 (Fix)
/ui-design 修复这个表单的 Label 关联和 ARIA 描述问题
/ui-design 为这个模态框添加 Focus Trap (焦点陷阱) 功能
✅ Self-Checklist (自查清单)
在提交代码前，请检查：
- 所有的
<img>都有alt属性吗？ - 所有的表单输入框都有对应的
<label>吗？ - 按钮是否有清晰的文字描述（避免仅图标）？
- 页面是否可以仅用键盘顺畅操作？
- 颜色对比度是否足够清晰？
Converted and distributed by TomeVault — claim your Tome and manage your conversions.