Screen Reader Announcement Components
├── Role → What it is ("button", "checkbox", "tab")
├── Name → What it's called ("Submit", "Dark mode", "Settings")
├── State → Current condition ("expanded", "checked", "selected")
└── Value → Current value ("3 of 5", "50%")

Example: "Submit, button"
Example: "Dark mode, switch, on"
Example: "Volume, slider, 75%"

// Tabs pattern
<div role="tablist" aria-label="Account settings">
  <button role="tab" aria-selected={activeTab === 'profile'} aria-controls="panel-profile"
    id="tab-profile" onClick={() => setActiveTab('profile')}>
    Profile
  </button>
  <button role="tab" aria-selected={activeTab === 'security'} aria-controls="panel-security"
    id="tab-security" onClick={() => setActiveTab('security')}>
    Security
  </button>
</div>

<div role="tabpanel" id="panel-profile" aria-labelledby="tab-profile"
  hidden={activeTab !== 'profile'}>
  Profile settings content
</div>
<div role="tabpanel" id="panel-security" aria-labelledby="tab-security"
  hidden={activeTab !== 'security'}>
  Security settings content
</div>

// Expandable section
<button
  aria-expanded={isOpen}
  aria-controls="section-content"
  onClick={() => setIsOpen(!isOpen)}
>
  {isOpen ? 'Collapse' : 'Expand'} Section
</button>
<div id="section-content" hidden={!isOpen}>
  Expandable content here
</div>

// Toggle switch
<button
  role="switch"
  aria-checked={isDarkMode}
  onClick={() => setIsDarkMode(!isDarkMode)}
>
  Dark Mode
</button>

// Disabled state
<button aria-disabled="true" onClick={(e) => {
  // aria-disabled doesn't prevent click, so guard it
  if (isSubmitting) return;
  handleSubmit();
}}>
  {isSubmitting ? 'Submitting...' : 'Submit'}
</button>

// 1. aria-label — when no visible label exists
<button aria-label="Close">
  <XIcon />
</button>

// 2. aria-labelledby — reference visible text
<h2 id="billing-heading">Billing Address</h2>
<form aria-labelledby="billing-heading">
  {/* form fields */}
</form>

// 3. aria-labelledby with multiple sources
<div role="dialog" aria-labelledby="dialog-title dialog-subtitle">
  <h2 id="dialog-title">Confirm Deletion</h2>
  <p id="dialog-subtitle">This action cannot be undone</p>
</div>

// 4. aria-describedby — supplementary description
<label htmlFor="password">Password</label>
<input id="password" type="password" aria-describedby="password-help" />
<p id="password-help">Must be at least 8 characters with one number.</p>

// Status message — polite announcement
function SearchResults({ count }: { count: number }) {
  return (
    <div role="status" aria-live="polite">
      {count} results found
    </div>
  );
}

// Error alert — assertive announcement
function FormError({ message }: { message: string }) {
  return (
    <div role="alert">
      {message}
    </div>
  );
}

// Toast notification system
function ToastContainer({ toasts }: { toasts: Toast[] }) {
  return (
    <div aria-live="polite" aria-relevant="additions">
      {toasts.map((toast) => (
        <div key={toast.id} role="status">
          {toast.message}
        </div>
      ))}
    </div>
  );
}

// Loading state with aria-busy
function DataTable({ isLoading, data }: DataTableProps) {
  return (
    <div aria-busy={isLoading} aria-live="polite">
      {isLoading ? (
        <p>Loading data...</p>
      ) : (
        <table>{/* table content */}</table>
      )}
    </div>
  );
}

/* Visually hidden but accessible to screen readers */
.sr-only {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  margin: -1px;
  overflow: hidden;
  clip: rect(0, 0, 0, 0);
  white-space: nowrap;
  border: 0;
}

// Decorative icon — hide from screen readers
<button>
  <SearchIcon aria-hidden="true" />
  Search
</button>

// Icon-only button — provide text for screen readers
<button aria-label="Search">
  <SearchIcon aria-hidden="true" />
</button>

// Visually hidden text for additional context
<a href="/blog">
  Read more<span className="sr-only"> about accessibility testing</span>
</a>

function Disclosure({ title, children }: DisclosureProps) {
  const [isOpen, setIsOpen] = useState(false);
  const contentId = useId();

  return (
    <div>
      <button
        aria-expanded={isOpen}
        aria-controls={contentId}
        onClick={() => setIsOpen(!isOpen)}
      >
        {title}
      </button>
      <div id={contentId} hidden={!isOpen}>
        {children}
      </div>
    </div>
  );
}

function Combobox({ options, onSelect }: ComboboxProps) {
  const [query, setQuery] = useState('');
  const [isOpen, setIsOpen] = useState(false);
  const [activeIndex, setActiveIndex] = useState(-1);
  const listboxId = useId();

  const filtered = options.filter((o) =>
    o.label.toLowerCase().includes(query.toLowerCase())
  );

  return (
    <div>
      <input
        role="combobox"
        aria-expanded={isOpen}
        aria-controls={listboxId}
        aria-activedescendant={activeIndex >= 0 ? `option-${activeIndex}` : undefined}
        aria-autocomplete="list"
        value={query}
        onChange={(e) => {
          setQuery(e.target.value);
          setIsOpen(true);
        }}
        onKeyDown={(e) => {
          if (e.key === 'ArrowDown') {
            setActiveIndex((i) => Math.min(i + 1, filtered.length - 1));
          } else if (e.key === 'ArrowUp') {
            setActiveIndex((i) => Math.max(i - 1, 0));
          } else if (e.key === 'Enter' && activeIndex >= 0) {
            onSelect(filtered[activeIndex]);
            setIsOpen(false);
          } else if (e.key === 'Escape') {
            setIsOpen(false);
          }
        }}
      />
      {isOpen && (
        <ul role="listbox" id={listboxId}>
          {filtered.map((option, index) => (
            <li
              key={option.value}
              role="option"
              id={`option-${index}`}
              aria-selected={index === activeIndex}
              onClick={() => {
                onSelect(option);
                setIsOpen(false);
              }}
            >
              {option.label}
            </li>
          ))}
        </ul>
      )}
    </div>
  );
}