arc-templated-issues 1.0.0

package/template-mappings.json

@@ -0,0 +1,58 @@
+{
+  "$schema": "./template-mappings.schema.json",
+  "version": "1.0.0",
+  "description": "Maps AxeCore rule IDs to accessibility issue templates",
+  "mappings": {
+    "control-lacks-a-label-in-the-code.md": {
+      "rules": [
+        "button-name",
+        "input-button-name",
+        "link-name",
+        "label",
+        "select-name",
+        "summary-name",
+        "aria-command-name",
+        "aria-input-field-name",
+        "aria-toggle-field-name",
+        "aria-meter-name",
+        "aria-progressbar-name",
+        "aria-tooltip-name",
+        "aria-treeitem-name",
+        "aria-dialog-name",
+        "label-title-only"
+      ],
+      "description": "Controls and form elements lacking accessible labels or names"
+    },
+    "heading-levels-incorrectly-nested.md": {
+      "rules": [
+        "heading-order",
+        "empty-heading",
+        "page-has-heading-one"
+      ],
+      "description": "Heading hierarchy and structure issues"
+    },
+    "images-should-be-marked-as-decorative.md": {
+      "rules": [
+        "image-alt",
+        "role-img-alt",
+        "svg-img-alt",
+        "input-image-alt",
+        "object-alt",
+        "area-alt",
+        "image-redundant-alt"
+      ],
+      "description": "Images missing alternative text or improperly marked"
+    },
+    "interactive-element-is-not-keyboard-accessible.md": {
+      "rules": [
+        "tabindex",
+        "scrollable-region-focusable",
+        "nested-interactive",
+        "frame-focusable-content",
+        "accesskeys"
+      ],
+      "description": "Interactive elements with keyboard accessibility issues"
+    }
+  },
+  "defaultTemplate": "arc-accessibility-issue-template.md"
+}

package/template-mappings.schema.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Template Mappings Schema",
+  "description": "Schema for mapping AxeCore rule IDs to accessibility issue templates",
+  "type": "object",
+  "properties": {
+    "version": {
+      "type": "string",
+      "description": "Version of the mappings configuration"
+    },
+    "description": {
+      "type": "string",
+      "description": "Description of this configuration file"
+    },
+    "mappings": {
+      "type": "object",
+      "description": "Map of template filenames to their rule configurations",
+      "patternProperties": {
+        ".*\\.md$": {
+          "type": "object",
+          "properties": {
+            "rules": {
+              "type": "array",
+              "description": "Array of AxeCore rule IDs that map to this template",
+              "items": {
+                "type": "string"
+              }
+            },
+            "description": {
+              "type": "string",
+              "description": "Human-readable description of what issues this template covers"
+            }
+          },
+          "required": ["rules"]
+        }
+      }
+    },
+    "defaultTemplate": {
+      "type": "string",
+      "description": "Default template to use when no specific mapping exists",
+      "pattern": ".*\\.md$"
+    }
+  },
+  "required": ["mappings", "defaultTemplate"]
+}

package/web/control-lacks-a-label-in-the-code.md

@@ -0,0 +1,81 @@
+# Control lacks a label in the code
+
+## Severity
+1-Critical
+
+## Suggested Priority
+Blocker
+
+-------- copy below ---------
+
+[URL/Path]
+######
+
+[Steps to reproduce]  
+######
+
+[Element] 
+The ##### located ##### 
+
+[What is the issue] 
+The ###### control lacks a label in the code making it difficult for screen reader users to understand its purpose. A meaningful label is not announced. 
+
+[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. 
+
+[Code reference] 
+(## Tester note: grab code snippet from experience and delete me ##) 
+{code:html} 
+<button></button> 
+{code} 
+
+[How to fix] 
+Ensure that the control has an accessible label. There are many ways this is defined in the code. The control’s nested text or alternative text of images within controls can be used as the accessible name of the control.  
+
+When on-screen text is not available, authors can use another method to provide an accessible name, such as by using {{aria-labelledby}}, {{aria-label}}, or {{title}} attribute (not recommended in all cases), to provide the accessible name. The {{aria-labelledby}} attribute must contain one or more IDs of elements that label the button. The aria-label attribute is best when there is no on-screen label. Authors should place the string that labels the form field in the aria-label attribute.  
+
+Authors can also identify an accessible name using an associated label element whenever an on-screen label is present. The label element's value is then explicitly associated with the relevant form field using the for and {{ID}} attributes. Use of the label element provides an added benefit as it increases the target area that users can click to focus the form field.  
+
+[Compliant code example] 
+(## Tester note: include real code example or just leave generic examples below and delete me ##) 
+{code:html} 
+<button>My Account</button> 
+{code} 
+
+{code:html} 
+<a href=”/facebook” aria-label=”Facebook”><svg>...</svg></button> 
+{code} 
+
+{code:html} 
+<span id=”example”>Some text</span> 
+<a href=”/facebook” aria-labelledby=”example”><svg>...</svg></button> 
+{code} 
+
+[How to test] 
+Screen reader testing: Use a screen reader to navigate to the control and verify that the correct label is announced. 
+
+Visual inspection: Ensure the button has a clear, descriptive label. Check that either {{aria-label}}, {{aria-labelledby}}, or {{title}} are present in the code, and that the label reflects the button's purpose.  
+
+Use the Chrome DevTools Accessibility Inspector to verify that the Name property has been properly calculated.  Open DevTools > Choose Accessibility Pane > Inspect element > review Computed Properties
+
+[MagentaA11y] 
+https://www.magentaa11y.com/how-to-test/link-button/ 
+https://www.magentaa11y.com/checklist-web/link/ 
+https://www.magentaa11y.com/checklist-web/button/ 
+
+[WCAG] 
+(## Tester note: Choose or add and delete me ##)
+2.4.4: Link Purpose (In Context) (A) 
+2.4.6: Headings and Labels (AA) 
+2.5.3: Label in Name (AA) 
+4.1.2 Name, Role, Value (A)
+
+[Operating system] 
+######
+
+[Browser]
+######
+
+[Assistive technology] 
+Keyboard 
+

package/web/heading-levels-incorrectly-nested.md

@@ -0,0 +1,121 @@
+# Heading levels incorrectly nested
+
+## Severity
+3-Average
+
+## Suggested Priority
+Medium
+
+-------- copy below ---------
+
+[URL/Path]
+######
+
+[Steps to reproduce]  
+######
+
+[Element] 
+(## Tester note: Describe where the heading is in the UI and delete me  ##)
+
+[What is the issue] 
+The following heading level nesting example does not meet the requirements for logically structured heading hierarchy: 
+
+The heading levels on this page are incorrectly nested, meaning that headings do not follow a logical order. For example, a {{<h3>}} may appear before a {{<h2>}}, or a {{<h4>}} may follow a {{<h2>}} without an appropriate {{<h3>}} in between. This disrupts the hierarchical structure of the page and makes it harder for users to understand the page content and navigate effectively.
+
+[Why it is important]
+Proper heading structure is crucial for accessibility as it helps assistive technologies, such as screen readers, understand and convey the relationships between different sections of content. Incorrectly nested headings can confuse users, making it difficult for them to grasp the organization of the page. This issue impacts people who rely on headings for navigation, especially those using screen readers or keyboard navigation, preventing them from efficiently moving through content. WCAG 1.3.1 (Info and Relationships) requires that information, structure, and relationships be conveyed clearly.
+
+[Code reference] 
+(## Tester note: CSS code references can be helpful here – delete me ##)
+{code:css}
+... 
+{code}
+
+[How to fix]  
+
+Ensure that heading levels are used in a logical, hierarchical order. For example:
+
+- An {{<h1>}}  should be the first heading on the page.
+
+- {{<h2>}} headings should follow {{<h1>}}, and {{<h3>}} should follow {{<h2>}}.
+
+- Do not skip heading levels (e.g., {{<h1>}} skipping to {{<h3>}} is incorrect; it should be {{<h1>}} then {{<h2>}} then {{<h3>}}).
+
+- A single heading should not use multiple levels of nested heading elements (e.g., {{<h1>}}T-Mobile {{<h3>}}iPhone Deals{{/h3}}{{/h1}} is incorrect; it should be simplified to use a single heading level {{<h1>}}T-Mobile iPhone Deals {{</h1>}}), and inner text can font sizing and styling be further customized using CSS styles.
+
+Use the correct HTML elements for headings: {{<h1>}}, {{<h2>}}, {{<h3>}}, etc. Avoid using styling (like font size) alone to create the appearance of a heading.
+
+Repeating patterns of headings are allowed so long as they follow a logical sequence (example: {{<h2>}},{{<h3>}},{{<h2>}},{{<h3>}})
+
+[Compliant code example]
+(## Tester note: n/a here if not applicable and is a design change and delete me ##)
+{code:html} 
+
+<h1>My favorite taco recipe</h1>
+
+<!-- Author's entire life story as it relates to tacos -->
+
+<h2>Ingredients</h2>
+
+<!-- List of ingredients -->
+
+<h2>Steps</h2>
+
+<h3>Preparing the protein</h3>
+
+<!-- List of instructions -->
+
+<h3>Preparing the vegetables</h3>
+
+<!-- List of instructions -->
+
+<h3>Assembly and plating</h3>
+
+<!-- List of instructions-->
+
+<h2>Nutrition information</h2>
+
+<!-- List of nutrition info -->
+
+<h2>Related recipes</h2>
+
+<!-- List of related recipes -->
+{code}
+
+[How to test]
+
+Automated:
+- Use an accessibility testing tool such as Axe DevTools or the Level Access extension to detect any heading structure issues. These tools will flag incorrect nesting of heading levels.
+
+- Follow-up with manual verification of the heading hierarchy in the HTML source code. (See Manual checks below.)
+
+Manual:
+
+- Inspect the page's HTML code to check the order of the heading elements (<h1>, <h2>, <h3>, etc.).
+
+- Navigate through the page using a screen reader or keyboard shortcuts (e.g., arrow keys or heading shortcut keys) to verify that headings are in a logical order and the page content is easy to understand.
+
+- Review the document structure using browser developer tools to ensure headings follow the correct hierarchy.
+
+[MagentaA11y] 
+
+https://www.magentaa11y.com/checklist-web/heading/
+
+[Resources]
+
+https://www.w3.org/WAI/tutorials/page-structure/headings
+
+[WCAG] 
+1.3.1 Info and Relationships (Level A)
+
+[Operating system] 
+######
+
+[Browser]
+######
+
+[Assistive technology] 
+######
+
+
+

package/web/images-should-be-marked-as-decorative.md

@@ -0,0 +1,79 @@
+# Images should be marked as decorative
+
+## Severity
+Low
+
+## Suggested Priority
+Low
+
+-------- 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] 
+The (## Tester note: describe image here – delete me ##) image/icon does not provide meaningful information, however, it is not marked as decorative. 
+
+[Why it is important] 
+When images are not properly marked as decorative, screen readers may announce them unnecessarily. This creates noise, cognitive overload, or potentially conveys incorrect information for users who are blind or rely on assistive technologies. Properly marking images as decorative ensures the images are skipped by assistive technologies, which provides a cleaner overall experience for screen reader users.
+
+[Code reference] 
+(## Tester note: CSS code references can be helpful here – delete me ##)
+{code} 
+... 
+{code}
+
+[How to fix]  
+
+Ensure standard {{<img>}} elements have an empty {{alt=””}} attribute or {{alt (null)}}.
+Ensure {{<svg>}}  elements have {{aria-hidden=”true” focusable="false"}} attributes. 
+[Compliant code example] 
+(## Tester note: n/a here if not applicable and is a design change and delete me ##)
+{code:html}
+
+ <img src="image.jpg" alt="">
+
+{code}
+
+{code:html}
+
+<svg aria-hidden="true">...</svg>
+
+{code}
+
+[How to test] 
+
+Automated: Use an automated scanning tool like Axe, Level Access, or Lighthouse to scan for images that are missing {{alt}} attributes. Decorative images still require an empty {{alt}} attribute, so if an image is missing an {{alt}} attribute all together it will be flagged by a scanner. A scanner will not flag images that should be treated as decorative, so manual testing is necessary.
+
+
+Manual: Use a screen reader (e.g., NVDA, JAWS, VoiceOver) to navigate to images on the page with your arrow keys, or try jumping directly to images with the NVDA/JAWS keyboard shortcut key {{G}}, or Voiceover keyboard shortcut keys {{VO key + Command + G}}. Ensure decorative images are being skipped over and not announced by the screen reader.
+
+[MagentaA11y] 
+www.magentaa11y.com/checklist-web/image-decorative/
+
+www.magentaa11y.com/how-to-test/images/
+
+[WCAG] 
+1.1.1 Non-Text Content (A)
+
+[Operating system] 
+######
+
+[Browser]
+######
+
+[Assistive technology] 
+JAWS
+NVDA
+VoiceOver
+
+[Additional Resources]
+
+https://www.w3.org/WAI/tutorials/images/decision-tree/
+

package/web/interactive-element-is-not-keyboard-accessible.md

@@ -0,0 +1,75 @@
+# Interactive element is not keyboard accessible
+
+## Severity
+1-Critical
+
+## Suggested Priority
+Blocker
+
+-------- copy below ---------
+
+[URL/Path]
+######
+
+[Steps to reproduce]  
+######
+
+[Element] 
+The ##### button located #####
+
+[What is the issue] 
+(## Tester note: choose one and delete me ##)
+The ###### is not keyboard accessible. Keyboard users are not able to reach the control in any way or activate it. 
+
+The ###### is not keyboard accessible. Keyboard users are able to reach the control, but nothing happens when those users try to activate the control.  
+
+[Why it is important]
+All functionalities must be operable using only a keyboard or similar input method. Some users rely exclusively on keyboards, screen readers, or alternative input devices, such as switch controls or adaptive keyboards, to navigate and interact with websites. Ensuring that all interactive elements, such as buttons, links, and form controls, can be accessed and activated via keyboard is very important for accessibility. Users with mobility or dexterity-related disabilities as well as screen reader users will benefit from keyboard accessible interfaces.
+
+[Code reference] 
+(## Tester note: show actual code and delete me ##)
+{code:html} 
+... 
+{code} 
+
+[How to fix]  
+- Ensure that all interactive elements are keyboard operable and allow for keyboard focus. Keyboard users should be able to tab to the control and activate it with the keyboard alone.  
+- Use an element that is naturally focusable such as a {{<button>}} or {{<a>}}. 
+- In cases where a negative {{tabindex}} has been used, remove {{tabindex="-1"}} from the element. 
+- Ensure the button does not own {{aria-hidden="true"}} 
+- Ensure anchor tags / links own valid {{href}} attribute values.
+
+[Compliant code example] 
+(## Tester note: show a real code fragment here or use generic examples below and delete me ##)
+{code:html} 
+<button>My Account</button> 
+{code}
+
+{code:html} 
+<a href=”/some-page”>Learn more about MagentaA11y</a> 
+{code}
+
+[How to test]
+Keyboard: Using the keyboard alone, tab to the control. Focus should move to the control. Try activating the control, the control should work with the enter key and spacebar if it is a button and just the enter key if it is a link.
+
+Manual inspection: Using Chrome DevTools, inspect the control and verify that the {{tabindex=”-1”}} and {{aria-hidden=”true”}} attributes are not present.
+
+[MagentaA11y]
+https://www.magentaa11y.com/how-to-test/keyboard-focus/ 
+https://www.magentaa11y.com/checklist-web/button/ 
+https://www.magentaa11y.com/checklist-web/link/ 
+
+[WCAG]
+(## Tester note: Choose or add and delete me ##)
+2.1.1 Keyboard (A) 
+2.4.3 Focus Order (A)
+
+[Operating system] 
+######
+
+[Browser]
+######
+
+[Assistive technology] 
+Keyboard 
+

package/web/wip-link-text-is-not-descriptive-or-lacks-purpose.md

@@ -0,0 +1,111 @@
+# [WIP] Link text is not descriptive or lacks purpose
+
+## Severity
+3-Average
+
+## Suggested Priority
+Medium
+
+(## Tester note: review guidance prior to logging issue ##)
+
+1) 1.3.1 Information & Relationships does NOT apply to buttons. Buttons can have repetitive names on the same page as long as they are doing the same action. Always inspect the code to learn whether something is coded as a link or button in HTML. `role="button"` on a link counts as a Button.
+
+2) If the link is nested within its related content within the same list item {{<li>}}, {{<p>}}, or table cell {{<td>}} then the link has programmatic determination and satisfies 1.3.1 Information & Relationships.
+
+-------- 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] 
+The ###### link text is not descriptive enough to convey its purpose or destination. For example, links such as "Shop now", "Buy now", "Click here", or "Read more" lack context when read independently.
+
+[Why it is important]  
+Descriptive link text improves navigation for all users, especially for people using assistive technologies such as screen readers. These users often navigate links out of context, so the purpose of each link must be clear without relying on surrounding content.
+
+When multiple links on a screen have the same visible text label but different targets, then providing distinguishing context becomes very important.
+
+Voice Recognition users benefit from having meaningful link purpose in the code so that they can activate controls by voice alone. Imagine saying "click 'Learn more'" and seeing that there are 6 options for voice control to choose from. This is the equivalent of making someone do multiple clicks to perform a single action!!
+
+[Code reference]  
+(## Tester note: CSS code references can be helpful here – delete me ##)
+{code:html}
+...
+{code}
+
+[How to fix]  
+Update the link text to describe the link's purpose or destination. For example, replace "Buy Now" with "Buy our new iPhone 93 Pro" or "Learn more about our services." Ensure that links with identical destinations have consistent text. Avoid overly verbose descriptions. This may be a content change so partner with design or key stakeholders before changing copy.
+
+If the generic link text itself cannot be changed then apply a code-based fix such as proper use of {{aria-describedby}}, {{aria-label}}, {{aria-labelledby}} so that context is included in the link's label in the code.
+
+If the link is pointing to files like PDF or opening pages in new windows, it is best practice to include this information within the link's accessible name in some way.
+
+[Compliant code example]  
+(## Tester note: tester can leave these generic examples in place or author a tailored solution based on the Code Reference (preferred) ##)
+
+**aria-label:** {{aria-label}} attribute value includes the visible text and it is front-loaded followed by a comma and then the additional context which should match nearby text and be super meaningful.
+{code:html}
+<h2>iPhone 24 Pro</h2>
+<a href="#" aria-label="Buy now, iPhone 24 Pro">Buy Now</a>
+{code}
+
+**aria-describedby:** Nearby text content is programmatically associated.
+{code:html}
+<h2 id="unique-id-0">Some cool heading</h2>
+<a href="#" aria-describedby="unique-id-0">Buy Now</a>
+{code}
+
+**aria-labelledby:** The control itself is referenced as well as other nearby content via {{aria-labelledby}}.
+{code:html}
+<h2 id="unique-id-0">Some cool heading</h2>
+<a href="#" aria-labelledby="unique-id-1 unique-id-0" id="unique-id-1">Buy Now</a>
+{code}
+
+**Link to file:**
+{code:html}
+<a href="#">Download the awesome manual (PDF)</a>
+{code}
+
+**Opens in a new window:**
+{code:html}
+<a href="#" aria-label="Learn more, iPhone 24 Pro, opens in a new window">Learn More</a>
+{code}
+
+[How to test]  
+Automated: Use tools such as Axe DevTools or the Level Access extension to identify links with generic text.
+
+Manual:
+- Review all links and ensure the text clearly conveys their purpose out of context.
+- Using Chrome DevTools Accessibility Inspector, inspect the link in the HTML. The Name property value in Computed Properties (in conjunction with any Description property text) should be meaningful.
+- Use a screen reader to navigate the page by links (e.g., NVDA's "Links List"). Confirm the text is descriptive and unambiguous.
+
+[MagentaA11y]  
+https://www.magentaa11y.com/checklist-web/link/
+
+[Resources]
+######
+
+[WCAG]  
+2.4.4 Link Purpose (In Context) (A)
+2.5.3 Label in Name (A)
+
+[Operating system]  
+######
+
+[Build Version]
+######
+
+[Browser]
+######
+
+[Assistive technology]  
+JAWS
+NVDA
+VoiceOver
+TalkBack

package/web/wip-non-text-content-does-not-meet-required-3-1-contrast.md

@@ -0,0 +1,74 @@
+# [WIP] Non-text content does not meet required 3:1 contrast
+
+## 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 ##)
+
+The ##### located at #####
+
+[What is the issue] 
+The ###### lacks 3:1 contrast which is required for non-text content that is important, informative, and contains context (aka not decorative).
+
+[Color reference] 
+(## Tester note: fill out hex codes for XXXXXX which is the foreground or non-text content color and YYYYYY which is the background or adjacent color ##)
+
+Non-text content color XXXXXX fails 3:1 contrast against YYYYYY background.
+https://webaim.org/resources/contrastchecker/?fcolor=000000&bcolor=FFFFFF
+
+[Why it is important]  
+Non-text content such as icons, images of text, graphics, etc. that contain important information must have contrast in order for the most possible users to be able to see them. High contrast helps users with vision disabilities such as low vision users, as well as color vision deficiencies such as red-green color blindness, blue-yellow color blindness, and complete color blindness. 3:1 contrast is actually about calculating the hue contrast such that even if you cannot make out color at all, the lightness/darkness of the colors will be sufficient for a user to tell them apart.
+
+[How to fix]  
+Refer to the WebAIM Contrast checker — https://webaim.org/resources/contrastchecker/?fcolor=000000&bcolor=FFFFFF — to find a color that will have 3:1 contrast.
+
+Consider TDDS color schemes as well: https://www.figma.com/design/HIvbo95KykcH9kuhwcVgky/1.-Foundations?node-id=1-480151&p=f&m=dev
+
+Note: Fix will likely require consultation with a designer to find a branded and TDDS compliant color.
+
+[Compliant code example]
+n/a — this is typically a design change
+
+[How to test]  
+Automated:
+- Run an automated scan tool such as LevelAccess, Axe, or Lighthouse. Note, however, that these tools regularly miss these types of contrast issues. Manual evaluation is recommended.
+- Input hex codes into WebAIM Contrast checker — https://webaim.org/resources/contrastchecker/?fcolor=000000&bcolor=FFFFFF — to verify contrast is less than 3:1.
+
+Manual:
+- Open DevTools in your browser window (F12)
+- Right-click and select "Inspect" on the different color combinations that you see as you move from the top of the page on down
+- Find the hexadecimal color values in the "Styles" tab of your DevTools window
+- Enter the hex values into a contrast checking tool (like WebAIM Contrast Checker or Deque's Color Contrast Analyzer) to verify if the contrast is less than 3:1.
+
+[MagentaA11y] 
+https://www.magentaa11y.com/how-to-test/color-contrast/
+
+[Resources]
+Figma contrast checker: https://www.figma.com/community/plugin/732603254453395948/stark-contrast-accessibility-checker
+
+[WCAG]  
+1.4.11 Non-text Contrast (AA)
+
+[Operating system]  
+######
+
+[Build Version]
+######
+
+[Browser]
+######
+
+[Assistive technology]
+######