wcag-audit-operable-keyboard-focus（WCAG 审核 operable keyboard focus）

When to Use

Use this tool when designing keyboard navigation flows, testing tab order, or ensuring logical focus progression through interactive elements.

Usage

Command Line

node scripts/validate.js --elements "header, nav, main, button, button, footer"
node scripts/validate.js --tab-order "1,2,3,4,5" --expected "1,2,3,4,5"
node scripts/validate.js --json '{"elements": ["header", "nav", "main", "button#submit"], "tabOrder": [1,2,3,4]}'

JSON Input

node scripts/validate.js --json '{
  "elements": ["header", "nav", "button#menu", "main", "button#submit", "footer"],
  "tabOrder": [1, 2, 3, 4, 5, 6],
  "expectedOrder": [1, 2, 4, 5, 3, 6]
}'

Parameters

• --elements: Comma-separated list of element identifiers
• --tab-order: Comma-separated list of tab order indices
• --expected: Expected logical order (optional)
• --json: JSON input with elements and tab order properties

Output

Returns JSON with validation results and issues:

{
  "elements": ["header", "nav", "main", "button", "footer"],
  "tabOrder": [1, 2, 3, 4, 5],
  "validation": {
    "logical": true,
    "complete": true,
    "issues": []
  },
  "recommendations": [
    "Consider moving primary action button before secondary navigation"
  ]
}

Examples

Validate simple tab order

$ node scripts/validate.js --elements "header, nav, main, button, footer" --tab-order "1,2,3,4,5"
✅ Logical order: PASS
✅ Complete coverage: PASS
✅ No focus traps: PASS
Focus order follows logical reading sequence

Detect focus order issues

$ node scripts/validate.js --elements "header, nav, button, main, footer" --tab-order "1,2,4,3,5"
❌ Logical order: FAIL
⚠️  Tab order issue: "main" (position 3) appears before "button" (position 4)
Recommendations:
- Move main content before secondary buttons
- Consider semantic HTML structure for better default tab order

WCAG Standards

• Logical Order: Focus order should follow logical reading sequence
• No Traps: Users should not get trapped in focus loops
• Complete Coverage: All interactive elements should be keyboard accessible
• Skip Links: Provide mechanisms to skip repeated navigation sections
• Modal Focus: Modal dialogs should manage focus appropriately

Best Practices

1. Follow reading order: Tab order should match visual reading sequence
2. Use semantic HTML: Proper heading hierarchy and landmarks improve default tab order
3. Provide skip links: Allow users to skip navigation sections
4. Test with keyboard: Verify all interactions work without mouse
5. Avoid focus traps: Ensure users can always move forward and backward

Focus Order Patterns

Good Order:

1. Header/Skip links
2. Main navigation
3. Main content
4. Footer links
5. Footer

Problematic Order:

1. Header
2. Footer links
3. Main navigation
4. Main content

Learn More

For more information about Agent Skills and how they extend AI capabilities.