/* Ensure all interactive elements meet touch target minimums */
button,
a,
input[type="checkbox"],
input[type="radio"],
[role="button"],
[role="tab"],
[role="menuitem"] {
  min-height: 48px;
  min-width: 48px;
}

/* For small visual elements, use padding to expand touch area */
.icon-button {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  width: 24px;   /* visual size */
  height: 24px;
  padding: 12px;  /* expands to 48px touch target */
  box-sizing: content-box;
}

// components/ui/dialog.tsx
"use client";

import React, { useId, useEffect, useRef, useCallback } from "react";
import { createPortal } from "react-dom";

interface DialogProps {
  /** Whether the dialog is currently open */
  open: boolean;
  /** Called when the dialog should close (Escape key, backdrop click, close button) */
  onClose: () => void;
  /** Accessible title for the dialog — required */
  title: string;
  /** Optional description displayed below the title */
  description?: string;
  /** Dialog content */
  children: React.ReactNode;
}

export function Dialog({ open, onClose, title, description, children }: DialogProps) {
  const dialogRef = useRef<HTMLDivElement>(null);
  const previouslyFocusedRef = useRef<HTMLElement | null>(null);

  /* --------------------------------------------------
     FOCUS TRAP: Tab cycles within the dialog only.
     Shift+Tab from first element goes to last.
     Tab from last element goes to first.
     -------------------------------------------------- */
  const getFocusableElements = useCallback(() => {
    if (!dialogRef.current) return [];
    const selector = [
      "a[href]",
      "button:not([disabled])",
      "input:not([disabled])",
      "select:not([disabled])",
      "textarea:not([disabled])",
      "[tabindex]:not([tabindex='-1'])",
    ].join(", ");
    return Array.from(
      dialogRef.current.querySelectorAll<HTMLElement>(selector)
    );
  }, []);

  const handleKeyDown = useCallback(
    (e: KeyboardEvent) => {
      /* Close on Escape */
      if (e.key === "Escape") {
        e.preventDefault();
        onClose();
        return;
      }

      /* Trap focus on Tab */
      if (e.key === "Tab") {
        const focusable = getFocusableElements();
        if (focusable.length === 0) return;

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

        if (e.shiftKey && document.activeElement === first) {
          e.preventDefault();
          last.focus();
        } else if (!e.shiftKey && document.activeElement === last) {
          e.preventDefault();
          first.focus();
        }
      }
    },
    [onClose, getFocusableElements]
  );

  /* --------------------------------------------------
     On open: store previously focused element,
     move focus into the dialog.
     On close: restore focus to the trigger element.
     -------------------------------------------------- */
  useEffect(() => {
    if (open) {
      previouslyFocusedRef.current = document.activeElement as HTMLElement;
      document.addEventListener("keydown", handleKeyDown);

      // Focus the dialog container (or the first focusable element)
      requestAnimationFrame(() => {
        const focusable = getFocusableElements();
        if (focusable.length > 0) {
          focusable[0].focus();
        } else {
          dialogRef.current?.focus();
        }
      });

      // Prevent background scrolling
      document.body.style.overflow = "hidden";
    }

    return () => {
      document.removeEventListener("keydown", handleKeyDown);
      document.body.style.overflow = "";

      // Restore focus to the element that opened the dialog
      if (previouslyFocusedRef.current) {
        previouslyFocusedRef.current.focus();
      }
    };
  }, [open, handleKeyDown, getFocusableElements]);

  const id = useId();
  if (!open) return null;

  const titleId = `${id}-title`;
  const descriptionId = description ? `${id}-description` : undefined;

  return createPortal(
    <>
      {/* Backdrop — clicking it closes the dialog */}
      <div
        className="fixed inset-0 z-50 bg-black/50"
        aria-hidden="true"
        onClick={onClose}
      />

      {/* Dialog panel */}
      <div
        ref={dialogRef}
        role="dialog"
        aria-modal="true"
        aria-labelledby={titleId}
        aria-describedby={descriptionId}
        tabIndex={-1}
        className="fixed left-1/2 top-1/2 z-50 w-full max-w-lg -translate-x-1/2 -translate-y-1/2 rounded-lg bg-white p-6 shadow-xl"
      >
        {/* Title — required for screen readers */}
        <h2 id={titleId} className="text-lg font-semibold text-neutral-900">
          {title}
        </h2>

        {/* Description — optional */}
        {description && (
          <p id={descriptionId} className="mt-1 text-sm text-neutral-600">
            {description}
          </p>
        )}

        {/* Content */}
        <div className="mt-4">{children}</div>

        {/* Close button */}
        <button
          type="button"
          onClick={onClose}
          className="absolute right-4 top-4 rounded-sm p-1 text-neutral-400 hover:text-neutral-900 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-blue-500"
          aria-label="Close dialog"
        >
          <svg
            xmlns="http://www.w3.org/2000/svg"
            width="20"
            height="20"
            viewBox="0 0 24 24"
            fill="none"
            stroke="currentColor"
            strokeWidth="2"
            aria-hidden="true"
          >
            <path d="M18 6 6 18M6 6l12 12" />
          </svg>
        </button>
      </div>
    </>,
    document.body
  );
}

function DeleteConfirmation() {
  const [open, setOpen] = React.useState(false);

  return (
    <>
      <button onClick={() => setOpen(true)}>Delete account</button>

      <Dialog
        open={open}
        onClose={() => setOpen(false)}
        title="Delete account?"
        description="This action is permanent and cannot be undone."
      >
        <div className="flex justify-end gap-3 mt-6">
          <button onClick={() => setOpen(false)}>Cancel</button>
          <button onClick={handleDelete} className="bg-red-600 text-white rounded px-4 py-2">
            Yes, delete
          </button>
        </div>
      </Dialog>
    </>
  );
}

// components/contact-form.tsx
"use client";

import React, { useState, useRef } from "react";

interface FormErrors {
  name?: string;
  email?: string;
  message?: string;
}

export function ContactForm() {
  const [errors, setErrors] = useState<FormErrors>({});
  const [submitted, setSubmitted] = useState(false);
  const errorSummaryRef = useRef<HTMLDivElement>(null);
  const nameRef = useRef<HTMLInputElement>(null);
  const emailRef = useRef<HTMLInputElement>(null);
  const messageRef = useRef<HTMLTextAreaElement>(null);

  function validate(formData: FormData): FormErrors {
    const errs: FormErrors = {};
    if (!formData.get("name")) errs.name = "Name is required.";
    const email = formData.get("email") as string;
    if (!email) {
      errs.email = "Email is required.";
    } else if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
      errs.email = "Please enter a valid email address.";
    }
    if (!formData.get("message")) errs.message = "Message is required.";
    return errs;
  }

  function handleSubmit(e: React.FormEvent<HTMLFormElement>) {
    e.preventDefault();
    const formData = new FormData(e.currentTarget);
    const validationErrors = validate(formData);

    if (Object.keys(validationErrors).length > 0) {
      setErrors(validationErrors);
      setSubmitted(false);

      // Focus the error summary so screen readers announce it
      requestAnimationFrame(() => errorSummaryRef.current?.focus());

      return;
    }

    setErrors({});
    setSubmitted(true);
    // Submit to your API here
  }

  const hasErrors = Object.keys(errors).length > 0;

  return (
    <form onSubmit={handleSubmit} noValidate aria-label="Contact form">
      {/* -----------------------------------------------
          Error summary — announced to screen readers.
          Placed at the top of the form so keyboard users
          encounter it before the fields.
          ----------------------------------------------- */}
      {hasErrors && (
        <div
          ref={errorSummaryRef}
          role="alert"
          tabIndex={-1}
          className="mb-6 rounded-md border border-red-300 bg-red-50 p-4"
        >
          <h2 className="text-sm font-semibold text-red-800">
            Please fix the following errors:
          </h2>
          <ul className="mt-2 list-disc pl-5 text-sm text-red-700">
            {errors.name && (
              <li>
                <a href="#name" className="underline">
                  {errors.name}
                </a>
              </li>
            )}
            {errors.email && (
              <li>
                <a href="#email" className="underline">
                  {errors.email}
                </a>
              </li>
            )}
            {errors.message && (
              <li>
                <a href="#message" className="underline">
                  {errors.message}
                </a>
              </li>
            )}
          </ul>
        </div>
      )}

      {/* ---- Name field ---- */}
      <div className="mb-4">
        <label htmlFor="name" className="block text-sm font-medium text-neutral-900">
          Name <span aria-hidden="true">*</span>
        </label>
        <input
          ref={nameRef}
          id="name"
          name="name"
          type="text"
          required
          autoComplete="name"
          aria-required="true"
          aria-invalid={errors.name ? "true" : undefined}
          aria-describedby={errors.name ? "name-error" : undefined}
          className={`mt-1 block w-full rounded-md border px-3 py-2 text-sm ${
            errors.name
              ? "border-red-500 focus:ring-red-500"
              : "border-neutral-300 focus:ring-blue-500"
          } focus:outline-none focus:ring-2`}
        />
        {errors.name && (
          <p id="name-error" className="mt-1 text-sm text-red-600">
            {errors.name}
          </p>
        )}
      </div>

      {/* ---- Email field ---- */}
      <div className="mb-4">
        <label htmlFor="email" className="block text-sm font-medium text-neutral-900">
          Email <span aria-hidden="true">*</span>
        </label>
        <input
          ref={emailRef}
          id="email"
          name="email"
          type="email"
          required
          autoComplete="email"
          aria-required="true"
          aria-invalid={errors.email ? "true" : undefined}
          aria-describedby={errors.email ? "email-error email-hint" : "email-hint"}
          className={`mt-1 block w-full rounded-md border px-3 py-2 text-sm ${
            errors.email
              ? "border-red-500 focus:ring-red-500"
              : "border-neutral-300 focus:ring-blue-500"
          } focus:outline-none focus:ring-2`}
        />
        <p id="email-hint" className="mt-1 text-xs text-neutral-500">
          We will never share your email.
        </p>
        {errors.email && (
          <p id="email-error" className="mt-1 text-sm text-red-600">
            {errors.email}
          </p>
        )}
      </div>

      {/* ---- Message field ---- */}
      <div className="mb-6">
        <label htmlFor="message" className="block text-sm font-medium text-neutral-900">
          Message <span aria-hidden="true">*</span>
        </label>
        <textarea
          ref={messageRef}
          id="message"
          name="message"
          rows={4}
          required
          aria-required="true"
          aria-invalid={errors.message ? "true" : undefined}
          aria-describedby={errors.message ? "message-error" : undefined}
          className={`mt-1 block w-full rounded-md border px-3 py-2 text-sm ${
            errors.message
              ? "border-red-500 focus:ring-red-500"
              : "border-neutral-300 focus:ring-blue-500"
          } focus:outline-none focus:ring-2`}
        />
        {errors.message && (
          <p id="message-error" className="mt-1 text-sm text-red-600">
            {errors.message}
          </p>
        )}
      </div>

      {/* ---- Submit ---- */}
      <button
        type="submit"
        className="rounded-md bg-blue-600 px-4 py-2 text-sm font-medium text-white hover:bg-blue-700 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-blue-500 focus-visible:ring-offset-2"
      >
        Send message
      </button>

      {/* ---- Success announcement ---- */}
      {submitted && (
        <p className="mt-4 text-sm text-green-700" role="status" aria-live="polite">
          Your message has been sent successfully. We will respond within 24 hours.
        </p>
      )}
    </form>
  );
}

<!--
  Skip navigation allows keyboard and screen reader users to bypass
  repetitive navigation and jump directly to the main content.

  It should be the FIRST focusable element in the DOM.
  It is visually hidden until focused, then slides into view.
-->

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Accessible Page</title>
  <style>
    /* Skip link: visually hidden by default, visible on focus */
    .skip-link {
      position: absolute;
      top: -100%;
      left: 16px;
      z-index: 9999;
      padding: 8px 16px;
      background-color: #1e40af;
      color: #ffffff;
      font-size: 0.875rem;
      font-weight: 600;
      text-decoration: none;
      border-radius: 0 0 6px 6px;
      transition: top 0.2s ease;
    }

    .skip-link:focus {
      top: 0;
      outline: 2px solid #3b82f6;
      outline-offset: 2px;
    }
  </style>
</head>
<body>
  <!-- Skip link — first element in the DOM -->
  <a href="#main-content" class="skip-link">
    Skip to main content
  </a>

  <!-- Navigation -->
  <header>
    <nav aria-label="Primary navigation">
      <ul>
        <li><a href="/">Home</a></li>
        <li><a href="/about">About</a></li>
        <li><a href="/products">Products</a></li>
        <li><a href="/contact">Contact</a></li>
      </ul>
    </nav>
  </header>

  <!-- Main content — the skip link target -->
  <main id="main-content" tabindex="-1">
    <!--
      tabindex="-1" allows the element to receive focus programmatically
      (via the skip link) without being part of the natural tab order.
    -->
    <h1>Welcome to our accessible website</h1>
    <p>This content is immediately accessible via the skip link.</p>
  </main>

  <footer>
    <nav aria-label="Footer navigation">
      <ul>
        <li><a href="/privacy">Privacy Policy</a></li>
        <li><a href="/terms">Terms of Service</a></li>
      </ul>
    </nav>
  </footer>
</body>
</html>

## Accessibility Audit Checklist

### Perceivable
- [ ] All images have appropriate alt text (informative images described, decorative images have alt="")
- [ ] Video content has captions; audio content has transcripts
- [ ] Color contrast meets 4.5:1 for normal text and 3:1 for large text (WCAG 1.4.3)
- [ ] Information is not conveyed by color alone (WCAG 1.4.1)
- [ ] Text can be resized to 200% without loss of content or functionality (WCAG 1.4.4)
- [ ] Content reflows at 320px width without horizontal scrolling (WCAG 1.4.10)
- [ ] Non-text contrast: UI components and graphical objects meet 3:1 (WCAG 1.4.11)

### Operable
- [ ] All functionality is available via keyboard (WCAG 2.1.1)
- [ ] No keyboard traps — users can Tab into and out of every component (WCAG 2.1.2)
- [ ] Skip navigation link is present and functional (WCAG 2.4.1)
- [ ] Page has a descriptive <title> (WCAG 2.4.2)
- [ ] Focus order is logical and follows visual layout (WCAG 2.4.3)
- [ ] Link purpose is clear from the link text (no "click here") (WCAG 2.4.4)
- [ ] Focus indicator is visible on all interactive elements (WCAG 2.4.7)
- [ ] Touch targets are at least 24x24 CSS pixels (WCAG 2.5.8)
- [ ] Hover/focus content (tooltips, dropdowns) is dismissible, hoverable, and persistent (WCAG 1.4.13)

### Understandable
- [ ] Page language is set via <html lang="en"> (WCAG 3.1.1)
- [ ] Form inputs have visible, associated labels (WCAG 3.3.2)
- [ ] Error messages identify the field and describe the error (WCAG 3.3.1)
- [ ] Error suggestions are provided when possible (WCAG 3.3.3)
- [ ] No unexpected context changes on focus or input (WCAG 3.2.1, 3.2.2)
- [ ] Consistent navigation and identification across pages (WCAG 3.2.3, 3.2.4)

### Robust
- [ ] HTML validates without major errors (good practice; WCAG 4.1.1 was removed in WCAG 2.2)
- [ ] All interactive elements have accessible names (WCAG 4.1.2)
- [ ] ARIA roles, states, and properties are valid and complete (WCAG 4.1.2)
- [ ] Status messages are announced without receiving focus (WCAG 4.1.3)
- [ ] Custom widgets follow ARIA Authoring Practices patterns

### Screen Reader Testing
- [ ] Tested with VoiceOver (macOS/iOS) or NVDA/JAWS (Windows)
- [ ] Headings form a logical, sequential hierarchy
- [ ] Landmarks (main, nav, header, footer) are present and labeled
- [ ] Form fields announce their label, required state, and any errors
- [ ] Dynamic content updates are announced via live regions
- [ ] Modal dialogs announce their title and trap focus correctly

### Automated Testing
- [ ] axe-core or Lighthouse accessibility audit passes with 0 critical/serious issues
- [ ] ESLint eslint-plugin-jsx-a11y passes with 0 errors
- [ ] Pa11y or similar CI tool integrated into the build pipeline

// tests/accessibility.spec.ts
import { test, expect } from "@playwright/test";
import AxeBuilder from "@axe-core/playwright";

// Test every critical page for accessibility violations
const pages = [
  { name: "Home", path: "/" },
  { name: "Dashboard", path: "/dashboard" },
  { name: "Settings", path: "/settings" },
  { name: "Login", path: "/login" },
  { name: "Signup", path: "/signup" },
];

for (const page of pages) {
  test(`${page.name} page should have no accessibility violations`, async ({
    page: playwrightPage,
  }) => {
    await playwrightPage.goto(page.path);

    // Wait for page content to load
    await playwrightPage.waitForLoadState("networkidle");

    const results = await new AxeBuilder({ page: playwrightPage })
      .withTags(["wcag2a", "wcag2aa", "wcag22aa"]) // WCAG 2.2 AA
      .analyze();

    // Report violations with helpful output
    const violations = results.violations.map((v) => ({
      id: v.id,
      impact: v.impact,
      description: v.description,
      nodes: v.nodes.length,
      help: v.helpUrl,
    }));

    if (violations.length > 0) {
      console.table(violations);
    }

    expect(results.violations).toEqual([]);
  });

  // Test dark mode separately — contrast failures often differ
  test(`${page.name} page (dark mode) should have no a11y violations`, async ({
    page: playwrightPage,
  }) => {
    // Set dark mode preference
    await playwrightPage.emulateMedia({ colorScheme: "dark" });
    await playwrightPage.goto(page.path);
    await playwrightPage.waitForLoadState("networkidle");

    const results = await new AxeBuilder({ page: playwrightPage })
      .withTags(["wcag2a", "wcag2aa", "wcag22aa"])
      .analyze();

    expect(results.violations).toEqual([]);
  });
}

// Test specific interactive states
test("Modal dialog should be accessible when open", async ({ page }) => {
  await page.goto("/dashboard");
  await page.click('button:has-text("New project")');

  // Wait for modal to appear
  await page.waitForSelector('[role="dialog"]');

  const results = await new AxeBuilder({ page })
    .include('[role="dialog"]') // Scope to just the modal
    .withTags(["wcag2a", "wcag2aa"])
    .analyze();

  expect(results.violations).toEqual([]);
});

import { useState, useRef, useCallback } from "react";

type Tab = {
  id: string;
  label: string;
  content: React.ReactNode;
};

interface TabsProps {
  tabs: Tab[];
  defaultTab?: string;
  label: string; // Accessible label for the tablist
}

export function Tabs({ tabs, defaultTab, label }: TabsProps) {
  const [activeTab, setActiveTab] = useState(defaultTab || tabs[0]?.id);
  const tabRefs = useRef<Map<string, HTMLButtonElement>>(new Map());

  const setTabRef = useCallback(
    (id: string) => (el: HTMLButtonElement | null) => {
      if (el) tabRefs.current.set(id, el);
      else tabRefs.current.delete(id);
    },
    []
  );

  function handleKeyDown(e: React.KeyboardEvent) {
    const currentIndex = tabs.findIndex((t) => t.id === activeTab);
    let nextIndex: number | null = null;

    switch (e.key) {
      case "ArrowRight":
        nextIndex = (currentIndex + 1) % tabs.length;
        break;
      case "ArrowLeft":
        nextIndex = (currentIndex - 1 + tabs.length) % tabs.length;
        break;
      case "Home":
        nextIndex = 0;
        break;
      case "End":
        nextIndex = tabs.length - 1;
        break;
      default:
        return;
    }

    e.preventDefault();
    const nextTab = tabs[nextIndex];
    setActiveTab(nextTab.id);
    tabRefs.current.get(nextTab.id)?.focus();
  }

  return (
    <div>
      {/* Tab list */}
      <div
        role="tablist"
        aria-label={label}
        onKeyDown={handleKeyDown}
        className="tab-list"
      >
        {tabs.map((tab) => (
          <button
            key={tab.id}
            ref={setTabRef(tab.id)}
            role="tab"
            id={`tab-${tab.id}`}
            aria-selected={activeTab === tab.id}
            aria-controls={`panel-${tab.id}`}
            tabIndex={activeTab === tab.id ? 0 : -1}
            onClick={() => setActiveTab(tab.id)}
            className={`tab-button ${activeTab === tab.id ? "active" : ""}`}
          >
            {tab.label}
          </button>
        ))}
      </div>

      {/* Tab panels */}
      {tabs.map((tab) => (
        <div
          key={tab.id}
          role="tabpanel"
          id={`panel-${tab.id}`}
          aria-labelledby={`tab-${tab.id}`}
          hidden={activeTab !== tab.id}
          tabIndex={0}
          className="tab-panel"
        >
          {tab.content}
        </div>
      ))}
    </div>
  );
}

.tab-list {
  display: flex;
  gap: 0;
  border-bottom: 1px solid var(--color-border, #e2e8f0);
}

.tab-button {
  padding: 0.75rem 1rem;
  border: none;
  border-bottom: 2px solid transparent;
  background: transparent;
  color: var(--color-text-muted, #6b7280);
  font-size: 0.875rem;
  font-weight: 500;
  cursor: pointer;
  min-height: 44px;
  transition: color 150ms ease, border-color 150ms ease;
}

.tab-button:hover {
  color: var(--color-text, #1f2937);
}

.tab-button.active {
  color: var(--color-primary, #2563eb);
  border-bottom-color: var(--color-primary, #2563eb);
}

.tab-button:focus-visible {
  outline: 2px solid var(--color-primary, #2563eb);
  outline-offset: -2px;
  border-radius: 2px;
}

.tab-panel {
  padding: 1.5rem 0;
}

.tab-panel:focus-visible {
  outline: 2px solid var(--color-primary, #2563eb);
  outline-offset: 2px;
  border-radius: 4px;
}