Preface

The DSH plugin ecosystem aims to solve specific development problems by composing independent tools. When developing and reviewing frontend projects, ensuring accessibility compliance (WCAG) usually relies on manual inspection or complex static analysis tools. dsh-a11y-scan is a native plugin that integrates the axe-core scanning engine to automatically detect issues in local HTML files, build output directories, or user-confirmed URLs, and outputs structured violation reports.

Core Capabilities

This plugin mainly provides the following capabilities:
* Automated Scanning: Based on axe-core, it scans local HTML files, build artifact directories for Vite/Next.js, etc., or user-confirmed URLs.
* Multiple Output Formats: Violation results can be reported as Markdown, HTML (self-contained single file), or JSON.
* Read-Only Mode: The plugin is a read-only tool and does not automatically modify code; all file write operations require explicit parameter configuration.
* Programmable Standalone Tool: It can be invoked independently in CI/Workflows outside conversation flows and outputs structured data.
* Automation and Manual Review: For items that axe cannot automatically determine (such as focus order, keyboard operation, and reading/announcement order), it outputs an incomplete checklist for manual review.
* Detailed Report Information: Each violation includes the rule ID, Impact severity, WCAG 2.1 mapping, element locator information, and remediation suggestions.

Installation and Enablement

Installing the plugin requires mounting the local path to a specified Profile.

dsh plugin --profile <name> add /path/to/dsh-a11y-scan

Usage

The tool name is a11y_scan, invoked via dsh tool run. The main parameters are as follows:
* path: scan target; supports project directories, single HTML files, or URLs (URL mode requires confirmUrl: true).
* level: WCAG compliance level; supports A, AA, and AAA, defaulting to AA.
* wcag21: whether to use the WCAG 2.1 tag family, defaulting to true.
* out: report format; supports md, html, or json, defaulting to md.
* confirmUrl: whether explicit confirmation is required when scanning URLs, defaulting to false.
* reportFile: specifies the path of the generated report file (optional).

Example:

dsh tool run a11y_scan '{"path": "dist", "level": "AA", "out": "html", "reportFile": "reports/a11y.html"}'

Notes

  • Prerequisite Dependency: The plugin depends on @axe-core/cli (MPL-2.0 license) as the scanning backend. This dependency must be installed separately in the target project directory (npm i -D @axe-core/cli), and the plugin itself does not bundle this dependency.
  • Development Mode Dependency: In development mode, the plugin depends on an adjacent dsh-src directory (link dependency).
  • Permissions and Security: The plugin runs with the current DSH process permissions. URL scanning requires explicitly enabling confirmUrl; local file scanning does not access the network.
  • Licensing: The plugin code follows the MIT license, and the axe-core scanning engine follows the MPL-2.0 license.

Summary

By integrating axe-core into the DSH ecosystem, dsh-a11y-scan provides a deterministic automated accessibility review solution. It not only outputs structured violation lists but also marks edge cases that require manual review as incomplete items. Combined with CI processes and manual review, it can effectively improve the efficiency of WCAG compliance checks in frontend projects.

Details and source code:
* Plugin Directory
* GitHub Repository