---

name: a11y-issue-writer description: Format accessibility violations into standardized, JIRA-ready issue reports using the accessibility-issues-template-mcp. Use this skill when users want to write accessibility issues, format axe-core violations as tickets, create accessibility bug reports, generate issue templates from test results, or convert violations to standardized formats. Triggers on requests like "write issues for these violations", "format as JIRA tickets", "create accessibility bug reports", or "generate issue from axe results".

Accessibility Issue Writer

Format accessibility violations into standardized issue reports using the accessibility-issues-template-mcp.

Prerequisites

Requires the accessibility-issues-template-mcp server configured in your IDE.

Repository: github.com/joe-watkins/accessibility-issues-template-mcp

Verify these tools are available:

• format_axe_violation
• list_issue_templates
• get_issue_template
• validate_issue

Workflow

1. Receive violations - Accept axe-core violations array or individual violation objects
2. Format each violation - Call format_axe_violation with violation data and context
3. Output formatted issues - Present issues in requested format (markdown, JIRA, etc.)

MCP Tools

format_axe_violation

Convert a single axe-core violation to a formatted issue report.

Copyformat_axe_violation(
  violation: {
    id: "color-contrast",
    impact: "serious",
    tags: ["wcag2aa", "wcag143"],
    description: "Ensures contrast between foreground and background colors meets WCAG 2 AA thresholds",
    help: "Elements must have sufficient color contrast",
    helpUrl: "https://dequeuniversity.com/rules/axe/4.8/color-contrast",
    nodes: [{ html: "<p class='low-contrast'>...</p>", target: [".low-contrast"] }]
  },
  context: {
    url: "https://example.com",
    browser: "Chromium",
    operatingSystem: "Windows"
  }
)

list_issue_templates

List all 28+ available issue templates.

Copylist_issue_templates()

get_issue_template

Retrieve a specific template by axe rule ID.

Copyget_issue_template(templateName: "color-contrast")

validate_issue

Check formatted issue for completeness.

Copyvalidate_issue(issue: { /* formatted issue object */ })

Input Formats

Full axe-core Results

When receiving complete axe-core output, iterate over the violations array:

Copy// From axe.run() results
results.violations.forEach(violation => {
  format_axe_violation(violation, context)
})

Single Violation

Format individual violations as received:

Copyformat_axe_violation(violation: singleViolation, context: contextObject)

Manual Input

For manually reported issues, use get_issue_template to get the appropriate template structure:

Copyget_issue_template(templateName: "button-name")

Output Format

Each formatted issue includes:

• Title: Rule name and brief description
• Severity: Mapped from axe impact (critical/serious/moderate/minor)
• URL/Path: Where the issue was found
• Steps to reproduce: Navigation instructions
• Element: Description and location
• What is the issue: Specific failure description
• Why it is important: User impact explanation
• Code reference: Failing HTML snippet
• How to fix: Remediation guidance
• Compliant code example: Fixed HTML snippet
• How to test: Automated and manual verification steps
• Resources: Deque University link, WCAG reference

Severity Mapping

Batch Processing

When processing multiple violations:

1. Group by rule - Combine similar violations
2. Order by severity - Critical first, then serious, moderate, minor
3. Number sequentially - Issue #1, Issue #2, etc.

Example output structure:

Copy# Accessibility Issues Report

**URL:** https://example.com
**Total Issues:** 12

## Critical (2 issues)

### Issue #1: color-contrast - Insufficient contrast ratio
[formatted issue content]

### Issue #2: button-name - Button missing accessible name
[formatted issue content]

## Serious (5 issues)
...

Integration with Other Skills

This skill is called by a11y-tester after running axe-core tests. It can also be invoked directly with violations from any source.

From a11y-tester:

Copy1. a11y-tester runs axe-core → collects violations
2. a11y-tester delegates to a11y-issue-writer → formats issues
3. Output: Summary + formatted issues

Standalone usage:

CopyUser provides violations → a11y-issue-writer formats → Output issues