ARC Templated Accessibility Issues

Pre-written accessibility issue templates for iOS, Android, and Web, maintained by the ARC Accessibility Resource Center. These templates are designed to standardize how accessibility defects are documented and filed across platforms, ensuring consistent severity ratings, reproduction steps, code references, and remediation guidance.

Purpose

Manually writing accessibility issues from scratch is time-consuming and inconsistent. These templates give testers and engineers a reliable starting point — with pre-filled issue descriptions, WCAG references, how-to-fix guidance, and testing steps — so teams can file high-quality bugs faster.

Structure

arc-templated-issues/
├── web/                          # Web platform templates
├── native/                       # iOS and Android platform templates
├── public/                       # Combined output docs (generated)
│   ├── web-issue-templates.md
│   └── native-issue-templates.md
├── scripts/
│   └── build-combined-doc.js     # Script to regenerate public/ docs
├── arc-accessibility-issue-template.md   # Base template structure
├── template-mappings.json        # Maps axe-core rule IDs to templates
└── template-mappings.schema.json # JSON schema for template-mappings.json

Platforms

| Platform | Status | |----------|--------| | Web | Active | | iOS | Active | | Android | Active |

Template Format

Each template follows a standard structure:

• Severity — Critical / Severe / Average / Low
• Suggested Priority — Blocker / High / Medium / Low
• Steps to reproduce
• Element — Where the issue appears in the UI
• What is the issue — Description, including screen reader announcement impact
• Why it is important — User impact and business rationale
• Code reference — Snippet of the offending code
• How to fix — Remediation guidance
• Compliant code example — Corrected code snippet
• How to test — Automated and manual testing steps
• MagentaA11y — Links to relevant MagentaA11y criteria
• WCAG — Applicable success criteria and conformance level
• Operating system / Browser / Assistive technology — Environment details

Web Templates

| Template | Mapped axe-core Rules | |----------|-----------------------| | Control lacks a label in the code | button-name, link-name, label, aria-label rules, and more | | Heading levels incorrectly nested | heading-order, empty-heading, page-has-heading-one | | Images should be marked as decorative | image-alt, role-img-alt, svg-img-alt, and more | | Interactive element is not keyboard accessible | tabindex, scrollable-region-focusable, nested-interactive, and more |

The full axe-core rule-to-template mapping is defined in template-mappings.json.

Native Templates

| Template | |----------| | Button lacks a label in the code | | Focus order is not logical | | Heading trait is not used in the code | | Image/icon should be marked as decorative | | Items should be grouped | | State is not communicated for button |

Building the Combined Docs

The public/ folder contains pre-built markdown files that merge all templates by platform. To regenerate them after adding or editing templates:

node scripts/build-combined-doc.js

This outputs:

• public/web-issue-templates.md
• public/native-issue-templates.md

npm Package

This repo is published to npm as arc-templated-issues. Any project can consume the templates directly:

npm install arc-templated-issues

Published contents:

| Path | Description | |------|-------------| | public/web-issue-templates.md | All web templates merged into one file | | public/native-issue-templates.md | All native templates merged into one file | | web/*.md | Individual web templates | | native/*.md | Individual native templates | | arc-accessibility-issue-template.md | Base template structure | | template-mappings.json | axe-core rule ID → template mappings |

Releasing a new version

npm run release:patch   # bug fixes / content updates → 1.0.x
npm run release:minor   # new templates added → 1.x.0
npm run release:major   # breaking changes → x.0.0

Each release:* script rebuilds public/ from the source templates, bumps the version, and publishes.

Usage

1. Identify the accessibility issue you are filing.
2. Find the matching template in the relevant platform folder (web/ or native/).
3. Copy the section below the -------- copy below --------- divider into your issue tracker.
4. Fill in the ###### placeholders with issue-specific details.
5. Remove any tester notes (lines beginning with ## Tester note:) before filing.

Contributing

Templates are owned and maintained by the ARC Accessibility Resource Center. To propose a new template or suggest changes to an existing one, open a merge request with your changes and a brief description of the accessibility issue it addresses.

New templates should follow the base structure in arc-accessibility-issue-template.md and include at minimum: severity, WCAG mapping, how-to-fix guidance, a compliant code example, and a MagentaA11y reference where applicable.