[test] Add demo-based axe-core accessibility tests for mui-material

.circleci/config.yml

@@ -267,6 +267,9 @@ jobs:
       - run:
           name: Run visual regression tests
           command: xvfb-run pnpm test:regressions
+      - run:
+          name: A11y results committed?
+          command: git add -A && git diff --exit-code --staged
       - run:
           name: Build packages for fixtures
           command: pnpm release:build

AGENTS.md

@@ -153,6 +153,46 @@ describe('Button', () => {
 });
 ```
 
+### Accessibility Testing
+
+axe-core runs inside the visual-regression Playwright loop (`test/regressions/index.test.js`) — no separate browser session. Screenshots and a11y are independent: a demo can opt out of one and still run the other.
+
+Key files:
+
+- `test/regressions/demoMeta.ts` — `SCREENSHOT_RULES` and `A11Y_RULES` arrays, matched last-wins (no inheritance: overrides restate every field) against `docs/data/material/components/{slug}/{Demo}` (minimatch globs).
+- `test/regressions/a11y/axe.ts` — asserts `color-contrast` and `link-in-text-block` unless listed in `skipAssertions`.
+- `test/regressions/a11y/a11yReporter.ts` — writes one file per slug at `docs/data/material/components/{slug}/{slug}.a11y.json`, an object keyed by demo name.
+
+Enroll a component (slug-wide, or narrow with brace-glob):
+
+```ts
+// test/regressions/demoMeta.ts
+{ test: 'docs/data/material/components/alert/*', enabled: true, skipAssertions: ['color-contrast'] },
+{ test: 'docs/data/material/components/buttons/{BasicButtons,ColorButtons}', enabled: true },
+```
+
+Override a specific demo: append a per-demo rule _after_ the slug-wide rule (last-match-wins; the override must restate every field it wants):
+
+```ts
+{ test: 'docs/data/material/components/popover/AnchorPlayground', enabled: false }, // Redux isolation
+```
+
+Run `pnpm test:regressions` to refresh the `*.a11y.json` files. CI fails if any are stale.
+
+For local iteration, scope the run with vitest's `-t` test-name filter (matched against the `it()` strings, which contain the route). Non-matching tests are skipped — their bodies don't execute, so the browser never navigates to those routes.
+
+```bash
+# in one terminal
+pnpm test:regressions:server
+
+# in another — note no `--`, pnpm forwards args directly
+pnpm test:regressions:run -t '/docs-components-buttons/'              # one slug
+pnpm test:regressions:run -t '/docs-components-buttons/BasicButtons$' # one demo
+pnpm test:regressions:run -t '/docs-components-(buttons|chips)/'      # multiple slugs
+```
+
+Filtered runs only refresh the matched slugs' `*.a11y.json`. Run the unfiltered `pnpm test:regressions` before pushing.
+
 ### Imports
 
 Use one-level deep imports to avoid bundling entire packages:

docs/data/material/components/buttons/buttons.a11y.json

@@ -0,0 +1,56 @@
+{
+  "BasicButtons": {
+    "passedRules": [
+      "aria-allowed-attr",
+      "aria-conditional-attr",
+      "aria-prohibited-attr",
+      "aria-valid-attr",
+      "aria-valid-attr-value",
+      "button-name",
+      "color-contrast",
+      "nested-interactive",
+      "target-size"
+    ],
+    "failedRules": [],
+    "testedRules": {
+      "wcag2a": [
+        "aria-allowed-attr",
+        "aria-conditional-attr",
+        "aria-prohibited-attr",
+        "aria-valid-attr-value",
+        "aria-valid-attr",
+        "button-name",
+        "nested-interactive"
+      ],
+      "wcag2aa": ["color-contrast"],
+      "wcag22aa": ["target-size"]
+    }
+  },
+  "ColorButtons": {
+    "passedRules": [
+      "aria-allowed-attr",
+      "aria-conditional-attr",
+      "aria-prohibited-attr",
+      "aria-valid-attr",
+      "aria-valid-attr-value",
+      "button-name",
+      "color-contrast",
+      "nested-interactive",
+      "target-size"
+    ],
+    "failedRules": [],
+    "testedRules": {
+      "wcag2a": [
+        "aria-allowed-attr",
+        "aria-conditional-attr",
+        "aria-prohibited-attr",
+        "aria-valid-attr-value",
+        "aria-valid-attr",
+        "button-name",
+        "nested-interactive"
+      ],
+      "wcag2aa": ["color-contrast"],
+      "wcag22aa": ["target-size"]
+    }
+  }
+}

package.json

@@ -57,7 +57,7 @@
     "test:e2e:dev": "pnpm -F ./test/e2e dev",
     "test:e2e-website": "playwright test test/e2e-website --config test/e2e-website/playwright.config.ts",
     "test:e2e-website:dev": "cross-env PLAYWRIGHT_TEST_BASE_URL=http://localhost:3000 playwright test test/e2e-website --config test/e2e-website/playwright.config.ts",
-    "test:regressions": "cross-env NODE_ENV=production pnpm test:regressions:build && concurrently --success first --kill-others \"pnpm test:regressions:run\" \"pnpm test:regressions:server\"",
+    "test:regressions": "cross-env NODE_ENV=production pnpm test:regressions:build && concurrently --success first --kill-others \"pnpm test:regressions:run\" \"pnpm test:regressions:server\" && prettier --write \"docs/data/material/components/**/*.a11y.json\"",
     "test:regressions:build": "vite build test/regressions",
     "test:regressions:dev": "vite test/regressions --port 5001",
     "test:regressions:run": "vitest run -r ./test/regressions/",
@@ -112,6 +112,7 @@
     "@vitejs/plugin-react": "^5.1.1",
     "@vitest/browser-playwright": "^4.0.13",
     "@vitest/coverage-v8": "^4.0.13",
+    "axe-core": "4.11.1",
     "babel-plugin-istanbul": "7.0.1",
     "babel-plugin-module-resolver": "5.0.3",
     "chalk": "5.6.2",
@@ -128,6 +129,7 @@
     "jsdom": "26.1.0",
     "lerna": "9.0.7",
     "markdownlint-cli2": "0.22.1",
+    "minimatch": "10.2.4",
     "nx": "20.8.4",
     "pkg-pr-new": "0.0.66",
     "playwright": "1.59.1",