Skip to content

v0.4.0

Release Date: 2026-07-11

Highlights

  • Agent-Optimized Output - Default JSON format designed for coding agents with actionable fix patterns
  • Source Code Mapping - Map DOM findings to source file locations via source maps
  • Validation Delta - Compare before/after audits to enable autonomous fix loops
  • Project-Specific Fixes - Configure team fix patterns in ~/.plexusone/a11y/fixes.yaml

Overview

This release transforms agent-a11y into a fully agent-ready accessibility tool. The default output is now structured JSON with actionable fix patterns that coding agents (Claude Code, Kiro, Codex, etc.) can directly apply. Source mapping enables agents to locate the exact file and line to edit, while validation delta enables the autonomous fix loop: audit → fix → validate → repeat.

What's New

Agent-Optimized Output

The CLI and MCP tools now output agent-optimized JSON by default:

# Agent-optimized JSON (default)
agent-a11y audit https://example.com

# Human-readable output
agent-a11y audit https://example.com --human

Output includes:

  • Fix Patterns - Actionable guidance (add attribute, modify style, etc.)
  • Token Suggestions - Design system tokens for compliant values
  • GO/WARN/NO-GO Status - Simple pass/fail for CI/CD workflows

Source Code Mapping

Map DOM findings to source file locations using source maps:

agent-a11y audit https://localhost:3000 --source-map ./dist/

Output includes source locations:

{
  "element": {
    "selector": "img.hero-image",
    "source": {
      "file": "src/components/Hero.tsx",
      "line": 42,
      "component": "Hero",
      "framework": "react"
    }
  }
}

Supports React, Vue, Svelte, and Angular framework detection.

Validation Delta

Compare before/after audits to track fix progress:

# Create baseline
agent-a11y validate https://example.com --save-baseline -o baseline.json

# Validate after fixes
agent-a11y validate https://example.com --baseline baseline.json

# CI mode: fail on regressions
agent-a11y validate https://example.com --baseline baseline.json --fail-on-regression

Output includes:

  • Fixed - Issues that were resolved
  • Remaining - Issues still present
  • Regressions - New issues introduced
  • Status - FIXED, IMPROVED, NO_CHANGE, REGRESSED, or MIXED

Project-Specific Fix Configuration

Configure team fix patterns in ~/.plexusone/a11y/fixes.yaml:

version: "1.0"

projects:
  - match: "*/mycompany/dashboard-*"
    language: react
    framework: next
    components:
      Button:
        selectors: [".btn", "[data-component='button']"]
        fixes:
          - rule: button-name
            pattern: '<Button aria-label="...">'

languages:
  react:
    patterns:
      image-alt:
        component: Image
        import: "next/image"
        example: '<Image alt="..." />'

CLI commands:

# Show resolved configuration
agent-a11y config show

# Create default configuration
agent-a11y config init

Design System Integration

Specify a design system spec for token-aware suggestions:

agent-a11y audit https://example.com --design-system ./design-system/

Token suggestions include:

  • Color tokens that meet contrast requirements
  • Spacing tokens for target size compliance
  • Typography tokens for text spacing

New Types

Type Description
AgentFinding Finding with element context and remediation
AgentResult Full audit result with summary and status
AgentRemediation Fix patterns and token suggestions
SourceLocation File, line, column, component, framework
ValidationDelta Before/after comparison result
FixedFinding Resolved issue with fingerprint
ProjectPattern Project-specific fix pattern

New CLI Commands

Command Description
validate Validate fixes against baseline
config show Show resolved project configuration
config init Create default fixes.yaml

New CLI Flags

Flag Command Description
--human audit Human-readable output instead of agent JSON
--design-system audit Path to design system spec
--source-map audit Path to source map directory
--baseline validate Baseline file to compare against
--expect-fixed validate Rule IDs expected to be fixed
--fail-on-regression validate Exit 1 if regressions detected
--save-baseline validate Save audit as baseline

Installation

go install github.com/plexusone/agent-a11y/cmd/agent-a11y@v0.4.0

Documentation

Autonomous Fix Loop

With v0.4.0, agent-a11y enables fully autonomous accessibility remediation:

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│   IDENTIFY   │────▶│     FIX      │────▶│   VALIDATE   │────┐
│              │     │              │     │              │    │
│ agent-a11y   │     │ coding agent │     │ agent-a11y   │    │
│ audit        │     │ applies fix  │     │ validate     │    │
└──────────────┘     └──────────────┘     └──────────────┘    │
       ▲                                                      │
       └──────────────────────────────────────────────────────┘
                          (loop until FIXED)