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';

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

/**
 * Accessible Modal Dialog (W3C ARIA APG Compliant)
 * Uses native HTMLDialogElement with .showModal() to guarantee:
 * 1. Native inert background (blocks screen reader and click bleed-through).
 * 2. Native keyboard focus trap (strictly keeps Tab cycles within dialog).
 * 3. Native Escape key cancellation and focus restoration to trigger element.
 */
export function AccessibleModal({ isOpen, onClose, titleId, children }: AccessibleModalProps) {
  const dialogRef = useRef<HTMLDialogElement>(null);

  useEffect(() => {
    const dialog = dialogRef.current;
    if (!dialog) return;

    if (isOpen) {
      if (!dialog.open) {
        dialog.showModal();
      }
    } else {
      if (dialog.open) {
        dialog.close();
      }
    }
  }, [isOpen]);

  return (
    <dialog
      ref={dialogRef}
      aria-labelledby={titleId}
      onCancel={(e) => {
        e.preventDefault();
        onClose();
      }}
      className="w-full max-w-lg rounded-xl bg-background p-6 shadow-2xl border backdrop:bg-black/60 outline-none"
    >
      {children}
    </dialog>
  );
}