PIE-534 deepen a11y scenario coverage

Add broader per-element Axe scenarios, reusable accessibility checks, and tracking docs so accessibility findings can be triaged consistently across the PIE catalog.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: chillenious

.cursor/rules/a11y-scenario-suite.mdc

@@ -0,0 +1,14 @@
+---
+description: Guidance for maintaining the PIE accessibility scenario suite
+globs: apps/element-demo/src/lib/a11y/**, apps/element-demo/test/a11y/**, apps/element-demo/src/lib/samples/**, docs/a11y/**
+alwaysApply: false
+---
+
+# Accessibility Scenario Suite
+
+- Treat WCAG 2.2 Level AA as the target when adding or reviewing PIE element accessibility scenarios.
+- Use `.claude/skills/accessibility-reviewer-assessments/SKILL.md` for the detailed assessment-specific checklist.
+- Prefer dedicated a11y scenarios in `apps/element-demo/src/lib/a11y/scenarios/catalog.ts` over broad demo inventory coverage.
+- Keep automated scope explicit: document Axe-covered checks, custom Playwright checks, manual-only concerns, and unclear gaps in `docs/a11y/`.
+- Add reusable checks in `apps/element-demo/test/a11y/axe-scenarios.spec.ts` only when the concern applies across multiple elements.
+- Do not edit synced outputs in `packages/elements-react/*` or `packages/lib-react/*`; fix upstream first or document the issue for follow-up.

apps/element-demo/src/lib/a11y/scenarios/catalog.ts

@@ -18,8 +18,11 @@ export type A11yConcern =
 
 export type A11yAutomatedCheck =
   | 'axe'
+  | 'group-label'
   | 'interactive-control-name'
   | 'keyboard-tab-reach'
+  | 'math-alternative'
+  | 'media-alternative'
   | 'target-size'
   | 'status-message';
 

apps/element-demo/src/lib/a11y/scenarios/types.ts

@@ -202,10 +202,16 @@ async function runScenarioChecks(
   const results: CheckResult[] = [];
 
   for (const check of checks) {
-    if (check === 'interactive-control-name') {
+    if (check === 'group-label') {
+      results.push(await checkGroupLabels(page));
+    } else if (check === 'interactive-control-name') {
       results.push(await checkInteractiveControlNames(page));
     } else if (check === 'keyboard-tab-reach') {
       results.push(await checkKeyboardTabReach(page));
+    } else if (check === 'math-alternative') {
+      results.push(await checkMathAlternatives(page));
+    } else if (check === 'media-alternative') {
+      results.push(await checkMediaAlternatives(page));
     } else if (check === 'target-size') {
       results.push(await checkTargetSize(page));
     } else if (check === 'status-message') {
@@ -216,6 +222,73 @@ async function runScenarioChecks(
   return results;
 }
 
+async function checkGroupLabels(page: Page): Promise<CheckResult> {
+  const details = await page.locator('[data-testid="a11y-scan-subject"]').evaluate((subject) => {
+    const groupSelector = [
+      'fieldset',
+      '[role="group"]',
+      '[role="radiogroup"]',
+      '[role="listbox"]',
+      '[role="grid"]',
+      '[role="table"]',
+    ].join(',');
+
+    function isVisible(element: Element) {
+      const rect = element.getBoundingClientRect();
+      const style = window.getComputedStyle(element);
+      return (
+        rect.width > 0 &&
+        rect.height > 0 &&
+        style.visibility !== 'hidden' &&
+        style.display !== 'none'
+      );
+    }
+
+    function textFromIdRefs(ids: string | null) {
+      if (!ids) {
+        return '';
+      }
+      return ids
+        .split(/\s+/)
+        .map((id) => document.getElementById(id)?.textContent?.trim() ?? '')
+        .filter(Boolean)
+        .join(' ');
+    }
+
+    function groupName(element: Element) {
+      if (element instanceof HTMLFieldSetElement) {
+        const legend = element.querySelector('legend')?.textContent?.trim();
+        if (legend) {
+          return legend;
+        }
+      }
+
+      return (
+        element.getAttribute('aria-label')?.trim() ||
+        textFromIdRefs(element.getAttribute('aria-labelledby')) ||
+        element.getAttribute('title')?.trim() ||
+        ''
+      );
+    }
+
+    return [...subject.querySelectorAll(groupSelector)]
+      .filter(isVisible)
+      .filter((element) => !groupName(element))
+      .slice(0, 10)
+      .map((element) => element.outerHTML.slice(0, 300));
+  });
+
+  return {
+    check: 'group-label',
+    status: details.length > 0 ? 'failed' : 'passed',
+    message:
+      details.length > 0
+        ? `${details.length} visible group(s) appear to lack a programmatic label`
+        : 'Visible fieldsets and ARIA groups have label signals',
+    details,
+  };
+}
+
 async function checkInteractiveControlNames(page: Page): Promise<CheckResult> {
   const details = await page.locator('[data-testid="a11y-scan-subject"]').evaluate((subject) => {
     const interactiveSelector = [
@@ -345,6 +418,140 @@ async function checkKeyboardTabReach(page: Page): Promise<CheckResult> {
   };
 }
 
+async function checkMathAlternatives(page: Page): Promise<CheckResult> {
+  const result = await page.locator('[data-testid="a11y-scan-subject"]').evaluate((subject) => {
+    const mathSelector = ['math', '.MathJax', '[data-latex]', '[data-math]'].join(',');
+
+    function isVisible(element: Element) {
+      const rect = element.getBoundingClientRect();
+      const style = window.getComputedStyle(element);
+      return (
+        rect.width > 0 &&
+        rect.height > 0 &&
+        style.visibility !== 'hidden' &&
+        style.display !== 'none'
+      );
+    }
+
+    function textFromIdRefs(ids: string | null) {
+      if (!ids) {
+        return '';
+      }
+      return ids
+        .split(/\s+/)
+        .map((id) => document.getElementById(id)?.textContent?.trim() ?? '')
+        .filter(Boolean)
+        .join(' ');
+    }
+
+    const mathNodes = [...subject.querySelectorAll(mathSelector)].filter(isVisible);
+    const missing = mathNodes
+      .filter((element) => {
+        const hasAccessibleName =
+          !!element.getAttribute('aria-label')?.trim() ||
+          !!textFromIdRefs(element.getAttribute('aria-labelledby'));
+        const hasNativeAlternative = !!element.querySelector('annotation, annotation-xml, title');
+        const hasText = !!element.textContent?.trim();
+        return !hasAccessibleName && !hasNativeAlternative && !hasText;
+      })
+      .slice(0, 10)
+      .map((element) => element.outerHTML.slice(0, 300));
+
+    return { count: mathNodes.length, missing };
+  });
+
+  return {
+    check: 'math-alternative',
+    status: result.count === 0 || result.missing.length > 0 ? 'failed' : 'passed',
+    message:
+      result.count === 0
+        ? 'No rendered math nodes were found for this math-alternative scenario'
+        : result.missing.length > 0
+          ? `${result.missing.length} rendered math node(s) appear to lack a text alternative`
+          : 'Rendered math nodes expose text or accessible-name signals',
+    details: result.missing,
+  };
+}
+
+async function checkMediaAlternatives(page: Page): Promise<CheckResult> {
+  const details = await page.locator('[data-testid="a11y-scan-subject"]').evaluate((subject) => {
+    function isVisible(element: Element) {
+      const rect = element.getBoundingClientRect();
+      const style = window.getComputedStyle(element);
+      return (
+        rect.width > 0 &&
+        rect.height > 0 &&
+        style.visibility !== 'hidden' &&
+        style.display !== 'none'
+      );
+    }
+
+    function textFromIdRefs(ids: string | null) {
+      if (!ids) {
+        return '';
+      }
+      return ids
+        .split(/\s+/)
+        .map((id) => document.getElementById(id)?.textContent?.trim() ?? '')
+        .filter(Boolean)
+        .join(' ');
+    }
+
+    function hasNameOrDecorativeRole(element: Element) {
+      if (
+        element.getAttribute('aria-hidden') === 'true' ||
+        element.getAttribute('role') === 'presentation' ||
+        element.getAttribute('role') === 'none'
+      ) {
+        return true;
+      }
+
+      return (
+        !!element.getAttribute('aria-label')?.trim() ||
+        !!textFromIdRefs(element.getAttribute('aria-labelledby')) ||
+        !!element.querySelector('title')?.textContent?.trim()
+      );
+    }
+
+    const missing: string[] = [];
+
+    for (const image of [...subject.querySelectorAll('img')].filter(isVisible)) {
+      if (image.getAttribute('alt') === null && !hasNameOrDecorativeRole(image)) {
+        missing.push(image.outerHTML.slice(0, 300));
+      }
+    }
+
+    for (const graphic of [...subject.querySelectorAll('svg, canvas')].filter(isVisible)) {
+      if (!hasNameOrDecorativeRole(graphic)) {
+        missing.push(graphic.outerHTML.slice(0, 300));
+      }
+    }
+
+    for (const media of [...subject.querySelectorAll('audio, video')].filter(isVisible)) {
+      if (!hasNameOrDecorativeRole(media) && media.querySelectorAll('track').length === 0) {
+        missing.push(media.outerHTML.slice(0, 300));
+      }
+    }
+
+    return {
+      count: subject.querySelectorAll('img, svg, canvas, audio, video').length,
+      missing: missing.slice(0, 10),
+    };
+  });
+
+  return {
+    check: 'media-alternative',
+    status: details.count === 0 || details.missing.length > 0 ? 'failed' : 'passed',
+    message:
+      details.count === 0
+        ? 'No media or graphic nodes were found for this media-alternative scenario'
+        : details.missing.length > 0
+          ? `${details.missing.length} visible media/graphic node(s) appear to lack an alternative or decorative marker`
+          : 'Visible media and graphics expose alternatives or decorative markers',
+    details: details.missing,
+  };
+}
+
 async function checkTargetSize(page: Page): Promise<CheckResult> {
   const details = await page.locator('[data-testid="a11y-scan-subject"]').evaluate((subject) => {
     const selector = [

apps/element-demo/test/a11y/axe-scenarios.spec.ts

@@ -0,0 +1,46 @@
+# PIE Element A11y Tracking
+
+Status: Initial scenario coverage in progress.
+
+This directory tracks the WCAG 2.2 Level AA accessibility coverage for every PIE element in the demo registry. The automated suite lives in `apps/element-demo/src/lib/a11y/scenarios/catalog.ts` and runs through `apps/element-demo/test/a11y/axe-scenarios.spec.ts`.
+
+## Coverage Matrix
+
+| Element | Scenario Coverage | Automated Focus | Remaining Manual / Unclear Work |
+| --- | --- | --- | --- |
+| [categorize](categorize.md) | Drop-zone names; evaluate feedback | Axe, labelled groups, control names, tab reach, target size, status messages | Confirm full drag/drop keyboard workflow and screen-reader placement announcements. |
+| [charting](charting.md) | Editable bar, line, histogram | Axe, labelled groups, control names, tab reach, target size, media alternatives | Confirm data values and chart trends are understandable without sight or color. |
+| [complex-rubric](complex-rubric.md) | Rubric structure; evaluate feedback | Axe, labelled groups, control names, tab reach, status messages | Confirm long descriptors are announced in a usable order. |
+| [drag-in-the-blank](drag-in-the-blank.md) | Blank targets; image word problem | Axe, labelled groups, control names, tab reach, target size, media alternatives | Confirm drag/drop has a complete keyboard alternative and clear live feedback. |
+| [drawing-response](drawing-response.md) | Toolbar controls; evaluate feedback | Axe, labelled groups, control names, tab reach, target size, media alternatives, status messages | Confirm non-pointer drawing alternatives and canvas result descriptions. |
+| [ebsr](ebsr.md) | Two-part choice groups; evaluate feedback | Axe, labelled groups, control names, tab reach, target size, status messages | Confirm Part A/Part B relationship is clear to screen readers. |
+| [explicit-constructed-response](explicit-constructed-response.md) | Embedded fields; evaluate feedback | Axe, labelled groups, control names, tab reach, target size, status messages | Confirm embedded blank instructions remain clear in long rich text. |
+| [extended-text-entry](extended-text-entry.md) | Editor labels; evaluate feedback | Axe, labelled groups, control names, tab reach, target size, status messages | Confirm rich-text/editor keyboard shortcuts and screen-reader mode behavior. |
+| [fraction-model](fraction-model.md) | Segment controls; configurable/improper models | Axe, labelled groups, control names, tab reach, target size, media alternatives | Confirm fraction visuals have equivalent text meaning. |
+| [graphing](graphing.md) | Toolbar; parabola graph | Axe, labelled groups, control names, tab reach, target size, media alternatives | Confirm graph construction can be completed without pointer input. |
+| [graphing-solution-set](graphing-solution-set.md) | Solution region; evaluate feedback | Axe, labelled groups, control names, tab reach, target size, media alternatives, status messages | Confirm shaded solution regions do not rely on color or position alone. |
+| [hotspot](hotspot.md) | Hotspot region names | Axe, labelled groups, control names, tab reach, target size, media alternatives | Confirm hotspot labels are descriptive without revealing answers. |
+| [image-cloze-association](image-cloze-association.md) | Image targets and responses | Axe, labelled groups, control names, tab reach, target size, media alternatives | Confirm image/drop target relationship is understandable without sight. |
+| [inline-dropdown](inline-dropdown.md) | Combobox blanks; evaluate feedback | Axe, labelled groups, control names, tab reach, target size, status messages | Confirm dropdown open/close and option navigation behavior with screen readers. |
+| [likert](likert.md) | Scale radio group; evaluate feedback | Axe, labelled groups, control names, tab reach, target size, status messages | Confirm scale endpoints and selected state are announced clearly. |
+| [match](match.md) | Row choice labels; evaluate feedback | Axe, labelled groups, control names, tab reach, target size, status messages | Confirm row/answer relationships are navigable without visual table layout. |
+| [match-list](match-list.md) | Association controls; evaluate feedback | Axe, labelled groups, control names, tab reach, target size, status messages | Confirm prompt/answer association context is retained during navigation. |
+| [math-inline](math-inline.md) | Math editor; evaluate feedback | Axe, labelled groups, control names, tab reach, target size, math alternatives, status messages | Confirm equation editor output is usable with screen readers. |
+| [math-templated](math-templated.md) | Template fields; evaluate feedback | Axe, labelled groups, control names, tab reach, target size, math alternatives, status messages | Confirm blank-to-expression context survives screen-reader navigation. |
+| [matrix](matrix.md) | Row/column relationships; evaluate feedback | Axe, labelled groups, control names, tab reach, target size, status messages | Confirm row and column headers are announced for each selectable cell. |
+| [mc-populated-blank](mc-populated-blank.md) | Choice labels; audio/transcript; stem association | Axe, labelled groups, control names, tab reach, target size, media alternatives | Confirm transcript completeness and blank/stem association. |
+| [multi-trait-rubric](multi-trait-rubric.md) | Trait table structure; evaluate feedback | Axe, labelled groups, control names, tab reach, status messages | Confirm trait/score descriptor relationships for assistive tech. |
+| [multiple-choice](multiple-choice.md) | Single-select; multi-select; evaluate feedback | Axe, labelled groups, control names, tab reach, target size, status messages | Confirm radio vs checkbox semantics match configuration. |
+| [number-line](number-line.md) | Point controls; inequality rays | Axe, labelled groups, control names, tab reach, target size, media alternatives | Confirm endpoint inclusion, ray direction, and plotted values are exposed textually. |
+| [passage](passage.md) | Reading structure; poetry order | Axe, labelled groups | Confirm line/stanza reading and hidden layout text with screen readers. |
+| [placement-ordering](placement-ordering.md) | Keyboard reorder; evaluate feedback | Axe, labelled groups, control names, tab reach, target size, status messages | Confirm reorder workflow can be completed and announced without drag input. |
+| [rubric](rubric.md) | Score structure; descriptor order | Axe, labelled groups, control names, tab reach | Confirm descriptor reading order and heading structure in long rubrics. |
+| [select-text](select-text.md) | Token semantics; evaluate feedback | Axe, labelled groups, control names, tab reach, target size, status messages | Confirm text selection workflow and selected state announcements. |
+| [simple-cloze](simple-cloze.md) | Input label; evaluate feedback | Axe, labelled groups, control names, tab reach, target size, status messages | Confirm input error/correctness messages are clear and associated. |
+| [venn-classification](venn-classification.md) | Tile/region keyboard; region overrides | Axe, labelled groups, control names, tab reach, target size, media alternatives | Confirm region placement announcements and keyboard classification workflow. |
+
+## Tracking Notes
+
+- Automated checks do not prove complete keyboard workflows or screen-reader usability; those are tracked as manual gaps in the per-element files.
+- Findings are currently non-blocking unless `A11Y_ENFORCE=1` is set.
+- If an issue requires changing a synced React element or shared React lib, fix it upstream before syncing into this repository.

docs/a11y/TRACKING.md

@@ -0,0 +1,15 @@
+# Categorize A11y Coverage
+
+## Intended Use
+
+Students classify draggable answer choices into labelled categories. Evaluate mode shows correctness feedback for placed choices.
+
+## Automated Coverage
+
+- `category-dropzone-keyboard-names`: labelled category regions, draggable choice names, keyboard reachability, target size.
+- `category-feedback-status`: evaluate-mode feedback and live/status semantics.
+
+## Not Covered / Manual
+
+- Confirm the complete classification workflow can be completed without drag gestures.
+- Confirm screen readers announce pick-up, movement, drop target, and final placement changes clearly.

docs/a11y/categorize.md

@@ -0,0 +1,16 @@
+# Charting A11y Coverage
+
+## Intended Use
+
+Students inspect or edit chart data in bar, line, and histogram forms. The element combines form-like controls with non-text chart graphics.
+
+## Automated Coverage
+
+- `editable-bar-chart-controls`: labelled chart controls, keyboard reachability, target size, non-text contrast.
+- `line-chart-add-points`: add-point workflow, visible controls, and chart affordances.
+- `histogram-non-text-alternatives`: histogram graphic alternatives and color-independent chart meaning.
+
+## Not Covered / Manual
+
+- Confirm chart values, trends, and bin meanings are available without relying on sight or color alone.
+- Confirm pointer-based chart editing has a complete keyboard alternative.

docs/a11y/charting.md

@@ -0,0 +1,15 @@
+# Complex Rubric A11y Coverage
+
+## Intended Use
+
+Instructors review detailed rubric criteria and score responses across long descriptors and structured scale levels.
+
+## Automated Coverage
+
+- `rubric-scale-structure`: rubric headings, labels, table-like relationships, and descriptor readability.
+- `complex-rubric-evaluate-feedback`: evaluate-mode score controls, status feedback, and labelled groups.
+
+## Not Covered / Manual
+
+- Confirm long descriptors are announced in a usable order by screen readers.
+- Confirm visual scale layout does not obscure the relationship between criteria and score points.

docs/a11y/complex-rubric.md

@@ -0,0 +1,15 @@
+# Drag In The Blank A11y Coverage
+
+## Intended Use
+
+Students place draggable choices into inline blanks or target areas, sometimes alongside images or math content.
+
+## Automated Coverage
+
+- `blank-drop-keyboard-alternative`: blank targets, draggable choice labels, keyboard reachability, and target size.
+- `image-blank-alternatives`: image alternatives, labelled choices, and keyboard-reachable image-based blanks.
+
+## Not Covered / Manual
+
+- Confirm the complete blank-filling workflow works without drag gestures.
+- Confirm placement changes are announced through clear live feedback.