From 5d160c0e09e7c29db02ce7c33a30a1df6bd7a45a Mon Sep 17 00:00:00 2001 From: Zhongwei Li Date: Sun, 30 Nov 2025 08:22:53 +0800 Subject: [PATCH] Initial commit --- .claude-plugin/plugin.json | 15 +++ README.md | 3 + commands/a11y-scan.md | 115 ++++++++++++++++++ plugin.lock.json | 69 +++++++++++ skills/accessibility-test-scanner/SKILL.md | 52 ++++++++ .../assets/README.md | 6 + .../assets/example_scan_results.json | 70 +++++++++++ .../assets/report_template.md | 87 +++++++++++++ .../references/README.md | 8 ++ .../scripts/README.md | 7 ++ 10 files changed, 432 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 README.md create mode 100644 commands/a11y-scan.md create mode 100644 plugin.lock.json create mode 100644 skills/accessibility-test-scanner/SKILL.md create mode 100644 skills/accessibility-test-scanner/assets/README.md create mode 100644 skills/accessibility-test-scanner/assets/example_scan_results.json create mode 100644 skills/accessibility-test-scanner/assets/report_template.md create mode 100644 skills/accessibility-test-scanner/references/README.md create mode 100644 skills/accessibility-test-scanner/scripts/README.md diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..7b6fbcf --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,15 @@ +{ + "name": "accessibility-test-scanner", + "description": "A11y compliance testing with WCAG 2.1/2.2 validation, screen reader compatibility, and automated accessibility audits", + "version": "1.0.0", + "author": { + "name": "Claude Code Plugin Hub", + "email": "[email protected]" + }, + "skills": [ + "./skills" + ], + "commands": [ + "./commands" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..5b401d1 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# accessibility-test-scanner + +A11y compliance testing with WCAG 2.1/2.2 validation, screen reader compatibility, and automated accessibility audits diff --git a/commands/a11y-scan.md b/commands/a11y-scan.md new file mode 100644 index 0000000..3cb5260 --- /dev/null +++ b/commands/a11y-scan.md @@ -0,0 +1,115 @@ +--- +description: Scan for accessibility issues with WCAG 2.1/2.2 compliance and screen reader testing +shortcut: a11y +--- + +# Accessibility Test Scanner + +Comprehensive accessibility testing with WCAG 2.1/2.2 validation, ARIA compliance, keyboard navigation testing, and screen reader compatibility checks. + +## What You Do + +1. **WCAG Compliance Scanning** + - Check WCAG 2.1 Level A, AA, AAA compliance + - Validate WCAG 2.2 new success criteria + - Generate detailed compliance reports + +2. **ARIA Validation** + - Verify proper ARIA usage + - Detect ARIA antipatterns + - Validate landmark regions and roles + +3. **Keyboard Navigation** + - Test tab order and focus management + - Verify keyboard shortcuts + - Check focus indicators + +4. **Screen Reader Testing** + - Generate screen reader test scenarios + - Validate semantic HTML + - Check alt text and labels + +5. **Color Contrast** + - Validate color contrast ratios + - Test for color blindness + - Suggest accessible color palettes + +## Usage Pattern + +When invoked, you should: + +1. Identify pages/components to test +2. Run automated accessibility audits (axe-core, Pa11y, Lighthouse) +3. Analyze results against WCAG criteria +4. Prioritize issues by severity and impact +5. Generate fix recommendations with code examples +6. Create accessibility test suite + +## Output Format + +```markdown +## Accessibility Audit Report + +### Compliance Level: [A / AA / AAA] +**Pages Scanned:** [N] +**Issues Found:** [Critical: N, Serious: N, Moderate: N, Minor: N] + +### Critical Issues (WCAG Level A) + +#### Issue: [Description] +**WCAG Criterion:** [X.X.X - Name] +**Impact:** [High/Medium/Low] +**Affected Elements:** [N] +**Location:** `[selector or file:line]` + +**Problem:** +[Detailed explanation] + +**Fix:** +```html + +[problematic code] + + +[corrected code] +``` + +**Testing:** +- [ ] Screen reader: [how to verify] +- [ ] Keyboard: [how to verify] + +### ARIA Issues +- Missing labels: [N] +- Invalid roles: [N] +- Incorrect relationships: [N] + +### Keyboard Navigation + Tab order: Logical + Focus indicators: Missing on [N] elements + Keyboard traps: Found [N] + +### Color Contrast + Normal text: Pass + Small text: [N] failures + UI components: [N] failures + +### Recommendations +1. [Priority fix] +2. [Priority fix] +3. [Enhancement] + +### Next Steps +- [ ] Fix critical WCAG A violations +- [ ] Address WCAG AA issues +- [ ] Set up automated a11y testing +- [ ] Manual screen reader testing +``` + +## Testing Tools Integration + +- axe-core (automated testing) +- Pa11y (command-line testing) +- Lighthouse accessibility audit +- WAVE browser extension +- NVDA/JAWS screen reader scripts +- jest-axe / cypress-axe for automated tests diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..d22469c --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,69 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:jeremylongshore/claude-code-plugins-plus:plugins/testing/accessibility-test-scanner", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "5c44e5c4551a8a5dafeadf67074efdc8fc44bacf", + "treeHash": "f615926b692216c9c1415c45981fc96ef1c44ff1d97e58549589b4c0ffc2a48f", + "generatedAt": "2025-11-28T10:18:02.691617Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "accessibility-test-scanner", + "description": "A11y compliance testing with WCAG 2.1/2.2 validation, screen reader compatibility, and automated accessibility audits", + "version": "1.0.0" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "2d7d934f3ac07914011fa19929ee2395c870ae9fd89e5dc00ad7065d77e50706" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "d5c97d2efab2502a03326b1cc3c1410e6087150a5e3487def2d44d012133f38b" + }, + { + "path": "commands/a11y-scan.md", + "sha256": "532908cd7f8feb53446b3ebe74db67f46f4f23fede9abfb9faa6fc2c5ba65f71" + }, + { + "path": "skills/accessibility-test-scanner/SKILL.md", + "sha256": "7b10ddea864aeba031f62db3ea3811675271175428e7cd5bfde53ec5623b6ff6" + }, + { + "path": "skills/accessibility-test-scanner/references/README.md", + "sha256": "831fcb0d753740ba86be0d571acc3ff58721abca898157588fdfc2d76b1c1867" + }, + { + "path": "skills/accessibility-test-scanner/scripts/README.md", + "sha256": "d93f9cc0db0bbf291b6aa54b6d4bdb3e5e4ef17b1a88438b5348dd13e756679d" + }, + { + "path": "skills/accessibility-test-scanner/assets/example_scan_results.json", + "sha256": "0238f54461df0861167611e5d1318a749ead703aed258f54f9814c40e38c69de" + }, + { + "path": "skills/accessibility-test-scanner/assets/report_template.md", + "sha256": "ed2f481ddda1a1d64f7c05bedc01f67a11432bb1836e8a8fb45b26eeef9f1014" + }, + { + "path": "skills/accessibility-test-scanner/assets/README.md", + "sha256": "31d95d92b0349d8d93ed31726d96d9e9c49e94873132b3819ccd7c717b89f562" + } + ], + "dirSha256": "f615926b692216c9c1415c45981fc96ef1c44ff1d97e58549589b4c0ffc2a48f" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/skills/accessibility-test-scanner/SKILL.md b/skills/accessibility-test-scanner/SKILL.md new file mode 100644 index 0000000..f3ce492 --- /dev/null +++ b/skills/accessibility-test-scanner/SKILL.md @@ -0,0 +1,52 @@ +--- +name: scanning-for-accessibility-issues +description: | + This skill enables Claude to perform comprehensive accessibility audits. It uses the accessibility-test-scanner plugin to identify WCAG 2.1/2.2 compliance issues, validate ARIA attributes, check keyboard navigation, and assess screen reader compatibility. Use this skill when the user requests an accessibility scan, audit, or compliance check, or when terms like "WCAG", "ARIA", "screen reader", "accessibility testing", or "a11y" are mentioned. It provides actionable insights for improving web application accessibility. +allowed-tools: Read, Write, Edit, Grep, Glob, Bash +version: 1.0.0 +--- + +## Overview + +This skill empowers Claude to conduct thorough accessibility testing of web applications. It leverages the `accessibility-test-scanner` plugin to pinpoint areas of non-compliance with accessibility standards and offers recommendations for remediation. + +## How It Works + +1. **Initiating the Scan**: Claude invokes the `a11y-scan` command, triggering the accessibility-test-scanner plugin. +2. **Performing the Audit**: The plugin conducts a comprehensive audit, checking for WCAG 2.1/2.2 compliance, ARIA validation, keyboard navigation, and screen reader compatibility. +3. **Generating a Report**: The plugin generates a detailed report outlining accessibility issues found, along with recommendations for fixing them. + +## When to Use This Skill + +This skill activates when you need to: +- Evaluate a web application's compliance with WCAG 2.1 or WCAG 2.2 guidelines. +- Identify ARIA antipatterns and ensure proper ARIA usage. +- Test keyboard navigation and focus management. + +## Examples + +### Example 1: Checking WCAG Compliance + +User request: "Run an accessibility scan on this webpage and tell me if it meets WCAG 2.1 AA standards." + +The skill will: +1. Execute the `a11y-scan` command. +2. Provide a report detailing WCAG 2.1 AA compliance issues and recommendations. + +### Example 2: Validating ARIA Attributes + +User request: "Check the ARIA attributes on this component for any errors or antipatterns." + +The skill will: +1. Execute the `a11y-scan` command. +2. Provide a report highlighting ARIA validation issues and recommended fixes. + +## Best Practices + +- **Specificity**: Be specific in your requests (e.g., "WCAG 2.2 Level AA compliance" instead of just "accessibility"). +- **Context**: Provide the specific webpage or component to be scanned for accurate results. +- **Iteration**: Use the scan results to iteratively improve accessibility and re-scan to verify fixes. + +## Integration + +This skill can be used in conjunction with other tools for code editing and testing. For example, after identifying accessibility issues, Claude can use its coding skills to implement the recommended fixes. \ No newline at end of file diff --git a/skills/accessibility-test-scanner/assets/README.md b/skills/accessibility-test-scanner/assets/README.md new file mode 100644 index 0000000..01026ff --- /dev/null +++ b/skills/accessibility-test-scanner/assets/README.md @@ -0,0 +1,6 @@ +# Assets + +Bundled resources for accessibility-test-scanner skill + +- [ ] report_template.md: Markdown template for generating accessibility reports. +- [ ] example_scan_results.json: Example JSON output of an accessibility scan for demonstration purposes. diff --git a/skills/accessibility-test-scanner/assets/example_scan_results.json b/skills/accessibility-test-scanner/assets/example_scan_results.json new file mode 100644 index 0000000..4a55c08 --- /dev/null +++ b/skills/accessibility-test-scanner/assets/example_scan_results.json @@ -0,0 +1,70 @@ +{ + "_comment": "Example JSON output of an accessibility scan. Represents scan results for a single URL.", + "scan_url": "https://www.example.com/product-page", + "scan_timestamp": "2024-10-27T10:00:00Z", + "wcag_version": "WCAG 2.2", + "overall_score": 75, + "overall_status": "Needs Improvement", + "issues": [ + { + "_comment": "Example of a contrast issue.", + "id": "contrast-aa", + "code": "WCAG 1.4.3", + "severity": "serious", + "description": "Text contrast is below the recommended level for WCAG AA.", + "message": "The contrast ratio between the text color '#A9A9A9' and background color '#FFFFFF' is only 2.2:1. The minimum required ratio is 4.5:1.", + "context": "

This is a product description.

", + "selector": "p.product-description", + "help_url": "https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html", + "impact": "Users with low vision may have difficulty reading this text.", + "tags": ["wcag2a", "wcag1_4_3", "visual"] + }, + { + "_comment": "Example of an ARIA issue.", + "id": "aria-required-children", + "code": "ARIA 4.1", + "severity": "moderate", + "description": "ARIA role requires children to contain particular roles.", + "message": "The element with role 'menubar' must have required children with role 'menuitem'.", + "context": "", + "selector": "ul[role=\"menubar\"]", + "help_url": "https://www.w3.org/TR/wai-aria-1.2/#menubar", + "impact": "Screen reader users may not be able to properly navigate the menu.", + "tags": ["aria", "keyboard", "screenreader"] + }, + { + "_comment": "Example of a keyboard navigation issue.", + "id": "keyboard-navigation", + "code": "WCAG 2.1.1", + "severity": "minor", + "description": "Ensure all page functionality is available using the keyboard.", + "message": "The 'Skip to Content' link is not visible when it receives focus.", + "context": "Skip to Content", + "selector": "a.skip-link", + "help_url": "https://www.w3.org/WAI/WCAG21/Understanding/keyboard.html", + "impact": "Users who rely on keyboard navigation may not be able to easily bypass repetitive content.", + "tags": ["wcag2a", "wcag2_1_1", "keyboard"] + }, + { + "_comment": "Example of an image alt text issue.", + "id": "image-alt", + "code": "WCAG 1.1.1", + "severity": "critical", + "description": "Images must have alternate text.", + "message": "Image missing an alt attribute.", + "context": "", + "selector": "img[src=\"product.jpg\"]", + "help_url": "https://www.w3.org/WAI/WCAG21/Understanding/non-text-content.html", + "impact": "Screen reader users will not understand the purpose of the image.", + "tags": ["wcag2a", "wcag1_1_1", "images", "screenreader"] + } + ], + "summary": { + "critical": 1, + "serious": 1, + "moderate": 1, + "minor": 1, + "passed": 125 + }, + "axe_version": "4.8.2" +} \ No newline at end of file diff --git a/skills/accessibility-test-scanner/assets/report_template.md b/skills/accessibility-test-scanner/assets/report_template.md new file mode 100644 index 0000000..75b0bed --- /dev/null +++ b/skills/accessibility-test-scanner/assets/report_template.md @@ -0,0 +1,87 @@ +# Accessibility Audit Report + +**Date:** `[Insert Date]` +**Website/Application:** `[Insert Website/Application Name]` +**Report Generated By:** Accessibility Test Scanner Plugin + +## Executive Summary + +`[Provide a brief overview of the accessibility audit findings. Highlight key areas of concern and areas of success. For example: "This report details the findings of an accessibility audit conducted on [Website/Application Name] using the Accessibility Test Scanner plugin. The audit identified several critical issues related to color contrast and keyboard navigation. Overall, the application demonstrates a moderate level of accessibility, but requires improvements to meet WCAG 2.1 AA compliance."]` + +## Scope + +This report covers the following pages/sections of the website/application: + +`[List the specific pages or sections that were audited. For example: "Homepage, Contact Us page, Product Listing page, and User Profile section."]` + +## Methodology + +This audit was conducted using the Accessibility Test Scanner plugin, which performs automated checks based on the following guidelines and standards: + +* **WCAG 2.1/2.2 (Levels A, AA, AAA)**: Web Content Accessibility Guidelines +* **ARIA Validation**: Evaluation of proper ARIA (Accessible Rich Internet Applications) usage. +* **Screen Reader Compatibility**: Simulated screen reader testing. +* **Keyboard Navigation**: Evaluation of keyboard operability. + +`[Optionally, include details about any manual testing performed in addition to the automated checks.]` + +## Findings + +This section details the accessibility issues identified during the audit. Each issue is categorized by WCAG success criterion and severity. + +**Severity Levels:** + +* **Critical:** A violation that severely impacts users' ability to access essential content or functionality. +* **Major:** A violation that significantly hinders users' ability to access content or functionality. +* **Moderate:** A violation that causes some difficulty for users but does not completely prevent access. +* **Minor:** A violation that has a minimal impact on users but should still be addressed. + +### WCAG 2.1/2.2 Violations + +`[For each violation, provide the following information:]` + +* **WCAG Success Criterion:** `[e.g., 1.1.1 Non-text Content, 1.4.3 Contrast (Minimum)]` +* **Severity:** `[Critical, Major, Moderate, Minor]` +* **Description:** `[A clear explanation of the issue. For example: "The image on the homepage lacks alt text."]` +* **Location:** `[Specific page or element where the issue was found. For example: "Homepage, tag."]` +* **Recommendation:** `[Specific steps to fix the issue. For example: "Add descriptive alt text to the image. Example: Company Logo"]` +* **Example:** + + **WCAG Success Criterion:** 1.4.3 Contrast (Minimum) + **Severity:** Critical + **Description:** The text color on the call-to-action button does not provide sufficient contrast with the background color, making it difficult for users with low vision to read. + **Location:** Homepage, `#cta-button` + **Recommendation:** Increase the contrast ratio between the text and background colors to meet the minimum requirement of 4.5:1 for normal text. Consider using a color contrast checker tool to ensure compliance. + **Example:** Change the button's background color from `#ddd` to `#007bff` and the text color to `#fff` to meet WCAG contrast requirements. + +### ARIA Validation Issues + +`[Document any issues related to incorrect or missing ARIA attributes. Follow the same format as above.]` + +* **Description:** `[e.g., "Missing ARIA label on a form field."]` +* **Location:** `[e.g., "Contact Us page, "]` +* **Recommendation:** `[e.g., "Add aria-label attribute to the input field. Example: "]` + +### Keyboard Navigation Issues + +`[Document any issues related to keyboard accessibility. Follow the same format as above.]` + +* **Description:** `[e.g., "The tab order is not logical."]` +* **Location:** `[e.g., "Product Listing page"]` +* **Recommendation:** `[e.g., "Ensure the tab order follows the visual flow of the page. Use the `tabindex` attribute to explicitly define the tab order if necessary."]` + +### Screen Reader Compatibility Issues + +`[Document any issues identified during simulated screen reader testing. Follow the same format as above.]` + +* **Description:** `[e.g., "The screen reader does not announce the state of the checkbox."]` +* **Location:** `[e.g., "User Profile section, "]` +* **Recommendation:** `[e.g., "Use appropriate ARIA attributes to provide screen readers with information about the state of the checkbox. Example: "]` + +## Recommendations + +`[Provide a summary of the key recommendations for improving the accessibility of the website/application. Prioritize recommendations based on severity.]` + +## Conclusion + +`[Summarize the overall accessibility posture of the website/application and outline next steps for remediation. For example: "While the Accessibility Test Scanner plugin identified several accessibility issues, addressing these issues will significantly improve the user experience for people with disabilities. We recommend prioritizing the critical and major issues and implementing the recommendations outlined in this report."]` \ No newline at end of file diff --git a/skills/accessibility-test-scanner/references/README.md b/skills/accessibility-test-scanner/references/README.md new file mode 100644 index 0000000..918527e --- /dev/null +++ b/skills/accessibility-test-scanner/references/README.md @@ -0,0 +1,8 @@ +# References + +Bundled resources for accessibility-test-scanner skill + +- [ ] wcag_2_1_guidelines.md: Comprehensive documentation of WCAG 2.1 guidelines, organized for easy reference. +- [ ] wcag_2_2_guidelines.md: Comprehensive documentation of WCAG 2.2 guidelines, organized for easy reference. +- [ ] aria_best_practices.md: Detailed guide on ARIA attribute usage and common pitfalls. +- [ ] supported_standards.md: A list of supported accessibility standards (WCAG 2.1, WCAG 2.2, Section 508, EN 301 549, ARIA 1.2) with links to official documentation. diff --git a/skills/accessibility-test-scanner/scripts/README.md b/skills/accessibility-test-scanner/scripts/README.md new file mode 100644 index 0000000..af92089 --- /dev/null +++ b/skills/accessibility-test-scanner/scripts/README.md @@ -0,0 +1,7 @@ +# Scripts + +Bundled resources for accessibility-test-scanner skill + +- [ ] wcag_guidelines.py: Script to fetch and parse WCAG guidelines from the web, providing a structured format for Claude to reference. +- [ ] aria_validator.py: Script to validate ARIA attributes against best practices and standards. +- [ ] report_generator.py: Script to generate detailed accessibility reports in various formats (e.g., Markdown, JSON).