excessibility

🥈Silver

Excessibility automates accessibility testing for Phoenix LiveView apps. It captures HTML snapshots during tests, runs Pa11y for WCAG compliance checks, and provides AI-assisted debugging with timeline analysis. Developers benefit from faster, more thorough accessibility audits integrated into their testing workflows.

4030Updated 1mo ago

Intermediate30min to implementautomation

Saves ~45 min per use

Quick InstallView Source

git clone https://github.com/lessthanseventy/excessibility.git

Works with:

Claude

Overview

About This Skill

How to Use

[{"step":"Install Excessibility in your Phoenix LiveView project","action":"Add the Excessibility package to your `mix.exs` file and run `mix deps.get`. Ensure you have Node.js installed for Pa11y dependencies.","tip":"Use `mix excessibility.install` to automatically set up required dependencies and configuration."},{"step":"Configure your test suite to capture HTML snapshots","action":"Update your `test_helper.exs` to include Excessibility in your test pipeline. Example: `Excessibility.setup()` in your `test/test_helper.exs`.","tip":"Ensure your tests run with `MIX_ENV=test` to avoid capturing production snapshots."},{"step":"Run the accessibility audit","action":"Execute the audit using the prompt template. Replace [APP_NAME], [LEVEL], and other placeholders. Example: `excessibility --app TaskFlow --level AA --output json > accessibility_report.json`.","tip":"For CI/CD integration, use `excessibility --app TaskFlow --level AA --ci-mode` to fail the build on critical issues."},{"step":"Review the AI-generated report and implement fixes","action":"Open the generated report (e.g., `accessibility_report.json`) and address the top issues first. Use the timeline analysis to prioritize fixes based on when issues were introduced.","tip":"For complex issues, use the `excessibility debug --issue-id [ID]` command to get a detailed breakdown and suggested code changes."},{"step":"Re-run the audit to verify fixes","action":"After implementing changes, re-run the audit to confirm compliance. Example: `excessibility --app TaskFlow --level AA --compare-with previous_report.json`.","tip":"Use the `--compare-with` flag to track progress over time and ensure regressions are caught early."}]

Setup & Installation

Quick Install

No install command available. Check the GitHub repository for manual installation instructions.

Alternative Install (Git Clone)

git clone https://github.com/lessthanseventy/excessibility

Requirements

Claude Code or compatible AI agent
Works with: Claude

Quick Start Guide

Install the Skill

Copy the install command above and run it in your terminal.

Open Your AI Agent

Launch Claude Code, Cursor, or your preferred AI coding agent.

Try It Out

Use the prompt template or examples below to test the skill.

Customize

Adapt the skill to your specific use case and workflow.

Usage Examples

Prompt Template

Run an accessibility audit on the Phoenix LiveView app for [APP_NAME] using Excessibility. Generate HTML snapshots from the test suite, run Pa11y WCAG compliance checks with [LEVEL (A, AA, or AAA)], and analyze the results with AI-assisted debugging. Highlight the top 3 accessibility issues and suggest specific fixes for each. Include a timeline breakdown of when each issue was introduced (e.g., during a recent refactor or new feature addition).

Example Output

### Accessibility Audit Report for **Phoenix LiveView App: TaskFlow**

**Test Run:** `excessibility --app TaskFlow --level AA --output json`
**Snapshot Date:** 2023-11-15
**Pa11y Version:** 6.4.0

#### Summary
- **Total Issues Found:** 12
- **Critical Issues:** 3 (WCAG 2.1 Level AA violations)
- **Automated Fixes Suggested:** 5
- **Manual Review Required:** 4

---

#### Top 3 Critical Issues

1. **Missing ARIA Labels on Dynamic Form Fields**
   - **Location:** `lib/task_flow_web/live/task_form.ex` (lines 42-55)
   - **Issue:** The `phx-update="append"` LiveView container lacks an `aria-live` region to announce new items to screen readers.
   - **WCAG Violation:** 4.1.2 (Name, Role, Value)
   - **Timeline:** Introduced in v2.1.0 (2023-10-12) during the "Bulk Task Import" feature.
   - **Suggested Fix:** 
     ```elixir
     <div phx-update="append" aria-live="polite" aria-atomic="true">
       <%= for task <- @tasks do %>
         <%= live_component ... />
       <% end %>
     </div>
     ```
   - **Impact:** Users relying on screen readers cannot track newly added tasks.

2. **Color Contrast Failure in Status Badges**
   - **Location:** `assets/css/app.css` (lines 187-195)
   - **Issue:** The `status-badge` class uses `#3b82f6` (blue) on a white background, resulting in a contrast ratio of 3.1:1 (fails WCAG 2.1 AA minimum of 4.5:1).
   - **WCAG Violation:** 1.4.3 (Contrast Minimum)
   - **Timeline:** Present since initial release (2023-06-01).
   - **Suggested Fix:** Replace with `#2563eb` (darker blue) for a contrast ratio of 5.6:1.
   - **Impact:** Users with low vision may struggle to distinguish task statuses.

3. **Non-Descriptive Link Text in Task List**
   - **Location:** `lib/task_flow_web/live/task_list.html.heex` (line 28)
   - **Issue:** The link `<a href="/tasks/123">Click here</a>` lacks descriptive text for screen readers.
   - **WCAG Violation:** 2.4.4 (Link Purpose)
   - **Timeline:** Introduced in v1.2.0 (2023-08-15) during the initial MVP.
   - **Suggested Fix:** 
     ```html
     <a href="/tasks/123" aria-label="View details for task: Fix login bug">View Details</a>
     ```
   - **Impact:** Screen reader users cannot determine the purpose of the link without context.

---

#### Automated Fixes Applied
- **Fixed:** Missing `lang` attribute in `<html>` tag (added `lang="en"`).
- **Fixed:** Redundant `role="button"` on `<button>` elements (removed).
- **Fixed:** Missing `alt` text for decorative icons (added `aria-hidden="true"`).

---

#### Manual Review Required
1. **Keyboard Navigation in Task Editor:** The modal for editing tasks traps focus incorrectly. Requires manual testing with `Tab` and `Shift+Tab`.
2. **Skip Links:** No "Skip to Main Content" link exists for keyboard users.
3. **Form Validation Errors:** Error messages are not programmatically associated with form fields (missing `aria-describedby`).
4. **LiveView Focus Management:** After task completion, focus is not reset to the task list (disrupts keyboard workflow).

---

#### Timeline Analysis
| Issue | Introduced In | Last Modified | Root Cause |
|-------|---------------|---------------|------------|
| Missing ARIA Labels | v2.1.0 (2023-10-12) | 2023-11-10 | Added LiveView append feature without accessibility considerations. |
| Color Contrast | v1.0.0 (2023-06-01) | 2023-11-05 | Design system did not include accessibility tokens. |
| Non-Descriptive Links | v1.2.0 (2023-08-15) | 2023-11-08 | Rapid MVP development prioritized functionality over UX. |

---

**Recommendation:** Prioritize fixes for the 3 critical issues. Schedule a follow-up audit after implementing the suggested changes to verify compliance.