Claude Code Focus Management Audit Accessibility Guide

Focus management is one of the most critical yet overlooked aspects of web accessibility. When users navigate your application using keyboards or assistive technologies, the focus indicator must clearly show their current position, and focus must logically move through interactive elements. This guide shows you how to use Claude Code skills to audit and improve focus management across your projects.

Understanding Focus Management in Web Applications

Focus management refers to how your application controls which element receives keyboard input at any given time. Proper focus management ensures that:

Users can tab through all interactive elements in a logical order
Focus is visually indicated at all times
Modal dialogs trap focus appropriately
Focus moves to newly opened content automatically
Focus returns to the trigger element when dialogs close

Modern JavaScript frameworks make focus management challenging because content often loads dynamically. Single-page applications must carefully track focus state as users navigate between views.

Setting Up Claude Code for Accessibility Auditing

Claude Code provides several skills that help with accessibility auditing. First, ensure you have the necessary skills installed in your environment:

~/.claude/skills/
├── frontend-design.md
├── accessibility-audit.md
└── axe.md

The /frontend-design skill includes accessibility-first patterns when generating components. The dedicated accessibility audit skill provides comprehensive checklists for WCAG compliance verification.

Creating a Focus Management Audit Workflow

When auditing focus management, you’ll want to verify several key areas. Let’s create a practical workflow using Claude Code:

Step 1: Audit Focus Indicator Visibility

The first thing to check is whether focus indicators are visible. Claude Code can help you identify CSS that might be removing or hiding focus rings:

// Ask Claude Code to find potential focus indicator issues
// Search for: outline: none, outline: 0, or focus { outline: none }

This command helps you find CSS rules that disable focus indicators. Review each occurrence and ensure they include alternative focus styles:

/* Problematic - removes focus without replacement */
button:focus {
  outline: none;
}

/* Accessible - removes default but adds visible alternative */
button:focus {
  outline: none;
  box-shadow: 0 0 0 3px rgba(66, 153, 225, 0.5);
}

Step 2: Verify Tab Order

Logical tab order is essential for keyboard navigation. Claude Code can analyze your HTML structure to identify tab order issues:

Interactive elements should appear in a logical reading order
Tabindex values should be 0 (natural order) or -1 (programmatically focusable only)
Positive tabindex values create unpredictable tab orders

Modals present unique focus management challenges. When a modal opens, focus should:

Move to the first focusable element inside the modal
Be trapped within the modal (Tab key cycles within)
Return to the triggering element when closed

Use axe-core to detect modal focus issues:

// Run axe accessibility audit
const accessibilityResults = await axe.run(document);
const focusIssues = accessibilityResults.violations.filter(
  violation => violation.id.includes('focus')
);

Practical Examples: Fixing Common Focus Issues

Here’s how Claude Code helps you implement proper modal focus management:

import { useEffect, useRef } from 'react';

function Modal({ isOpen, onClose, children }) {
  const modalRef = useRef(null);
  const previousFocusRef = useRef(null);

  useEffect(() => {
    if (isOpen) {
      // Store previously focused element
      previousFocusRef.current = document.activeElement;
      
      // Focus first focusable element in modal
      const focusableElements = modalRef.current.querySelectorAll(
        'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
      );
      
      if (focusableElements.length > 0) {
        focusableElements[0].focus();
      }
      
      // Trap focus within modal
      const handleKeyDown = (e) => {
        if (e.key === 'Tab') {
          const focusable = Array.from(focusableElements);
          const firstElement = focusable[0];
          const lastElement = focusable[focusable.length - 1];
          
          if (e.shiftKey && document.activeElement === firstElement) {
            e.preventDefault();
            lastElement.focus();
          } else if (!e.shiftKey && document.activeElement === lastElement) {
            e.preventDefault();
            firstElement.focus();
          }
        }
        
        if (e.key === 'Escape') {
          onClose();
        }
      };
      
      document.addEventListener('keydown', handleKeyDown);
      return () => document.removeEventListener('keydown', handleKeyDown);
    } else {
      // Return focus to trigger
      if (previousFocusRef.current) {
        previousFocusRef.current.focus();
      }
    }
  }, [isOpen, onClose]);

  return (
    <div ref={modalRef} role="dialog" aria-modal="true">
      {children}
    </div>
  );
}

Example 2: Implementing Skip Links

Skip links help keyboard users bypass repetitive navigation. Claude Code can generate the HTML and CSS:

<!-- Add as first focusable element in body -->
<a href="#main-content" class="skip-link">Skip to main content</a>

<!-- Target element -->
<main id="main-content">

.skip-link {
  position: absolute;
  top: -40px;
  left: 0;
  background: #000;
  color: #fff;
  padding: 8px;
  z-index: 100;
  transition: top 0.3s;
}

.skip-link:focus {
  top: 0;
}

Automating Focus Audits with Claude Code Skills

You can automate focus management testing using the axe skill with Claude Code. Here’s a comprehensive audit command:

// Request Claude Code to run accessibility audit
"Run a focus management audit on this page and identify:
// - Elements with removed focus indicators
// - Incorrect tabindex usage
// - Missing aria labels on interactive elements
// - Modal focus trap issues
// - Focus order problems"

Claude Code will analyze your codebase and provide specific recommendations for each issue found.

WCAG Success Criteria for Focus Management

When auditing focus management, verify compliance with these WCAG 2.1 criteria:

Criterion	Requirement	Testing Method
2.1.1 Keyboard	All functionality available via keyboard	Tab through entire page
2.1.2 No Keyboard Trap	Focus not trapped in any element	Tab forward and backward
2.4.1 Bypass Blocks	Skip links provided	Press Tab on page load
2.4.3 Focus Order	Focus order is logical	Observe tab sequence
2.4.7 Focus Visible	Focus indicator always visible	Visual inspection

Conclusion

Focus management is fundamental to web accessibility. By leveraging Claude Code skills and automation tools like axe-core, you can systematically audit and improve focus handling in your applications. Start with the basics—visible focus indicators and logical tab order—then address more complex scenarios like modal focus traps and dynamic content focus management.

Remember: accessible focus management isn’t just about compliance; it improves usability for all keyboard users, creating a better experience for everyone.

Built by theluckystrike — More at zovo.one