keyboard-accessibility
WCAG 2.2 keyboard navigation, ARIA APG interaction patterns, roving tabindex in composite widgets, visible focus indicators, skip-to-content links, and zero keyboard traps across Web, Native, and TUI.
- License 许可
- MIT
- 最近更新
- 2026-10-16
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- keyboard-accessibility
- description
- WCAG 2.2 keyboard navigation, ARIA APG interaction patterns, roving tabindex in composite widgets, visible focus indicators, skip-to-content links, and zero keyboard traps across Web, Native, and TUI.
02 资源文件 5
- 参考文档checks/keyboard-accessibility-checklist.md1.2 KB
- 参考文档manifest.json1.8 KB
- 参考文档references/keyboard-accessibility-guide.md1.7 KB
- 脚本scripts/verify.sh1.9 KB
- 参考文档templates/keyboard-accessibility-report.md1.3 KB
03 SKILL.md 正文
Keyboard Navigation & Operability Engineering
1. Title and Description
Keyboard Navigation & Operability Engineering (keyboard-accessibility)
Enforces complete, mouse-independent keyboard operability across Web applications, Desktop native software (egui, Slint), and Terminal User Interfaces (TUI). Implements W3C WAI ARIA Authoring Practices Guide (APG) keyboard patterns, roving tabindexes, clear focus indicators, and WCAG 2.2 Success Criteria.
2. Purpose
Guarantee that all interactive digital experiences can be operated quickly, intuitively, and without barriers by keyboard-only users, switch-device operators, and screen reader navigators, preventing inaccessible mouse-only interfaces and keyboard traps.
3. Prerequisites
- UI component markup or interface source code.
- Functional knowledge of ARIA Authoring Practices Guide (APG) design patterns.
4. Inputs
- View layout, interactive components (dialogs, menus, tables, tabs, forms).
- Target platform: Web (DOM), Desktop (AccessKit, OS UI automation), or TUI (Terminal).
5. Outputs
- Fully keyboard-operable component logic with zero mouse dependence.
- Automated keyboard navigation tests (Tab order, arrow key navigation, Escape handling).
- Audit report conforming to
templates/keyboard-accessibility-report.md.
6. Execution Steps
Step 1: Establish Logical DOM & Tab Order
- Reading Order Equals Tab Order: The sequence of interactive elements in the DOM must strictly reflect the logical visual reading flow. Never reorder visual elements with CSS
orderorflex-direction: reversewithout synchronizing the underlying DOM sequence. - Tabindex Discipline:
tabindex="0": Inserts a naturally non-focusable element into the keyboard tab order.tabindex="-1": Removes an element from sequential tab order while retaining programmatic focusability (element.focus()).- Strictly Forbidden:
tabindex > 0(positive tabindexes destroy predictable tab order and are prohibited).
Step 2: Implement ARIA APG Composite Widget Patterns
Composite widgets (menus, tab lists, toolbars, grids, tree views) must present a single tab stop to the outer page, managing internal item navigation via arrow keys:
- Roving Tabindex Pattern:
- The currently active/focused item in the widget has
tabindex="0". - All sibling items in the widget have
tabindex="-1". - When the user presses
ArrowRightorArrowDown, change the current item totabindex="-1", set the next item totabindex="0", and call.focus().
- The currently active/focused item in the widget has
- Keyboard Mapping by Component Type:
- Tabs:
Left/Rightarrows switch active tab;Tabkey moves focus directly into the activetabpanel. - Dropdown Menus & Comboboxes:
DownArrowopens and navigates items;Enterselects;Escapecloses and returns focus to the trigger button. - Dialogs / Modals: Immediately trap focus inside the modal;
Escapecloses the modal. - Sliders:
Left/Downdecreases value;Right/Upincreases value;Home/Endsets min/max.
- Tabs:
Step 3: Enforce Visible Focus Indicators (WCAG 2.2 SC 2.4.7 & 2.4.11)
- Never Remove Outlines Without Replacement: Never author
outline: noneoroutline: 0without immediately defining an alternative high-visibility:focus-visiblestyle. - Focus Appearance Standards:
- Contrast ratio of the focus indicator must be at least 3:1 against the background and against the unfocused component border.
- Minimum thickness: 2px solid, with an offset (e.g.
outline-offset: 2px) to ensure the indicator is not clipped by parent containers.
Step 4: Bypass Blocks & Skip Links (WCAG SC 2.4.1)
Provide a hidden-until-focused skip link as the very first interactive element on any page with global navigation:
<a href="#main-content" class="sr-only focus:not-sr-only focus:absolute focus:p-4 focus:bg-white focus:text-black focus:z-50">
Skip to main content
</a>
Step 5: Prevent and Eliminate Keyboard Traps (WCAG SC 2.1.2)
- Ensure the user can navigate into and out of any component using only standard keyboard controls (
Tab,Shift+Tab,Escape). - If focus enters an embedded editor, iframe, or custom canvas, provide an explicit documented escape chord (e.g.
Escfollowed byTab).
Step 6: Native Desktop & TUI Keyboard Parity
- Desktop (egui / Slint / AccessKit): Ensure custom widgets implement keyboard event listeners (
egui::Event::Key) and register focus nodes. - Terminal (Bubble Tea): Support standard navigation keys (
Tab,Shift+Tab,Enter,Esc) and optional vim keys (j/k) configurable via KeyMaps.
7. Verification
# 1. Automated keyboard navigation test
npm test -- src/tests/keyboard-navigation.test.ts
# 2. Audit script for positive tabindexes and outline suppression
./scripts/verify.sh .
8. Fallbacks & Failure Recovery
| Failure Class | Root Cause | Deterministic Remediation |
|---|---|---|
| Focus Lost on DOM Removal | An active focused element is deleted or unmounted | Before removing element from DOM, programmatically move focus to a logical parent or previous sibling (previousSibling.focus()). |
| Keyboard Trap in Modal | Modal does not handle Tab key wrapping | Use focus-trap library or native <dialog> element with .showModal(). |
| Focus Indicator Clipped | Parent container has overflow: hidden |
Use box-shadow or outline-offset: -2px (inset indicator) instead of outer offset. |
| Arrow Keys Scroll Entire Page | Event listener fails to prevent default browser behavior | Call event.preventDefault() inside the specific ArrowUp / ArrowDown key handlers. |
9. Constraints
- Zero positive tabindexes:
tabindex="1"or higher is strictly forbidden. - Complete parity: Every single action performable by mouse click must have a documented, functional keyboard path.
- Visible focus non-negotiable: Focus rings must remain distinctly visible in all color themes and high-contrast modes.
10. Examples
Anti-Pattern: Clickable Div Without Keyboard Support
<!-- BAD: Mouse-only div, not in tab order, no keyboard activation, outline suppressed -->
<div onclick="openMenu()" style="outline: none; cursor: pointer;">
Options Menu
</div>
Idiomatic Pattern: ARIA APG Roving Tabindex Toolbar
// GOOD: Full roving tabindex keyboard navigation, semantic roles, focus indicators
import React, { useRef, useState } from 'react';
interface ToolbarProps {
items: Array<{ id: string; label: string; onAction: () => void }>;
}
export const AccessibleToolbar: React.FC<ToolbarProps> = ({ items }) => {
const [focusedIndex, setFocusedIndex] = useState(0);
const buttonRefs = useRef<(HTMLButtonElement | null)[]>([]);
const handleKeyDown = (e: React.KeyboardEvent, index: number) => {
let nextIndex = index;
if (e.key === 'ArrowRight' || e.key === 'ArrowDown') {
e.preventDefault();
nextIndex = (index + 1) % items.length;
} else if (e.key === 'ArrowLeft' || e.key === 'ArrowUp') {
e.preventDefault();
nextIndex = (index - 1 + items.length) % items.length;
} else if (e.key === 'Home') {
e.preventDefault();
nextIndex = 0;
} else if (e.key === 'End') {
e.preventDefault();
nextIndex = items.length - 1;
}
if (nextIndex !== index) {
setFocusedIndex(nextIndex);
buttonRefs.current[nextIndex]?.focus();
}
};
return (
<div role="toolbar" aria-label="Editor Actions" className="flex gap-2 p-2 border rounded">
{items.map((item, index) => (
<button
key={item.id}
ref={(el) => (buttonRefs.current[index] = el)}
tabIndex={focusedIndex === index ? 0 : -1} // Roving tabindex
onClick={item.onAction}
onKeyDown={(e) => handleKeyDown(e, index)}
className="px-3 py-1.5 rounded focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-blue-600 focus-visible:ring-offset-2"
>
{item.label}
</button>
))}
</div>
);
};
04 同仓库更多 Skills
zoom-reflow
暂无简介
wireframe-styleguide
暂无简介
visual-regression
Pixel-by-pixel snapshot testing, Playwright integration, dynamic content masking, deterministic font rendering, and cross-browser CI gates
ui-implementation
Component-driven UI implementation, multi-state matrix (default, hover, focus-visible, active, disabled, loading, empty, error), DTCG design tokens, responsive layout contracts, and accessibility tree mapping.
tui-editor-engine
Text buffer and editing semantics for a terminal code editor — index conversion, transaction-first editing, multi-cursor invariants, undo grouping, and large-file behaviour.
tree-sitter-context-indexing
暂无简介