chore(a11y): add automated axe-core accessibility CI workflow

.github/workflows/accessibility.yml

@@ -0,0 +1,33 @@
+name: Accessibility check
+on:
+  push:
+    branches:
+      - master
+      - main
+  pull_request:
+    branches:
+      - master
+      - main
+
+jobs:
+  axe:
+    name: axe-core (WCAG 2.x A/AA)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout the latest commit
+        uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10
+      - name: Install dependencies
+        run: npm install
+      - name: Run accessibility tests
+        run: |
+          npx start-server-and-test start http://localhost:3000 "cypress run --spec cypress/e2e/accessibility/accessibility.cy.js"
+      - name: Upload failure screenshots
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: accessibility-failure-screenshots
+          path: cypress/screenshots/accessibility/accessibility.cy.js
+          if-no-files-found: ignore

cypress.config.js

@@ -8,7 +8,14 @@ module.exports = defineConfig({
     supportFile: false,
     baseUrl: 'http://localhost:3000/',
     setupNodeEvents(on, config) {
-      // implement node event listeners here
+      on('task', {
+        // Lets cypress-axe violation summaries print to the CI log, since
+        // cy.log output isn't captured in `cypress run` terminal output.
+        log(message) {
+          console.log(message);
+          return null;
+        },
+      });
     },
   },
 });

cypress/e2e/accessibility/accessibility.cy.js

@@ -0,0 +1,50 @@
+import 'cypress-axe';
+
+// One representative page per distinct template/component mix, rather than a
+// full-site crawl: this keeps the check fast in CI while still exercising
+// every reusable pattern (nav + prose, deprecated-content styling, migration
+// tables, the interactive release-notes filter/collapse widgets).
+const PAGES = [
+  { path: '/', label: 'home / docs index' },
+  { path: '/dashboard/security/users', label: 'dashboard doc page' },
+  { path: '/framework/deprecated/pubsub', label: 'deprecated framework doc page' },
+  { path: '/support/migrate-v5-to-v6', label: 'migration guide (tables + admonitions)' },
+  { path: '/support/release-notes', label: 'release notes (version filter + collapsible sections)' },
+];
+
+// axe-core rule tags to run: WCAG 2.0/2.1/2.2 Level A + AA, which includes
+// contrast, ARIA, labeling, heading order, and the 2.2 "target-size" (touch
+// target) rule.
+const RUN_TAGS = ['wcag2a', 'wcag2aa', 'wcag21aa', 'wcag22aa'];
+
+// Only fail the build for violations a real user would actually hit.
+const INCLUDED_IMPACTS = ['critical', 'serious'];
+
+function logViolations(violations) {
+  cy.task(
+    'log',
+    `${violations.length} accessibility violation${violations.length === 1 ? '' : 's'} detected:`,
+  );
+  const summary = violations.map(({ id, impact, description, helpUrl, nodes }) => ({
+    id,
+    impact,
+    description,
+    helpUrl,
+    affectedElements: nodes.map((n) => n.target.join(' ')),
+  }));
+  cy.task('log', JSON.stringify(summary, null, 2));
+}
+
+describe('Accessibility (axe-core)', () => {
+  PAGES.forEach(({ path, label }) => {
+    it(`has no critical/serious violations on ${label} (${path})`, () => {
+      cy.visit(path);
+      cy.injectAxe();
+      cy.checkA11y(
+        null,
+        { runOnly: { type: 'tag', values: RUN_TAGS }, includedImpacts: INCLUDED_IMPACTS },
+        logViolations,
+      );
+    });
+  });
+});

package.json

@@ -13,7 +13,7 @@
     "write-translations": "docusaurus write-translations",
     "write-heading-ids": "docusaurus write-heading-ids",
     "cy:open": "cypress open",
-    "cy:run": "cypress run",
+    "cy:run": "cypress run --spec \"cypress/e2e/*.cy.js\"",
     "test": "start-server-and-test start http://localhost:3000 cy:run",
     "index:push": "pwsh scripts/refresh-search-index.ps1",
     "issue-templates:sync-versions": "pwsh scripts/update-issue-template-versions.ps1"
@@ -54,11 +54,13 @@
     "@docusaurus/module-type-aliases": "3.10.2",
     "@docusaurus/plugin-content-docs": "3.10.2",
     "@docusaurus/types": "3.10.2",
+    "axe-core": "^4.12.1",
     "cypress": "^15.13.1",
+    "cypress-axe": "^1.7.0",
     "dotenv": "^17.4.2",
     "start-server-and-test": "^2.1.5"
   },
   "engines": {
     "node": ">=20.0"
   }
-}
+}