web-accessibility

Skill: Web Accessibility

Web Accessibility & Interface Guidelines

Overview

Enforces universal accessibility compliance (WCAG 2.1 AA / AAA), rigorous semantic markup, keyboard navigability with focus traps, screen reader live regions, and Web Interface Guidelines standards.

When to Use

Activate whenever building, styling, or reviewing user interfaces, forms, modals, menus, navigation drawers, custom interactive widgets, or media elements.

Negative Constraints (What NOT to Do)

1. NEVER use outline: none without a custom :focus-visible replacement: Keyboard users must always have a distinct, high-contrast visual focus ring.
2. NEVER use non-semantic elements (<div onClick>) for interactive triggers: Always use native <button> or <a href>.
3. NEVER create modals or dialogs without keyboard focus traps: Focus must remain trapped inside open dialogs during Tab / Shift-Tab navigation and restore to trigger on close.
4. NEVER rely exclusively on color to indicate state or errors: Always pair colors with text labels, icons, or ARIA attributes (aria-invalid="true").
5. NEVER trap screen readers with missing form labels or error associations: Every input must link to <label htmlFor="id"> and errors via aria-describedby.
6. NEVER play animations without honoring prefers-reduced-motion: Respect user OS motion reduction preferences.

Rules & Patterns

1. Focus Visible & High-Contrast Focus Rings

button:focus-visible,
a:focus-visible,
input:focus-visible {
  outline: 2px solid #6366f1;
  outline-offset: 2px;
  border-radius: 4px;
}

button:focus:not(:focus-visible) {
  outline: none;
}

2. Accessible Modal & Focus Trap Contract

import React, { useEffect, useRef } from 'react';
import { createPortal } from 'react-dom';

interface ModalProps {
  isOpen: boolean;
  onClose: () => void;
  titleId: string;
  children: React.ReactNode;
}

export function AccessibleModal({ isOpen, onClose, titleId, children }: ModalProps) {
  const dialogRef = useRef<HTMLDivElement>(null);
  const triggerRef = useRef<HTMLElement | null>(null);

  useEffect(() => {
    if (!isOpen) return;
    triggerRef.current = document.activeElement as HTMLElement;

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

      if (e.key === 'Tab') {
        const focusables = dialogRef.current?.querySelectorAll<HTMLElement>(
          'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
        ) || [];
        if (!focusables.length) return;

        const first = focusables[0];
        const last = focusables[focusables.length - 1];

        if (e.shiftKey && document.activeElement === first) {
          e.preventDefault();
          last.focus();
        } else if (!e.shiftKey && document.activeElement === last) {
          e.preventDefault();
          first.focus();
        }
      }
    };

    document.addEventListener('keydown', handleKeyDown);
    return () => {
      document.removeEventListener('keydown', handleKeyDown);
      triggerRef.current?.focus();
    };
  }, [isOpen, onClose]);

  if (!isOpen) return null;

  return createPortal(
    <div className="fixed inset-0 z-50 flex items-center justify-center bg-black/60 p-4">
      <div 
        ref={dialogRef}
        role="dialog"
        aria-modal="true"
        aria-labelledby={titleId}
        className="w-full max-w-lg rounded-xl bg-background p-6 shadow-2xl border"
      >
        {children}
      </div>
    </div>,
    document.body
  );
}