# Accessibility Prover MCP

> Accessibility Prover validates component specifications against WCAG 2.2 AA standards before you write code. This MCP checks five critical areas: semantic HTML structure, keyboard focus traps, contrast ratios, screen reader readiness, and motion safety. It acts as a pre-build gate, catching invisible barriers like div soup or inaccessible animations that automated linters miss.

## Overview
- **Category:** productivity
- **Price:** Free
- **Tags:** accessibility-prover, wcag-2-2-aa, eaa-2025, semantic-html, keyboard-navigation, contrast-ratio, screen-reader, reduced-motion, a11y-validation, shift-left-accessibility

## Description

Writing UI components means thinking about more than just how they look. Accessibility Prover forces you to think about compliance from the start. Instead of waiting for a painful post-launch audit—or worse, facing legal fines under regulations like EAA 2025—you run this MCP early in the design process. It validates your component specifications against WCAG 2.2 AA standards using structured reasoning, not just by scanning raw HTML. You connect it via Vinkius and use it as a proactive gate. This means your AI agent or front-end developer can't generate code until the tool confirms five key things: that you used proper semantic tags (like `<button>` instead of a clickable `<div>`), that keyboard users can reach every element, that color contrast passes 4.5:1, and that screen readers have all the necessary labels. It’s about catching structural flaws before they even hit your repository.

## Tools

### validate_accessibility
It validates if your UI design meets all WCAG 2.2 AA standards by checking semantic HTML, keyboard navigation, contrast ratios, screen reader context, and motion safety.

## Prompt Examples

**Prompt:** 
```
Let's build a close button. It's a div with a click event and an X icon inside.
```

**Response:** 
```
Verdict: DIV_SOUP.

A `<div>` lacks native keyboard focus, Enter/Space activation, and the implicit 'button' ARIA role. Screen readers announce it as generic text — the user does not know it is interactive.

Fix: Replace `<div onclick>` with `<button aria-label="Close dialog">`. Add `focus-visible` styles for keyboard users. Hide the decorative SVG icon with `aria-hidden="true"` so the screen reader uses the aria-label instead.
```

**Prompt:** 
```
Component: CloseButton.
Layout: <button class='p-2' aria-label='Close dialog'><svg aria-hidden='true'>...</svg></button>.
Keyboard: native button, focusable. focus-visible: 2px solid outline.
Contrast: icon is #4A5568 on #FFFFFF background. Ratio: 4.62:1.
Screen Reader: aria-label='Close dialog' on button. SVG hidden.
Motion: no animations.
```

**Response:** 
```
Verdict: A11Y_PROVEN.

✓ semanticHTML — Native `<button>` with correct implicit role.
✓ keyboardNavigable — Focusable by default, visible focus indicator present.
✓ contrastCompliant — 4.62:1 exceeds the 4.5:1 AA minimum for standard text.
✓ screenReaderReady — aria-label provides clear context. Decorative SVG hidden.
✓ motionRespected — No animations present, no motion risk.
```

**Prompt:** 
```
Component: CloseButton.
Layout: <button aria-label='Close dialog'><svg>...</svg></button>.
Keyboard: native button.
Contrast: icon color #E2E8F0 on #FFFFFF background. Ratio: 1.28:1.
Screen Reader: aria-label set.
Motion: none.
```

**Response:** 
```
Verdict: CONTRAST_FAILING.

✗ contrastCompliant — Ratio 1.28:1 fails the WCAG 2.2 AA minimum of 4.5:1 by a factor of 3.5×. The icon is effectively invisible to users with low vision or color deficiency.

Fix: Change icon color to #4A5568 (4.62:1) or #374151 (6.33:1) to exceed the 4.5:1 threshold. Verify the ratio in hover and focus states as well — not just default.
```

**Prompt:** 
```
Component: NotificationBanner.
Layout: <div role='alert'> with a dismiss button (<span onclick='close()'>×</span>).
Keyboard: dismiss element is not focusable.
Contrast: text #1F2937 on #FEF3C7 background. Ratio: 8.19:1.
Screen Reader: role='alert' is set on the container. Dismiss has no label.
Motion: banner slides in from the top with 300ms ease-in.
```

**Response:** 
```
Verdict: KEYBOARD_TRAPPED + DIV_SOUP.

✓ contrastCompliant — 8.19:1 exceeds the 4.5:1 minimum.
✓ screenReaderReady (partial) — role='alert' is correct for live announcements.
✗ semanticHTML — Dismiss uses `<span onclick>`, which has no keyboard access or ARIA role. Replace with `<button aria-label="Dismiss notification">`.
✗ keyboardNavigable — Dismiss is unreachable by Tab. Keyboard users cannot close the notification.
✗ motionRespected — 300ms slide animation lacks `prefers-reduced-motion` check. Wrap in `@media (prefers-reduced-motion: no-preference)` or provide `transition: none` fallback.
```

## Capabilities

### Validate semantic structure
It checks if you used correct HTML elements (like `<button>` for actions) instead of relying on non-semantic tags like `<div>`.

### Enforce keyboard accessibility
You ensure every interactive element is reachable via the Tab key, and that modals properly trap focus so users don't get lost in the DOM.

### Verify contrast compliance
It measures foreground/background color ratios across all states (default, hover, focus) to ensure they meet the minimum 4.5:1 standard.

### Ensure screen reader compatibility
The tool verifies that images have descriptive alt texts and that icon buttons include necessary `aria-label` attributes for assistive technology.

### Manage motion risk
You confirm that all animations respect user preferences, specifically checking for the required `@media (prefers-reduced-motion)` overrides.

## Use Cases

### Pre-commit gate for component libraries
A team needs to merge 50 new components. Instead of manual testing, they run the MCP on every single one. If any component fails `validate_accessibility` due to a contrast failure or missing tab order, the build automatically blocks until the spec is fixed.

### AI agent guardrail
An AI coding agent generates a new user profile widget. The MCP intercepts the generated specification and runs it through `validate_accessibility`. The agent receives a verdict of KEYBOARD_TRAPPED and an explicit fix: 'Add focus traps to this modal.' This prevents inaccessible code from being committed.

### EU market launch compliance
Before launching in the EU, product managers run every user-facing component through the MCP. The structured records it generates provide immediate proof of due diligence for EAA 2025 audits, mitigating huge legal liabilities.

### Auditing legacy codebases
The team wants to modernize an old feature set. They feed the existing component's HTML and behavior into `validate_accessibility`. The tool returns a prioritized backlog showing which components are blocking (DIV_SOUP) versus merely degraded (CONTRAST_FAILING).

## Benefits

- Catches structural flaws like 'div soup' and missing focus traps early. This prevents the most common agent failure mode—creating inaccessible, div-based layouts.
- Reduces legal risk by creating auditable records for EAA 2025 compliance. You demonstrate due diligence with every component validation run.
- Saves time and budget. Fixing a contrast ratio during design takes minutes; fixing it after production requires multiple sprints and legal review.
- Goes beyond simple linting. It analyzes behavior, ensuring things like form-label associations and `aria-label` usage are correct, not just that the element exists.
- Tests five dimensions simultaneously (semantic HTML, keyboard flow, contrast, screen reader, motion). The output is an actionable verdict, not a vague severity score.

## How It Works

The bottom line is you get an auditable, prioritized checklist that proves your component meets compliance requirements before a single line of production code is written.

1. Submit a structured specification of your component. This includes the raw HTML structure, color values with hex codes, and descriptions of keyboard behavior.
2. The MCP runs this data through five distinct decision pivots—semantic HTML, keyboard navigation, contrast ratio, screen reader context, and motion safety.
3. You receive one of six structured verdicts (e.g., A11Y_PROVEN or CONTRAST_FAILING) detailing exactly which WCAG standard failed and what the specific fix needs to be.

## Frequently Asked Questions

**Why does Accessibility Prover reject divs with click handlers?**
A `` has no native keyboard interactivity, no focusability, and no implicit ARIA role. Adding `onclick` creates a visual button that keyboard and screen reader users cannot operate. Native `` elements provide focus, Enter/Space activation, and the 'button' role automatically — no extra JavaScript required.

**What is a focus trap and when is it required?**
A focus trap constrains Tab navigation inside a specific element — typically a modal, dialog, or dropdown — so users cannot navigate to the underlying page while the overlay is active. WCAG 2.4.3 (Focus Order) requires it for all modal dialogs. Without it, a keyboard user can Tab behind the modal into invisible content.

**Does Accessibility Prover check contrast across all interactive states?**
Yes. The contrastCompliant pivot validates foreground/background color combinations across five states: default, hover, focus, active, and disabled. A button that passes contrast in its default state but fails on hover (e.g., light gray text on white) is flagged as CONTRAST_FAILING.

**How is this different from axe-core or Lighthouse?**
axe-core and Lighthouse scan rendered HTML in a browser — they detect violations after the code is built and running. Accessibility Prover validates UI specifications before code is written. It reasons about component behavior, keyboard flows, and interaction states at the design level, catching architectural issues that post-build scanners cannot see because they only inspect the final DOM.

**Can I use Accessibility Prover with an AI coding agent?**
Yes — that is a primary use case. AI coding agents default to div-based layouts because divs are syntactically simpler. Accessibility Prover acts as a guardrail: the agent submits its component specification, the prover validates it against 5 pivots, and the agent receives a structured verdict with specific fixes before writing code.

**What does the European Accessibility Act (EAA 2025) mean for my product?**
Since June 2025, the EAA requires all digital products and services sold in the EU to meet accessibility standards equivalent to WCAG 2.1 AA (with WCAG 2.2 AA as the recommended benchmark). Non-compliance carries fines up to 5% of annual revenue and potential market withdrawal. Accessibility Prover helps demonstrate compliance as a build-time gate, creating an auditable validation record.

**What input format does Accessibility Prover expect?**
Submit each component as structured text covering 5 dimensions: (1) Layout — the HTML elements and hierarchy, (2) Keyboard — tab order, focus indicators, focus traps, (3) Contrast — foreground and background hex values with computed ratio, (4) Screen Reader — alt texts, aria-labels, form-label associations, (5) Motion — animation properties and prefers-reduced-motion handling. The tool reasons about each dimension independently.

**Does Accessibility Prover support WCAG 2.2 AAA?**
The tool validates against WCAG 2.2 AA, which is the legally required level under the EAA 2025 and the practical target for most products. AAA requirements (e.g., 7:1 contrast ratio, sign language interpretation) are not enforced — they are aspirational goals that few products achieve fully.