A five-layer approach to ensure semantic accuracy in LLM-generated React components
Nowadays, AI code generators like Claude Code or Codex can create a visually appealing React sidebar in seconds. However, when checking the accessibility tree in DevTools, such components often lack semantic details, resulting in the root side element having role `generic`, name `none`, and not being focusable, making it essentially non-existent for assistive technology users.
This issue arises because LLMs prioritize visual output over semantic details, which are crucial for assistive technologies. This article explores the architectural reasons behind this problem and introduces a five-layer enforcement system. The system employs prompt constraints, static analysis, runtime testing, CI integration, and accessible components to ensure automatic semantic correctness. Though React and Tailwind are used in examples, the principles apply to any framework.
Specialized tools like Vercel’s v0 have started incorporating accessible primitives, outputting components built on Radix with inherent accessibility, showcasing the right approach. However, many general-purpose tools still generate inadequate `
The Problem Illustrated:
Below is a navigation sidebar produced by general-purpose AI code generators. Testing various prompts across these tools reveals consistent structural inadequacies.
Browser’s accessibility tree for this component:
group
text “Settings”
group
group
text “Account”
image (no accessible name)
group
text “Profile”
text “Security”
What’s incorrect:
1. No navigation role for the outer `
2. “Settings” is a styled `
`, making heading navigation ineffective.
3. Items lack `/- ` structure, providing no “list, 2 items” context.
4. Account `` mistakenly carries a `generic` role instead of indicating interaction.
5. `` elements aren’t tabbable, hindering keyboard users’ interaction.
6. No `aria-expanded`, making chevron rotation visual-only.
7. Missing `aria-controls` to connect the toggle with the panel.
8. Lacking `onKeyDown`, rendering Enter/Space non-functional when focused.
9. SVGs are unlabeled without `aria-hidden` or names.
10. Profile and Security are clickable `` elements without `link` roles or focusability.With ten issues across 29 lines, screen readers only detect unstructured text with no interaction cues. Extensive testing reveals widespread occurrences of `
` instead of semantic elements, missing ARIA state attributes, absent keyboard handling, and icons lacking text alternatives.AI tools are improving, with newer models generating better semantic HTML and increasingly considering accessibility prompts. However, inconsistencies persist, necessitating systematic enforcement.
Why This Happens: Accessibility Tree
The browser creates two main representations from HTML and CSS: a render tree for visual elements and an Accessibility Tree for semantics following WAI-ARIA, HTML-AAM, and Core AAM standards. While AI-generated code excels at visuals, it lacks semantic fidelity.
Why AI Struggles:
1. Training data: GitHub’s React code focuses on `
` elements, underrepresenting semantic HTML and ARIA.
2. Feedback loops: Visual assessment by developers and evaluators reinforces visual accuracy over semantics.
3. Token economics: Shorter `{fn}` versus a detailed semantic button discourages longer expressions.
4. Lack of AOM modeling: AI models visualize code rather than understanding its assistive technology semantics.
Acknowledging these challenges emphasizes the need to enforce semantic correctness proactively.
Layer Implementation:
Layer 1: Prompt Constraints. Specify constraints within various tooling interfaces to ensure generated components adhere to semantic rules automatically.
Layer 2: Static Analysis. Use ESLint with the `eslint-plugin-jsx-a11y` plugin to catch common semantic issues in code.
Layer 3: Runtime Testing. Utilize tools like Playwright with ‘@axe-core/playwright’ for real-time accessibility testing in the browser.
Layer 4: CI Integration. CI frameworks like GitHub Actions enforce accessibility checks, preventing code with accessibility issues from merging.
Layer 5: Accessible Component Abstractions. Prefer libraries with built-in accessibility like Headless UI or Radix UI over raw code to maintain semantic accuracy automatically.
Common AI failure patterns include the invisible modal, icon-only buttons, custom selects, color contrast issues, and motion sensitivity problems. Layered enforcement improves accessibility and shifts responsibility to well-tested libraries and configurations, reducing human oversight and ensuring compliant code.
4. Account `
5. `
6. No `aria-expanded`, making chevron rotation visual-only.
7. Missing `aria-controls` to connect the toggle with the panel.
8. Lacking `onKeyDown`, rendering Enter/Space non-functional when focused.
9. SVGs are unlabeled without `aria-hidden` or names.
10. Profile and Security are clickable `
With ten issues across 29 lines, screen readers only detect unstructured text with no interaction cues. Extensive testing reveals widespread occurrences of `
AI tools are improving, with newer models generating better semantic HTML and increasingly considering accessibility prompts. However, inconsistencies persist, necessitating systematic enforcement.
Why This Happens: Accessibility Tree
The browser creates two main representations from HTML and CSS: a render tree for visual elements and an Accessibility Tree for semantics following WAI-ARIA, HTML-AAM, and Core AAM standards. While AI-generated code excels at visuals, it lacks semantic fidelity.
Why AI Struggles:
1. Training data: GitHub’s React code focuses on `
2. Feedback loops: Visual assessment by developers and evaluators reinforces visual accuracy over semantics.
3. Token economics: Shorter `
` versus a detailed semantic button discourages longer expressions.
4. Lack of AOM modeling: AI models visualize code rather than understanding its assistive technology semantics.
Acknowledging these challenges emphasizes the need to enforce semantic correctness proactively.
Layer Implementation:
Layer 1: Prompt Constraints. Specify constraints within various tooling interfaces to ensure generated components adhere to semantic rules automatically.
Layer 2: Static Analysis. Use ESLint with the `eslint-plugin-jsx-a11y` plugin to catch common semantic issues in code.
Layer 3: Runtime Testing. Utilize tools like Playwright with ‘@axe-core/playwright’ for real-time accessibility testing in the browser.
Layer 4: CI Integration. CI frameworks like GitHub Actions enforce accessibility checks, preventing code with accessibility issues from merging.
Layer 5: Accessible Component Abstractions. Prefer libraries with built-in accessibility like Headless UI or Radix UI over raw code to maintain semantic accuracy automatically.
Common AI failure patterns include the invisible modal, icon-only buttons, custom selects, color contrast issues, and motion sensitivity problems. Layered enforcement improves accessibility and shifts responsibility to well-tested libraries and configurations, reducing human oversight and ensuring compliant code.