ada-review

♿ ADA Review (Agentic Skill)

A state-of-the-art Agentic AI Skill designed to perform WCAG 2.1 Level AA accessibility audits and automated code remediations for Single Page Applications (Next.js, Nuxt/Vue, React).

This skill combines Static Code LLM Reasoning (for semantic architecture) with Dynamic Playwright Testing (Axe-core + viewport reflow + focus management traps) to achieve near 85% automated WCAG coverage.

🚀 Installation (Adding to your Project)

Since this is a skill for Autonomous AI Agents (such as Roo, Claude Desktop, Cursor, or Windsurf), installation consists of cloning this repository into your AI's context folder within your project.

1. Add the skill to your repository

In your terminal, from the root folder of your web project, run:

# Create the skills directory if it doesn't exist
mkdir -p .claude/skills

# Clone the main skills repository into a temp folder and copy ada-review
git clone https://github.com/Brunopaun/awesome-agent-skills.git /tmp/awesome-agent-skills
cp -r /tmp/awesome-agent-skills/ada-review .claude/skills/
rm -rf /tmp/awesome-agent-skills

(Alternatively: You can manually download the ada-review folder and place it in .claude/skills/).

2. Install dependencies for dynamic tests

To enable the AI to run axe-core and test the interactivity of your rendered application (Playwright), run the following:

cd .claude/skills/ada-review/tests
pip install -r requirements.txt
playwright install chromium

---

🤖 Usage (Commands for the AI)

Open your chat with the agent/LLM (e.g., Claude tab, Cursor Chat) and invoke the orchestrator by referencing the SKILL.md file.

Usage tip for tools like Cursor / Roo: Send a prompt tagging the skill: @.claude/skills/ada-review/SKILL.md /ada-review /dashboard

Core Commands (Prompts):

💡 BEST PRACTICE: Do not run the audit on your entire repository at once. Restrict the scope by Route or Feature flow to prevent context-heavy hallucinations.

• Scoped Audit (Recommended): /ada-review <route> (e.g., /ada-review /checkout or /ada-review "Settings Modal")
• Auto-Fix (Hands-on): /ada-review auto-fix <route> (The Agent will run the audits and immediately apply the necessary edits to the source code of that route without asking for repeated permission).

---

🏗️ How does this Skill work under the hood?

1. SKILL.md (The Orchestrator): Acts as the AI's brain, defining steps, loading modules, and mapping test outputs back to your generic TSX/Vue files using Regex/Grep instructions.
2. /modules (Static Analysis): Rule matrices detailing how the AI should judge hierarchies, lang tags, navigation, and other static heuristics that axe-core cannot catch.
3. /templates (Pre-Approved Cures): Custom snippets that adhere to best practices for your specific stack, preventing the AI from hallucinating imports or unknown libraries when composing the Auto-Fix.
4. /tests (The Dynamic Eye): Python scripts running local headless browsers (Playwright) to flag computed color contrasts over images and keyboard tab-traps (focus loops).