arc-templated-issues 1.0.0

package/README.md

@@ -0,0 +1,126 @@
+# 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](web/control-lacks-a-label-in-the-code.md) | `button-name`, `link-name`, `label`, `aria-label` rules, and more |
+| [Heading levels incorrectly nested](web/heading-levels-incorrectly-nested.md) | `heading-order`, `empty-heading`, `page-has-heading-one` |
+| [Images should be marked as decorative](web/images-should-be-marked-as-decorative.md) | `image-alt`, `role-img-alt`, `svg-img-alt`, and more |
+| [Interactive element is not keyboard accessible](web/interactive-element-is-not-keyboard-accessible.md) | `tabindex`, `scrollable-region-focusable`, `nested-interactive`, and more |
+
+The full axe-core rule-to-template mapping is defined in [`template-mappings.json`](template-mappings.json).
+
+## Native Templates
+
+| Template |
+|----------|
+| [Button lacks a label in the code](native/button-lacks-a-label-in-the-code.md) |
+| [Focus order is not logical](native/focus-order-is-not-logical.md) |
+| [Heading trait is not used in the code](native/heading-trait-is-not-used-in-the-code.md) |
+| [Image/icon should be marked as decorative](native/image-icon-should-be-marked-as-decorative.md) |
+| [Items should be grouped](native/items-should-be-grouped.md) |
+| [State is not communicated for button](native/state-is-not-communicated-for-button.md) |
+
+## 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:
+
+```bash
+node scripts/build-combined-doc.js
+```
+
+This outputs:
+- [`public/web-issue-templates.md`](public/web-issue-templates.md)
+- [`public/native-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:
+
+```bash
+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
+
+```bash
+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`](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.

package/arc-accessibility-issue-template.md

@@ -0,0 +1,83 @@
+[Severity]
+Critical
+Severe
+Average
+Low
+
+[Priority]
+Blocker
+High
+Medium
+Low
+
+[URL/Path]
+######
+
+[Steps to reproduce]  
+######
+
+[Element] 
+(## Tester note: Describe where the thing is in the UI and delete me ##) 
+
+[What is the issue] 
+(## Tester note: If the issue has screen reader impact - clearly describe announcements and delete me - if no screen reader impact, delete the announcement content below for that issue. ##)
+
+###### 
+
+Screen reader announcement (currently) is: "x...."
+Ideal announcement would be: "x ..."
+
+
+[Why it is important] 
+###### 
+
+[Code reference] 
+(## Tester note: Code references can be very helpful here to support screenshots and the reset of the issue – delete me ##)
+{code:html} 
+... 
+{code}
+
+[How to fix]  
+###### 
+
+[Compliant code example]
+(## Tester note: n/a here if not applicable - this could be a fixed/tailored code fragment pulled from Code Reference - code formatting options: code:html, code:css, code:swift, code:java ##)
+{code:html} 
+... 
+{code} 
+
+[How to test] 
+Automated: ######
+Manual: ######
+
+[MagentaA11y] 
+###### Links to MagentaA11y pages
+
+[Resources]
+######
+
+[WCAG] 
+###### Format: x.x.x Success Criterion (A or AA)
+
+[Operating system] 
+Windows
+MacOS
+iOS
+Android
+
+[Build Version]
+###### E.g. 10.6.0
+
+[Browser]
+Chrome
+Safari
+Firefox
+Edge
+
+[Assistive technology] 
+Keyboard
+JAWS
+NVDA
+VoiceOver
+TalkBack
+Zoom/Text Resize 

package/native/button-lacks-a-label-in-the-code.md

@@ -0,0 +1,75 @@
+# Button lacks a label in the code
+
+## Severity
+1-Critical
+
+## Suggested Priority
+Blocker
+
+-------- copy below ---------
+
+[Path]  
+######
+
+[Steps to reproduce]  
+######
+
+[Element] 
+The ##### button located #####
+
+[What is the issue] 
+The ##### button does not have an accessible label in the code, resulting in screen readers announcing it as "button" without context. This issue occurs when buttons are missing labels via accessibility properties like {{contentDescription}} (Android) or {{.accessibilityLabel}} (iOS).
+
+[Why it is important]  
+Accessible labels provide critical information about a button's purpose, enabling users of assistive technologies [such as voice recognition and screen readers] to navigate and interact with the application effectively. Without labels, users may face difficulties understanding what actions buttons will perform, leading to frustration and limited functionality.
+
+[How to fix]  
+- On iOS, set a descriptive {{.accessibilityLabel}} for each button.
+- On Android, use the {{contentDescription}} property to provide meaningful labels.
+- Ensure the label is concise and accurately describes the button's function (e.g., "Submit," "Back," or "Search").
+
+[Compliant code example]  
+iOS
+{code:swift}
+Button(action: { /* action */ }) {
+    Text("Submit")
+}
+.accessibilityLabel("Submit, any additional context")
+{code}
+
+Android
+{code:java}
+Button(onClick = { /* action */ }) {
+    Text("Submit")
+}.semantics { contentDescription = "Submit, any additional context" }
+{code}
+
+[How to test]  
+- Screen reader testing: Enable VoiceOver (iOS) or TalkBack (Android) and navigate to the buttons. Verify that each button is announced with a clear and accurate label.
+- Manual inspection: Check the code to confirm that all buttons include appropriate accessibility properties like {{.accessibilityLabel}} or {{contentDescription}}.
+
+[MagentaA11y]  
+https://www.magentaa11y.com/checklist-native/button/
+
+[Resources]
+######
+
+[WCAG]  
+(## Tester note: Choose or add and delete me ##)
+2.4.6: Headings and Labels (AA)
+2.5.3: Label in Name (AA)
+4.1.2 Name, Role, Value (A)
+
+[Operating system]  
+(## Tester note: Choose one and delete me ##)
+iOS
+Android
+
+[Build Version]
+###### E.g. 10.6.0
+
+[Assistive technology]  
+(## Tester note: Choose one and delete me ##)
+VoiceOver
+TalkBack
+Keyboard

package/native/focus-order-is-not-logical.md

@@ -0,0 +1,69 @@
+# Focus order is not logical
+
+## Severity
+2-Severe
+
+## Suggested Priority
+High
+
+-------- copy below ---------
+
+[URL/Path]  
+######
+
+[Steps to reproduce]  
+######
+
+[Element] 
+(## Tester note: Describe where the thing is in the UI and delete me ##)
+
+[What is the issue] 
+(## Tester note: Add to this content below describing the focus order — delete me ##)
+The screen reader focus order does not follow a logical order. In this case, the focus order ######
+
+[Why it is important]  
+Logical focus order ensures that users relying on screen readers can navigate the interface efficiently and understand the contextual relationships between elements. When focus order is disrupted, it creates barriers for users with visual impairments or motor disabilities, leading to frustration and reduced usability.
+
+[Code reference]  
+(## Tester note: Code references can be very helpful here to support screenshots and the rest of the issue — n/a if not applicable or no access to codebase, delete me ##)
+{code:swift}
+...
+{code}
+
+[How to fix]  
+(## Tester note: If needed add to this content to describe expected focus order ##)
+- Review the order of focusable elements and ensure it follows a logical and expected progression that matches the visual layout and intended user flow.
+- Ensure the elements that should receive focus are enabled for accessibility. e.g. {{isAccessibilityElement}} in iOS and {{importantForAccessibility}} in Android.
+- If the natural screen's focus order needs to be overridden, consider accessibility tools specific to the platform (e.g., {{accessibilityTraversalOrder}} for Android or adjusting the {{UIAccessibilityContainer}} for iOS).
+- Make sure hidden elements or off-screen controls are not included in the focus order.
+
+[Compliant code example]  
+(## Tester note: n/a here if not applicable — code formatting options: code:html, code:css, code:swift, code:java ##)
+{code:swift}
+...
+{code}
+
+[How to test]  
+Automated: Use tools like Android Accessibility Scanner or iOS Accessibility Inspector to detect potential focus order issues.
+Manual: Navigate the app using a screen reader (VoiceOver or TalkBack) and verify that the focus moves sequentially in a way that matches the visual and functional layout. Ensure that the meaning of the content makes sense.
+
+[MagentaA11y]  
+https://www.magentaa11y.com/checklist-native/focus/
+
+[Resources]
+######
+
+[WCAG]  
+2.4.3 Focus Order (A)
+1.3.2 Meaningful Sequence (A)
+
+[Operating system]  
+iOS
+Android
+
+[Build Version]
+###### E.g. 10.6.0
+
+[Assistive technology]  
+VoiceOver
+TalkBack

package/native/heading-trait-is-not-used-in-the-code.md

@@ -0,0 +1,74 @@
+# Heading Trait is not used in the code
+
+## Severity
+3-Average
+
+## Suggested Priority
+Medium
+
+-------- copy below ---------
+
+[Path]  
+######
+
+[Steps to reproduce]  
+######
+
+[Element] 
+The ##### large text located #####
+
+[What is the issue] 
+The large text ##### does not own the Header Trait. This issue occurs when {{UIAccessibilityTraits.header}} (iOS) or {{AccessibilityHeading}} (Android) is not applied to a text element serving as a heading.
+
+[Why it is important]  
+A heading provides semantic structure that allows users of screen readers to navigate content quickly and understand the hierarchy of information within the screen. Without a properly marked heading, users must navigate linearly, which is time-consuming and frustrating, and they will have less of an understanding of how the content is organized on the screen.
+
+[How to fix]  
+- Ensure the heading is logical, concise, and represents the hierarchy of content.
+- On iOS, apply the {{.accessibilityTraits}} property with the .header value to the text element.
+- On Android, use the setHeading() method or AccessibilityHeading property to define the heading role for the element.
+
+[Compliant code example]  
+iOS
+{code:swift}
+Text("Section Title")
+    .font(.title)
+    .accessibilityAddTraits(.isHeader)
+{code}
+
+Android
+{code:java}
+Text(
+    text = "Section Title",
+    modifier = Modifier.semantics { heading = true }
+)
+{code}
+
+[How to test]  
+Screen reader testing: Enable VoiceOver (iOS) or TalkBack (Android) and use heading navigation gestures. Confirm that the heading is announced and navigable in a logical order.
+Manual inspection: Review the code to ensure the heading is marked with appropriate accessibility traits.
+
+[MagentaA11y]  
+https://www.magentaa11y.com/checklist-native/headings/
+
+[Resources]
+######
+
+[WCAG]  
+(## Tester note: Choose or add and delete me ##)
+1.3.1 Info and Relationships (A)
+2.4.6 Headings and Labels (AA)
+
+[Operating system]  
+(## Tester note: Choose one and delete me ##)
+iOS
+Android
+
+[Build Version]
+###### E.g. 10.6.0
+
+[Assistive technology]  
+(## Tester note: Choose one and delete me ##)
+VoiceOver
+TalkBack
+Keyboard

package/native/image-icon-should-be-marked-as-decorative.md

@@ -0,0 +1,99 @@
+# Image/icon should be marked as decorative
+
+## Severity
+3-Average
+
+## Suggested Priority
+Medium
+
+-------- copy below ---------
+
+[URL/Path]  
+######
+
+[Steps to reproduce]  
+######
+
+[Element] 
+(## Tester note: Describe where the decorative image is in the UI and delete me ##)
+
+[What is the issue] 
+The following images do not meet the requirements for properly programmatically hidden decorative images:
+
+A caret icon is included within a table row/list item/blade. The caret icon is simply there for visual reinforcement, and it follows a visible text label. However, the caret icon is incorrectly read by a screen reader when swiping through the screen focus order.
+
+A battery icon is next to the text string of "Battery", where the text "Battery" provides an equivalent text alternative. However, the battery icon is not grouped together with the adjacent text and the battery icon announces with a long filename which is not meaningful to users.
+
+An image is used as a decorative design element to break up a page by visually signaling the introduction of the next section, and is not crucial to understanding the purpose or content of the page. However, the decorative layout image is still read by a screen reader.
+
+[Why it is important]  
+Proper hiding or presentational status on decorative images is important in ensuring that extraneous auditory noise is not generated for assistive technology users. When images which are not intended to convey information are not programmatically hidden, then assistive technology (AT) may try to announce a filename which is not meaningful. This issue impacts cognitive users, low vision users and non-sighted users who navigate the screen using assistive technology such as screen readers and braille readers. WCAG 1.1.1 (Non-Text Content) requires that images which are decorative, incidental, or used strictly for layout/positioning be programmatically hidden from assistive technology.
+
+[Code reference]  
+(## Tester note: iOS and Android image attributes for decorative, hidden, or null go here – delete me ##)
+{code:swift}
+...
+{code}
+
+[How to fix]  
+Ensure that decorative images and icons are programmatically hidden. Use the correct function to hide the decorative image or icon.
+
+[Compliant code example]  
+(## Tester note: n/a here if not applicable and is a design change and delete me ##)
+
+**Android — XML**
+Use `android:importantForAccessibility="no"` to ensure that the image is not considered for accessibility purposes. This will prevent TalkBack from announcing the image.
+
+**Android — Jetpack Compose**
+Set `contentDescription = null` for decorative elements to ensure that the content description is not announced by TalkBack.
+{code:java}
+Image(
+    painter = painterResource(id = R.drawable.decorative_image),
+    contentDescription = null
+)
+{code}
+
+**iOS — SwiftUI**
+Use the modifier `.accessibilityHidden(true)` to hide an icon or image from VoiceOver, Full Keyboard Access, and Switch Control.
+Use the `Image(decorative:)` initializer to mark an image as purely decorative. This ensures the image is not announced by VoiceOver, not focusable by Full Keyboard Access or Switch Control, and not included in the accessibility tree.
+{code:swift}
+Image(decorative: "decorative_image")
+// or
+Image("decorative_image")
+    .accessibilityHidden(true)
+{code}
+
+**iOS — UIKit**
+Use `imageView.isAccessibilityElement = false` to ensure the image view is ignored by VoiceOver, meaning it won't be announced or focusable.
+
+[How to test]  
+Automated:
+- Not Applicable
+
+Manual:
+- Inspect the screen to identify images which have adjacent text descriptions or are non-essential.
+- Navigate through the screen by swiping right and left using a screen reader in order to locate images. Follow along visually as images are announced to confirm whether the image is decorative versus providing content.
+- Review the list of decorative images to ensure that each uses a valid programmatic hidden, decorative, or null description value.
+
+[MagentaA11y] 
+https://www.magentaa11y.com/checklist-native/image-decorative/
+
+[Resources]
+Decorative Images
+https://www.w3.org/WAI/tutorials/images/decorative/
+
+Android Developers: Decorative Images
+https://developer.android.com/guide/topics/ui/accessibility/principles#decorative
+
+[WCAG]  
+1.1.1 Non-text Content (Level A)
+
+[Operating system]  
+######
+
+[Build Version]
+######
+
+[Assistive technology]  
+VoiceOver
+TalkBack

package/native/items-should-be-grouped.md

@@ -0,0 +1,71 @@
+# Items should be grouped
+
+## Severity
+3-Average
+
+## Suggested Priority
+Medium
+
+-------- copy below ---------
+
+[URL/Path]  
+######
+
+[Steps to reproduce]  
+######
+
+[Element] 
+(## Tester note: Describe where the thing is in the UI and delete me ##)
+
+[What is the issue]  
+Related items are not properly grouped, which impacts the navigation and understanding for users relying on screen readers and braille displays or keyboards.
+
+[Why it is important]  
+Grouping can help to better communicate the relationships of interactive elements such as interdependent controls, as well as non-interactive elements such as images that combine to make a larger group. Proper grouping reduces the need for excessive swipes or navigation actions and users can quickly understand and interact with related elements without needing to swipe through scattered content. This improves the overall efficiency of navigating the app, making it less tiring and more user-friendly for individuals with visual impairments. Lastly, proper groupings provide users with a larger touch target area.
+
+[Code reference]
+- In SwiftUI, group multiple elements with the `.accessibilityElement(children:)` modifier and with the `.combine` option on a parent view.
+- In Jetpack Compose, group elements by using `mergeDescendants`.
+- For Android Views, group all the relevant content elements in a single layout ViewGroup and set `android:importantForAccessibility="yes"` on that ViewGroup.
+
+[How to fix]  
+(## Tester note: If needed add to this content to describe expected grouping ##)
+- Review the order of focusable/swipeable elements and ensure related elements are logically grouped.
+
+[Compliant code example]
+(## Tester note: n/a here if not applicable — code formatting options: code:swift, code:java ##)
+{code:swift}
+...
+{code}
+
+[How to test] 
+- Automated: Use tools like Android Accessibility Scanner or iOS Accessibility Inspector to detect missing or incorrect groupings.
+- Manual: Use a screen reader (VoiceOver on iOS, TalkBack on Android) to navigate through the app. Ensure that related elements (e.g., buttons, form fields) are announced together and in the correct order. Pay close attention to how many swipes are needed to navigate between logically grouped items compared to disorganized ones. Ensure that users can reach related items with fewer actions.
+
+[MagentaA11y] 
+https://www.magentaa11y.com/checklist-native/focus/
+
+[Resources]
+- Android Developers: Groups of Related Content
+  https://developer.android.com/guide/topics/ui/accessibility/principles#content-groups
+- Accessibility group in Jetpack Compose
+  https://appt.org/en/docs/jetpack-compose/samples/accessibility-group
+- Accessibility Group on iOS
+  https://appt.org/en/docs/ios/samples/accessibility-group
+- Accessibility Group on React Native
+  https://appt.org/en/docs/react-native/samples/accessibility-group
+
+[WCAG]  
+1.3.1 Info and Relationships (A)
+3.3.2 Labels or Instructions (A)
+
+[Operating system]  
+iOS
+Android
+
+[Build Version]
+###### E.g. 10.6.0
+
+[Assistive technology]  
+VoiceOver
+TalkBack

package/native/state-is-not-communicated-for-button.md

@@ -0,0 +1,76 @@
+# State is not communicated for button
+
+## Severity
+2-Severe
+
+## Suggested Priority
+High
+
+-------- copy below ---------
+
+[Path]  
+######
+
+[Steps to reproduce]  
+######
+
+[Element] 
+The ##### button located #####
+
+[What is the issue]  
+The ##### control with a dynamic state of ##### does not communicate its state to screen reader users.
+
+[Why it is important]  
+State communication is essential for users of screen readers to understand the current functionality of the button. Without it, users may be unaware of the button's active or inactive state, leading to confusion and difficulty in completing tasks.
+
+For example, a toggle button might not announce whether it is currently "On" or "Off," or a navigation bar button may not announce as "Selected" or "Active."
+
+[How to fix]  
+- Use native controls and State will naturally be communicated.
+- For a toggle button, ensure states like "selected," "pressed," or "disabled" are programmatically exposed using platform-specific APIs.
+- On iOS, use {{.accessibilityValue}} to indicate the current state of the button (e.g., "On" or "Off").
+- On Android, set the {{contentDescription}} dynamically to reflect the button's state, or use accessibility APIs like {{AccessibilityNodeInfo.setText()}} to provide state information.
+
+[Compliant code example]  
+iOS
+{code:swift}
+Toggle("Enable Feature", isOn: $isOn)
+    .accessibilityValue(isOn ? "On" : "Off")
+{code}
+
+Android
+{code:java}
+val isChecked = remember { mutableStateOf(false) }
+Checkbox(
+    checked = isChecked.value,
+    onCheckedChange = { isChecked.value = it },
+    modifier = Modifier.semantics { contentDescription = if (isChecked.value) "Checked" else "Unchecked" }
+)
+{code}
+
+[How to test]  
+- Screen reader testing: Enable VoiceOver (iOS) or TalkBack (Android) and activate the button. Confirm that the state change (e.g., "On" to "Off", "Selected", or "Active") is announced correctly based on the interaction.
+
+[MagentaA11y]  
+https://www.magentaa11y.com/checklist-native/button/
+
+[Resources]
+######
+
+[WCAG]  
+4.1.2 Name, Role, Value (A)
+1.3.1: Info and Relationships (A)
+
+[Operating system]  
+(## Tester note: Choose one and delete me ##)
+iOS
+Android
+
+[Build Version]
+###### E.g. 10.6.0
+
+[Assistive technology]  
+(## Tester note: Choose one and delete me ##)
+VoiceOver
+TalkBack
+Keyboard