Loading...
Loading...
Compare original and translation side by side
| You Decide | Claude Code Implements |
|---|---|
| "Our app must be keyboard-navigable" | Proper focus management, tab order, keyboard handlers |
| "All images need descriptions" | Alt text on every image |
| "Forms must have clear error messages" | Linked labels, aria-describedby, validation messages |
| "We support screen readers" | Semantic HTML, ARIA roles, live regions |
| 由你决策 | Claude Code 实现 |
|---|---|
| "我们的应用必须支持键盘导航" | 正确的焦点管理、Tab键顺序、键盘事件处理程序 |
| "所有图片都需要描述" | 为每张图片添加替代文本(Alt text) |
| "表单必须包含清晰的错误提示" | 关联标签、aria-describedby属性、验证提示 |
| "我们要支持屏幕阅读器" | 语义化HTML、ARIA角色、实时区域 |
Audit and fix HTML semantics across the app:
- Use <button> for actions, <a> for navigation (never the reverse)
- Use <nav>, <main>, <aside>, <header>, <footer>, <article>, <section> for page structure
- Use <h1>-<h6> in order (no skipped levels, never used just for styling)
- Use <label> linked to every form input
- Use <ul>/<ol> for lists
- Use <table> with proper <th> headers for tabular data
- Use <dialog> for modalsAudit and fix HTML semantics across the app:
- Use <button> for actions, <a> for navigation (never the reverse)
- Use <nav>, <main>, <aside>, <header>, <footer>, <article>, <section> for page structure
- Use <h1>-<h6> in order (no skipped levels, never used just for styling)
- Use <label> linked to every form input
- Use <ul>/<ol> for lists
- Use <table> with proper <th> headers for tabular data
- Use <dialog> for modalsEnsure full keyboard accessibility:
- Every interactive element (button, link, input, select) must be reachable with Tab
- Every interactive element must be activatable with Enter or Space
- Tab order must follow visual reading order
- Focus states must be clearly visible (not just outline: none)
- Modals must trap focus inside and return focus to the trigger on close
- Add a "Skip to main content" link as the first focusable elementEnsure full keyboard accessibility:
- Every interactive element (button, link, input, select) must be reachable with Tab
- Every interactive element must be activatable with Enter or Space
- Tab order must follow visual reading order
- Focus states must be clearly visible (not just outline: none)
- Modals must trap focus inside and return focus to the trigger on close
- Add a "Skip to main content" link as the first focusable element| Element | Minimum Contrast Ratio |
|---|---|
| Body text | 4.5:1 against background |
| Large text (18px+ or 14px+ bold) | 3:1 |
| UI components (borders, icons) | 3:1 |
Check and fix color contrast across the app:
- Verify all text meets WCAG AA contrast ratios (4.5:1 for body, 3:1 for large text)
- Verify UI elements (borders, icons, focus rings) meet 3:1 contrast
- Don't rely on color alone — add icons, patterns, or text labels alongside color indicators
- Test with the browser's built-in contrast checker| 元素 | 最低对比度 |
|---|---|
| 正文文本 | 与背景对比度4.5:1 |
| 大文本(18px及以上或14px及以上加粗) | 3:1 |
| UI组件(边框、图标) | 3:1 |
Check and fix color contrast across the app:
- Verify all text meets WCAG AA contrast ratios (4.5:1 for body, 3:1 for large text)
- Verify UI elements (borders, icons, focus rings) meet 3:1 contrast
- Don't rely on color alone — add icons, patterns, or text labels alongside color indicators
- Test with the browser's built-in contrast checkerFix form accessibility:
- Every input must have a visible <label> linked via for="id" attribute
- Placeholder text is NOT a label (it disappears on focus)
- Required fields: add visual indicator AND aria-required="true"
- Add autocomplete attributes for personal data: autocomplete="email", "name", etc.
Fix image accessibility:
- Every meaningful image needs descriptive alt text (max 125 chars)
- Decorative images need alt="" (empty alt, not missing alt)
- Charts and diagrams need a text description nearby or via aria-describedbyFix form accessibility:
- Every input must have a visible <label> linked via for="id" attribute
- Placeholder text is NOT a label (it disappears on focus)
- Required fields: add visual indicator AND aria-required="true"
- Add autocomplete attributes for personal data: autocomplete="email", "name", etc.
Fix image accessibility:
- Every meaningful image needs descriptive alt text (max 125 chars)
- Decorative images need alt="" (empty alt, not missing alt)
- Charts and diagrams need a text description nearby or via aria-describedbyImprove focus management and error handling:
- When a modal opens, move focus to the first interactive element inside
- When a modal closes, return focus to the button that opened it
- Trap focus inside modals (Tab shouldn't escape to the background)
- Connect error messages to inputs via aria-describedby
- When a form has errors, add aria-invalid="true" to invalid fields
- Announce dynamic content changes with aria-live="polite" (status messages) or aria-live="assertive" (errors)Improve focus management and error handling:
- When a modal opens, move focus to the first interactive element inside
- When a modal closes, return focus to the button that opened it
- Trap focus inside modals (Tab shouldn't escape to the background)
- Connect error messages to inputs via aria-describedby
- When a form has errors, add aria-invalid="true" to invalid fields
- Announce dynamic content changes with aria-live="polite" (status messages) or aria-live="assertive" (errors)Respect user motion preferences:
- Add a CSS media query: @media (prefers-reduced-motion: reduce) { * { animation: none !important; } }
- Disable autoplay on videos and carousels when reduced motion is preferred
- Keep transitions under 200ms or remove them for reduced-motion usersRespect user motion preferences:
- Add a CSS media query: @media (prefers-reduced-motion: reduce) { * { animation: none !important; } }
- Disable autoplay on videos and carousels when reduced motion is preferred
- Keep transitions under 200ms or remove them for reduced-motion usersRun an accessibility audit:
- Run axe-core or Lighthouse accessibility audit on our main pages
- Report all violations grouped by severity (critical, serious, moderate, minor)
- Fix all critical and serious violations
- Add accessibility checks to our CI pipeline so new issues are caught automaticallyRun an accessibility audit:
- Run axe-core or Lighthouse accessibility audit on our main pages
- Report all violations grouped by severity (critical, serious, moderate, minor)
- Fix all critical and serious violations
- Add accessibility checks to our CI pipeline so new issues are caught automatically| Mistake | Fix |
|---|---|
Adding | Never remove focus indicators. Style them instead. |
Using | Use semantic HTML elements. Buttons are |
| Placeholder as label | Always use a visible |
| Ignoring keyboard users | Test without a mouse. If you can't complete the flow, keyboard users can't either. |
| Bolting on ARIA to fix bad HTML | Fix the HTML first. ARIA is a repair tool, not a substitute. |
| Waiting until "later" to care | Build semantic HTML from day one. It's free and prevents 80% of issues. |
| 错误 | 修复方案 |
|---|---|
添加 | 永远不要移除焦点指示器,而是对其进行样式定制。 |
所有元素都用 | 使用语义化HTML元素。按钮要用 |
| 用占位符作为标签 | 始终使用可见的 |
| 忽略键盘用户 | 脱离鼠标进行测试。如果你无法完成流程,键盘用户也做不到。 |
| 用ARIA修补糟糕的HTML | 先修复HTML。ARIA是修复工具,而非替代品。 |
| 等到“以后”再重视无障碍访问 | 从第一天就使用语义化HTML构建应用。这无需额外成本,还能避免80%的问题。 |