// ❌ Broken — two <nav> elements with identical role "navigation" and no distinguishing name
// NVDA announces "navigation" for both; VoiceOver lists two items both called "navigation"
function Layout() {
  return (
    <>
      <nav>
        <a href="/dashboard">Dashboard</a>
      </nav>
      <nav>
        <a href="/profile">Profile</a>
      </nav>
    </>
  );
}

// ✅ aria-label differentiates landmark regions in the AT rotor
function Layout() {
  return (
    <>
      <nav aria-label="Global navigation">
        <a href="/dashboard">Dashboard</a>
      </nav>
      <nav aria-label="User account">
        <a href="/profile">Profile</a>
      </nav>
    </>
  );
}
// VoiceOver Landmarks Rotor now shows:
// "navigation, Global navigation"
// "navigation, User account"

// ❌ Icon button — AX name is empty; screen reader announces "button"
<button>
  <svg aria-hidden="false">...</svg>
</button>

// ❌ Icon button with tooltip — tooltip is not the AX name unless linked
<button title="Close">
  <svg>...</svg>
</button>
// title is used as fallback name by AccName — BUT tooltips are invisible to
// keyboard users on many platforms. title alone is not sufficient.

// ✅ Correct — aria-label provides name; svg hidden from AX tree
<button type="button" aria-label="Close dialog">
  <svg aria-hidden="true" focusable="false">...</svg>
</button>

// ✅ Alternative — visually hidden text is flat-traversed by AccName
<button type="button">
  <svg aria-hidden="true" focusable="false">...</svg>
  <span className="sr-only">Close dialog</span>
</button>

// ❌ Visual label proximity does not create programmatic association
<p>First name</p>
<input type="text" />
// Screen reader announces: "Edit text, blank" — no association

// ❌ Wrapping without htmlFor — works for mouse click but is unreliable in some AT
// (forLabel + input must be within the same label element)
<label>
  First name
  <input type="text" />
</label>
// Implicit association — works in most AT but explicit is preferred

// ✅ Explicit association — gold standard; works across all AT
<label htmlFor="first-name">First name</label>
<input id="first-name" type="text" />
// Screen reader announces: "First name, edit text"

// ✅ react — useId prevents SSR hydration mismatches from duplicate IDs
function FirstNameField() {
  const id = useId(); // generates deterministic :r0: style ID
  return (
    <div>
      <label htmlFor={id}>First name</label>
      <input id={id} type="text" autoComplete="given-name" />
    </div>
  );
}

// ✅ The correct sr-only utility class — visually hidden, AT-visible, focusable
// (follows Bootstrap / Tailwind CSS pattern, verified across all AT)
const srOnlyStyles: CSSProperties = {
  position: 'absolute',
  width: '1px',
  height: '1px',
  padding: '0',
  margin: '-1px',
  overflow: 'hidden',
  clip: 'rect(0,0,0,0)',
  whiteSpace: 'nowrap',
  borderWidth: '0',
};

// ❌ CRITICAL BUG — aria-hidden on an element that contains focused children
// A screen reader user can tab into the hidden region; AT announces nothing.
// Focus disappears silently — the most disorienting AT experience possible.
function Layout() {
  const isOpen = false;
  return (
    <div aria-hidden={!isOpen}>
      <button>Submit</button>  {/* Keyboard-focusable but AT-invisible */}
    </div>
  );
}

// ✅ Correct: remove interactive elements from tab order when aria-hidden
function Layout() {
  const isOpen = false;
  return (
    <div aria-hidden={!isOpen} inert={!isOpen}>
      {/* inert removes both from tab order AND from AXTree */}
      <button>Submit</button>
    </div>
  );
}

<nav aria-label="Global navigation">
  <ul>
    <li><a href="/dashboard" aria-current="page">Dashboard</a></li>
    <li><a href="/workspace">Workspace</a></li>
    <li><a href="/analytics">Analytics</a></li>
  </ul>
</nav>

// ✅ Active nav link with aria-current in React
interface NavLinkProps {
  href: string;
  children: ReactNode;
  currentPath: string;
}

function NavLink({ href, children, currentPath }: NavLinkProps) {
  const isCurrent = href === currentPath;
  return (
    <a
      href={href}
      aria-current={isCurrent ? 'page' : undefined}
      className={isCurrent ? 'nav-link active' : 'nav-link'}
    >
      {children}
    </a>
  );
}

// ❌ Counter-based IDs — hydration mismatch when SSR mount order differs from client
let counter = 0;
function useAccessibleId() {
  return useRef(`field-${++counter}`).current; // Different values server vs client
}

// ❌ Math.random() — completely different every render (also SSR-broken)
function Field() {
  const id = useState(() => `field-${Math.random()}`)[0];
  // Server: "field-0.4892..."  Client: "field-0.8123..." → hydration mismatch
}

// ✅ React 18 useId() — deterministic, SSR-safe, collision-free
function DescribedField({ helpText }: { helpText: string }) {
  const inputId = useId();
  const descId = useId();
  return (
    <div>
      <label htmlFor={inputId}>Workspace name</label>
      <input
        id={inputId}
        type="text"
        aria-describedby={descId}
      />
      <p id={descId} className="field-hint">
        {helpText}
      </p>
    </div>
  );
}