A11yInspect Accessibility Testing Tool

A11yInspect is a comprehensive accessibility checking tool for VS Code and CI/CD pipelines — powered by BarrierBreak custom rulesets. Runs accessibility checks to meet Web Content Accessibility Guideline (WCAG) for HTML, JSX/TSX, Vue, Angular, Markdown, and MDX files.

Building with accessibility in mind will ensure that your digital assets are accessible to people with disabilities.

Licensing

Activating a License

1. Go to VS Code Settings → search for A11yInspect
2. Enter your license key in the License Key field
3. Features unlock automatically based on your tier

Visit A11yInspect for Visual Studio Code Extension for subscription information.

Supported File Types

VS Code Extension

Installation

1. Open VS Code
2. Go to Extensions (Ctrl+Shift+X / Cmd+Shift+X)
3. Search for A11yInspect
4. Click Install

Core Features

WCAG Accessibility Checks

A11yInspect runs WCAG checks powered by BarrierBreak custom rulesets on every supported file. Issues are classified as Fail, Validate, or Suggestion based on their impact, severity and success criteria.

Diagnostics in Problems Panel

All accessibility issues are surfaced directly in VS Code's built-in Problems panel (Ctrl+Shift+M / Cmd+Shift+M), just like lint errors. Each issue shows the rule code, issue type, and the affected line — making it easy to scan issues without leaving your workflow.

Run on Save / Open

A11yInspect can run checks automatically:

• On save — opt-in, runs when you save a supported file (a11yinspect.runOnSave)
• On open — opt-in, runs when you open a supported file (a11yinspect.runOnOpen)

Both can be toggled independently in VS Code Settings.

You can also trigger a check manually at any time by right-clicking in the editor and selecting A11yInspect: Run Accessibility Check, or by using the run button in the sidebar panel toolbar.

Sidebar Issues Panel

The A11yInspect panel appears in the VS Code Activity Bar (side icon bar) and provides a dedicated tree view of all accessibility issues across your workspace.

• Group by severity — Issues grouped as Fails → Validates → Suggestions → Passes; within each group sorted by line number
• Group by file — Issues organised under their source file, sorted Fail → Validate → Suggestion → Pass within each file
• Click to navigate — Click any issue in the tree to jump directly to its location in the editor
• Toolbar actions — Run check, Scan workspace, Refresh, and Clear all buttons in the panel header
• Live updates — The panel refreshes automatically when a check completes

Switch grouping mode via the toolbar or via a11yinspect.panel.groupBy in settings.

Scan Workspace (Pro / Enterprise)

The Scan Workspace button (search icon, second in the panel toolbar) scans all supported files in your workspace at once. It is also available from the Command Palette as A11yInspect: Scan Workspace. Requires a Pro or Enterprise license — Free users will see an upgrade prompt.

When triggered, a file picker opens with every supported file pre-selected. Deselect any files you want to skip, then confirm to start the scan. A single progress bar tracks the scan (Scanning: filename (X/N)), and a summary notification shows the total issue counts when complete. All results are accumulated in the sidebar panel across every scanned file.

Running Run Accessibility Check on a single file (via right-click, toolbar, or Command Palette) clears the panel first and shows only that file's results.

Intellisense & Editor Features (Pro)

Context-Aware Attribute Completions

As you type inside an HTML or JSX tag, A11yInspect suggests the accessibility attributes most relevant to that element — alt for <img>, aria-label for <button>, role for custom elements, and so on. Suggestions are tailored per element type, so you only see what's applicable.

Hover Accessibility Tips

Hover over any HTML element to see a structured accessibility guidance panel — what attributes are missing, what values are expected, and relevant WCAG references. Tips are organised by category for easy scanning.

Code Action Quick Fixes

When a diagnostic underline appears on an element, a lightbulb (💡) shows in the gutter. Clicking it presents a list of pre-written, rule-based fixes — e.g. "Add alt attribute", "Add role" — that can be applied instantly without manual editing. No AI required; these are static fixes based on the accessibility rule.

Show Pass Diagnostics (Enterprise)

By default, only issues are shown. Enterprise users can enable pass diagnostics to see which checks an element successfully passed. This is useful for audits and compliance reporting where proof of passing checks is needed.

Enable via a11yinspect.showPasses: true in settings.

AI Integration — A11yAssist (Enterprise)

A11yAssist AI is inluded in A11yInspect providing AI-powered accessibility fixes and explanations. All AI features require an Enterprise license plus both apiKey and apiEndpoint to be configured.

How Inline Ghost Text Works

Ghost text appears directly in your editor as greyed-out text — you haven't typed it, it's just a preview suggestion:

1. Trigger — Type an opening tag followed by a space, e.g. <img or <button
2. Detection — A11yInspect checks the element type and identifies missing required accessibility attributes
3. AI suggestion — A contextual prompt is sent to your configured AI provider, which returns the appropriate attribute and value
4. Ghost text appears — The suggestion renders inline at your cursor, e.g. alt="product thumbnail"
5. Accept or ignore — Press Tab to insert it, or keep typing to dismiss it

Ghost text is non-blocking and only appears when A11yInspect detects a likely accessibility gap — not on every keystroke. It requires an Enterprise license and a configured AI provider (apiKey + apiEndpoint).

Configuration

{
  "a11yinspect.licenseKey": "",
  "a11yinspect.runOnSave": false,
  "a11yinspect.runOnOpen": false,
  "a11yinspect.ignore": [],
  "a11yinspect.rootElement": "",
  "a11yinspect.hideElements": "",
  "a11yinspect.intellisense.enabled": true,
  "a11yinspect.intellisense.showHover": true,
  "a11yinspect.showFail": true,
  "a11yinspect.showValidate": true,
  "a11yinspect.showSuggestions": true,
  "a11yinspect.showPasses": false
}

Settings

AI Settings

Azure OpenAI endpoints (containing .openai.azure.com) are auto-detected and use the api-key header. All other endpoints use Authorization: Bearer.

CLI Tool (Enterprise)

The CLI requires an Enterprise license key. Provide it via --license-key=<key> argument or the A11YINSPECT_LICENSE_KEY environment variable.

Usage

# Static file analysis
a11yinspect --license-key=YOUR_KEY "src/**/*.html"
a11yinspect --license-key=YOUR_KEY --format=sarif --output=a11y-report.sarif "**/*.html"

# URL crawling (scan live website)
a11yinspect --license-key=YOUR_KEY --crawl --url=https://example.com --max-pages=100

# With reporters
a11yinspect --license-key=YOUR_KEY --github --fail-on=error "src/**/*.{html,jsx,tsx}"

CLI Options

Options:
  -h, --help                Show help message
  -v, --version             Show version number
  --license-key=<key>       Enterprise license key (or set A11YINSPECT_LICENSE_KEY)
  --config=<path>           Path to config file (default: a11yinspect.config.json)
  --format=<format>         Output format: json, junit, sarif, html, console
  --output=<path>           Output file path
  --severity=<level>        Minimum severity: error, warning, notice, pass
  --fail-on=<level>         Fail CI on: error, warning, notice, none
  --ignore=<codes>          Comma-separated rule codes to ignore
  --exclude=<patterns>      Comma-separated patterns to exclude

URL Crawling:
  --crawl                   Enable URL crawling mode
  --url=<url>               URL to crawl (can specify multiple times)
  --max-pages=<n>           Maximum pages to crawl (default: 50)
  --depth=<n>               Maximum crawl depth (default: 3)
  --follow-links            Follow links within same domain
  --wait-time=<ms>          Wait time for page load (default: 1000)
  --viewport=<WxH>          Viewport size (default: 1280x720)

Reporters (opt-in, only enabled ones run):
  --github                  Enable GitHub reporter (uses GITHUB_TOKEN)
  --github-annotations      Add PR annotations
  --github-grouped          Use grouped issue mode
  --jira=<url>              Jira base URL (uses JIRA_TOKEN)
  --jira-project=<key>      Jira project key
  --api=<url>               Custom API endpoint URL
  --api-token=<token>       API bearer token

Reporters are opt-in — only the ones you explicitly pass will run. For example, --github alone enables only GitHub Issues without Jira or API reporting. See CI/CD Documentation for details.

Output Formats

GitHub Action (Enterprise)

name: Accessibility Check

on: [push, pull_request]

jobs:
  a11y:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: barrierbreak/a11yinspect@v1
        with:
          license-key: ${{ secrets.A11YINSPECT_LICENSE_KEY }}
          files: 'src/**/*.{html,jsx,tsx}'
          format: sarif
          output: a11y-report.sarif
          fail-on: error

See CI/CD Documentation for detailed setup instructions including Jenkins, GitLab CI, and reporter configuration.

License

Proprietary - see LICENSE file for the full End User License Agreement.

Credits

Developed by BarrierBreak.