The API is the UI.

// Inaccessible API response — client has to infer everything
{
  "temp": 71,
  "wind": 12,
  "dir": 270,
  "precip": 0.03
}

// Accessible API response — labeled, human-readable fields alongside raw data
{
  "temperature": {
    "value": 71,
    "unit": "fahrenheit",
    "label": "71 degrees Fahrenheit"
  },
  "wind": {
    "speed_mph": 12,
    "direction_degrees": 270,
    "label": "West wind at 12 miles per hour"
  },
  "precipitation": {
    "inches": 0.03,
    "label": "Light rain, 0.03 inches"
  },
  "summary": "Partly cloudy with a west wind at 12 mph. Temperature 71°F. Light rain possible.",
  "image": {
    "url": "https://example.com/icons/partly-cloudy.png",
    "alt": "Partly cloudy sky"
  }
}

// The NWS API at api.weather.gov follows this pattern:
// GET https://api.weather.gov/gridpoints/EWX/155,91/forecast
// Each period in the response includes:
// "detailedForecast": "Tonight: Partly cloudy. Low around 68. South wind 5 to 10 mph."
// That string requires zero post-processing to present to a VoiceOver user.

// API response: array of objects with consistent keys
const bands = [
  { band: "40m", freq: "7.0–7.3 MHz",    license: "General",    use: "Domestic + DX SSB, CW" },
  { band: "20m", freq: "14.0–14.35 MHz", license: "General",    use: "International DX" },
  { band: "10m", freq: "28.0–29.7 MHz",  license: "Technician", use: "SSB, FM, digital" }
];

// Render as an accessible HTML table
// caption describes the table's subject — required for screen reader context
// scope="col" associates each header cell with its column
function renderBandTable(bands) {
  return `
    <table>
      <caption>Amateur radio HF band plan</caption>
      <thead>
        <tr>
          <th scope="col">Band</th>
          <th scope="col">Frequency</th>
          <th scope="col">License</th>
          <th scope="col">Typical use</th>
        </tr>
      </thead>
      <tbody>
        ${bands.map(b => `
        <tr>
          <td>${b.band}</td>
          <td>${b.freq}</td>
          <td>${b.license}</td>
          <td>${b.use}</td>
        </tr>`).join('')}
      </tbody>
    </table>
  `;
}

// What NOT to do:
// <div class="table-row">          -- no semantic structure
// <span class="cell">20m</span>  -- VoiceOver reads cells with no column context
// CSS grid that looks like a table  -- completely opaque to screen readers

<!-- Live regions must exist in the DOM before content is injected.
     Create them on page load, empty. Inject text when events fire. -->

<!-- Polite: waits for the user to finish before announcing -->
<div id="status-region"
     role="status"
     aria-live="polite"
     aria-atomic="true"></div>

<!-- Assertive: interrupts whatever VoiceOver is currently reading -->
<div id="error-region"
     role="alert"
     aria-live="assertive"
     aria-atomic="true"></div>

<script>
  // Wrap announcements in a utility — every async operation uses the same channel
  function announce(message, type = 'polite') {
    const region = type === 'assertive'
      ? document.getElementById('error-region')
      : document.getElementById('status-region');

    // Clear then set — ensures re-announcement even if the message is identical
    region.textContent = '';
    requestAnimationFrame(() => {
      region.textContent = message;
    });
  }

  // Use wherever async state changes happen
  async function fetchForecast(lat, lon) {
    announce('Loading forecast...');
    try {
      const res = await fetch(`/api/forecast?lat=${lat}&lon=${lon}`);
      const data = await res.json();
      announce(`Forecast loaded. ${data.summary}`);
      renderForecast(data);
    } catch (err) {
      announce('Forecast failed to load. Please try again.', 'assertive');
    }
  }

  // Background polling: announce only meaningful state transitions
  // Don't announce every poll tick — only when status actually changes
  let lastStatus = null;
  function pollRadioStatus() {
    setInterval(async () => {
      const status = await fetchRadioStatus();
      if (status !== lastStatus) {
        announce(`Radio status: ${status}`);
        lastStatus = status;
      }
    }, 5000);
  }
</script>

// --- Using axe-core to audit the AX tree programmatically ---
// axe-core is the engine behind many accessibility testing tools.
// It queries the accessibility tree and reports violations.

// Install: npm install axe-core
import axe from 'axe-core';

async function auditPage() {
  const results = await axe.run();

  // violations: things that are definitely broken
  results.violations.forEach(violation => {
    console.error(`[${violation.impact}] ${violation.description}`);
    violation.nodes.forEach(node => {
      console.error('  Failing element:', node.html);
      console.error('  Fix:', node.failureSummary);
    });
  });

  // incomplete: things axe couldn't auto-determine — need human review
  // These are often the most important — color contrast, label sufficiency
  results.incomplete.forEach(item => {
    console.warn(`[needs review] ${item.description}`);
  });
}

// --- CI integration with Playwright ---
// Fail a build if accessibility regressions are introduced.

import { test, expect } from '@playwright/test';
import AxeBuilder from '@axe-core/playwright';

test('forecast table is accessible', async ({ page }) => {
  await page.goto('/forecast');
  const results = await new AxeBuilder({ page })
    .include('#forecast-table')
    .analyze();
  expect(results.violations).toHaveLength(0);
});

// --- Quick checks in the Chrome DevTools console ---
// These mirror exactly what VoiceOver reads:
// document.querySelector('button').computedRole  // e.g. "button"
// document.querySelector('button').computedName  // e.g. "Submit form"
// If computedName is "" — the element has no accessible name.
// That is an accessibility failure, not a warning.

<!-- Chart component structure -->
<figure aria-labelledby="chart-caption">

  <figcaption id="chart-caption">
    Monthly precipitation — Austin TX, January–June 2024
  </figcaption>

  <!-- Visual chart: aria-hidden removes the blank canvas from the AX tree -->
  <canvas
    aria-hidden="true"
    id="precip-chart"
    width="600"
    height="300">
  </canvas>

  <!-- Accessible data table: sr-only hides it visually, keeps it in the AX tree -->
  <table class="sr-only">
    <caption>Monthly precipitation data — Austin TX, January–June 2024</caption>
    <thead>
      <tr>
        <th scope="col">Month</th>
        <th scope="col">Precipitation (inches)</th>
      </tr>
    </thead>
    <tbody id="chart-data-table">
      <!-- Populated from the same data array used to render the chart -->
    </tbody>
  </table>

</figure>

<script>
  // Single data source for both the chart and the accessible table
  const precipData = [
    { month: "January",  inches: 1.84 },
    { month: "February", inches: 2.12 },
    { month: "March",    inches: 1.96 },
    { month: "April",    inches: 2.89 },
    { month: "May",      inches: 4.10 },
    { month: "June",     inches: 3.22 }
  ];

  // Populate both the accessible table and the visual chart from the same array
  const tbody = document.getElementById('chart-data-table');
  precipData.forEach(point => {
    const row = document.createElement('tr');
    row.innerHTML = `
      <td>${point.month}</td>
      <td>${point.inches} inches</td>
    `;
    tbody.appendChild(row);
  });

  renderChart('precip-chart', precipData);
</script>

<style>
  /* sr-only: removes from visual flow, keeps in AX tree */
  /* Do NOT use display:none — that removes it from the AX tree entirely */
  .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;
  }
</style>