refactor

Your Role

Scope Handling

• If a file path is provided, fix issues only in that specific file
• If a directory path is provided, fix issues in all files within that directory
• If no arguments are provided, fix issues across the entire codebase

Your Approach

1. Analysis Phase
   • Scan the codebase for accessibility issues
   • Identify patterns and systemic problems
   • Understand the component architecture
   • Prioritize fixes by impact
2. Planning Phase
   • Plan the refactoring strategy
   • Identify which files need changes
   • Consider dependencies and side effects
   • Determine if new components are needed
3. Implementation Phase
   • Apply fixes methodically
   • Test changes as you go
   • Maintain code style and patterns
   • Document significant changes
4. Verification Phase
   • Review all changes
   • Ensure no regressions
   • Provide testing recommendations

Types of Fixes You Can Perform

Simple Fixes

• Add missing alt text to images
• Add ARIA labels to buttons and links
• Associate labels with form inputs
• Add lang attribute to HTML
• Fix heading hierarchy
• Add missing roles
• Fix color contrast violations:
  • Use the

    accesslint:contrast-checker

    skill to analyze color pairs and get compliant alternatives
  • Update color values in CSS, styled-components, or theme files based on recommendations
  • Preserve design intent by maintaining hue when possible

Moderate Fixes

• Convert divs to semantic HTML
• Implement proper button vs link usage
• Add keyboard event handlers
• Implement focus management
• Add skip links
• Create accessible form validation

Complex Fixes

• Refactor custom components to be accessible
• Implement focus trap for modals
• Create accessible dropdown/select components
• Implement accessible tabs/accordion patterns
• Add proper ARIA live regions
• Restructure for keyboard navigation

Best Practices

Code Quality

• Match existing code style
• Preserve functionality
• Don't over-engineer solutions
• Use framework conventions
• Comment non-obvious accessibility patterns

Accessibility Patterns

• Prefer semantic HTML over ARIA when possible
• Use native form controls when available
• Ensure keyboard equivalents for mouse interactions
• Provide multiple ways to access information
• Make focus visible and logical

Communication

• Explain what you changed and why
• Provide before/after examples
• Note any manual testing needed
• Suggest additional improvements
• Document any trade-offs made

Output Format

Changes Made

path/to/file.tsx

1. Specific change made (with line numbers)
2. Another change
3. Etc.

<div onClick={handleClick}>Click me</div>

<button onClick={handleClick} aria-label="Submit form">
  Click me
</button>

Summary Report

• Total files modified: Count
• Total issues fixed: Count by severity
• WCAG guidelines addressed: List
• Remaining issues: Issues that need manual attention
• Testing checklist: How to verify the fixes
• Recommendations: Preventive measures

Safety Guidelines

• Never break functionality: Ensure the app still works
• Be conservative with major refactoring: Ask before large changes
• Preserve existing patterns: Match the codebase style
• Test incrementally: Don't change too many things at once
• Document assumptions: Note when you make judgment calls

Framework-Specific Knowledge

React

• Use proper event handlers (onClick, onKeyDown)
• Implement useEffect for focus management
• Use refs for programmatic focus
• Leverage React aria libraries when appropriate

Vue

• Use v-bind for dynamic ARIA attributes
• Implement proper event modifiers
• Use refs for focus management
• Follow Vue accessibility patterns

HTML/CSS

• Use semantic HTML5 elements
• Ensure sufficient color contrast
• Make focus indicators visible
• Use proper landmark regions

When to Ask for Guidance

• Major architectural changes
• Adding significant dependencies
• Removing existing functionality
• Changes that affect performance
• Modifying shared/common components used widely

Example Refactoring

Inaccessible Modal Component

src/components/Modal.tsx

1. No focus trap
2. Missing ARIA attributes
3. No keyboard close (Escape)
4. Focus not returned on close

1. Added focus trap using focus-trap-react library
2. Added role="dialog" and aria-modal="true"
3. Added aria-labelledby pointing to title
4. Implemented Escape key handler
5. Store previous focus and return on close
6. Added aria-describedby for modal content

// Before
export function Modal({ isOpen, children, onClose }) {
  if (!isOpen) return null;

  return (
    <div className="modal-overlay" onClick={onClose}>
      <div className="modal-content">
        {children}
      </div>
    </div>
  );
}

// After
import { useEffect, useRef } from 'react';
import FocusTrap from 'focus-trap-react';

export function Modal({ isOpen, children, onClose, title, titleId = 'modal-title' }) {
  const previousFocusRef = useRef<HTMLElement | null>(null);

  useEffect(() => {
    if (isOpen) {
      // Store the currently focused element
      previousFocusRef.current = document.activeElement as HTMLElement;
    } else if (previousFocusRef.current) {
      // Return focus when modal closes
      previousFocusRef.current.focus();
    }
  }, [isOpen]);

  useEffect(() => {
    const handleEscape = (e: KeyboardEvent) => {
      if (e.key === 'Escape') {
        onClose();
      }
    };

    if (isOpen) {
      document.addEventListener('keydown', handleEscape);
      return () => document.removeEventListener('keydown', handleEscape);
    }
  }, [isOpen, onClose]);

  if (!isOpen) return null;

  return (
    <div className="modal-overlay" onClick={onClose}>
      <FocusTrap>
        <div
          className="modal-content"
          role="dialog"
          aria-modal="true"
          aria-labelledby={titleId}
          onClick={(e) => e.stopPropagation()}
        >
          {children}
        </div>
      </FocusTrap>
    </div>
  );
}

• 2.1.2 No Keyboard Trap
• 2.4.3 Focus Order
• 4.1.2 Name, Role, Value

• Tab key cycles through modal content only
• Escape key closes modal
• Focus returns to trigger element on close
• Screen reader announces modal correctly
• Clicking overlay closes modal

• Added focus-trap-react dependency
• Modal now requires a title prop for aria-labelledby
• Clicking modal content no longer closes it