arc-templated-issues 1.0.0 → 1.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "arc-templated-issues",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.1.0",
|
|
4
4
|
"description": "ARC accessibility issue templates for web and native platforms",
|
|
5
5
|
"files": [
|
|
6
6
|
"public/",
|
|
@@ -11,7 +11,7 @@
|
|
|
11
11
|
"template-mappings.schema.json"
|
|
12
12
|
],
|
|
13
13
|
"scripts": {
|
|
14
|
-
"build": "node scripts/build-combined-doc.js",
|
|
14
|
+
"build": "node scripts/build-combined-doc.js && node scripts/build-json.js",
|
|
15
15
|
"prepublishOnly": "npm run build",
|
|
16
16
|
"release:patch": "npm run build && npm version patch && npm publish",
|
|
17
17
|
"release:minor": "npm run build && npm version minor && npm publish",
|
|
@@ -0,0 +1,137 @@
|
|
|
1
|
+
[
|
|
2
|
+
{
|
|
3
|
+
"file": "button-lacks-a-label-in-the-code.md",
|
|
4
|
+
"title": "Button lacks a label in the code",
|
|
5
|
+
"severity": "1-Critical",
|
|
6
|
+
"suggestedPriority": "Blocker",
|
|
7
|
+
"fields": {
|
|
8
|
+
"path": "######",
|
|
9
|
+
"stepsToReproduce": "######",
|
|
10
|
+
"element": "The ##### button located #####",
|
|
11
|
+
"whatIsTheIssue": "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).",
|
|
12
|
+
"whyItIsImportant": "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.",
|
|
13
|
+
"howToFix": "- On iOS, set a descriptive {{.accessibilityLabel}} for each button.\n- On Android, use the {{contentDescription}} property to provide meaningful labels.\n- Ensure the label is concise and accurately describes the button's function (e.g., \"Submit,\" \"Back,\" or \"Search\").",
|
|
14
|
+
"compliantCodeExample": "iOS\n{code:swift}\nButton(action: { /* action */ }) {\n Text(\"Submit\")\n}\n.accessibilityLabel(\"Submit, any additional context\")\n{code}\n\nAndroid\n{code:java}\nButton(onClick = { /* action */ }) {\n Text(\"Submit\")\n}.semantics { contentDescription = \"Submit, any additional context\" }\n{code}",
|
|
15
|
+
"howToTest": "- 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.\n- Manual inspection: Check the code to confirm that all buttons include appropriate accessibility properties like {{.accessibilityLabel}} or {{contentDescription}}.",
|
|
16
|
+
"magentaa11y": "https://www.magentaa11y.com/checklist-native/button/",
|
|
17
|
+
"resources": "######",
|
|
18
|
+
"wcag": "(## Tester note: Choose or add and delete me ##)\n2.4.6: Headings and Labels (AA)\n2.5.3: Label in Name (AA)\n4.1.2 Name, Role, Value (A)",
|
|
19
|
+
"operatingSystem": "(## Tester note: Choose one and delete me ##)\niOS\nAndroid",
|
|
20
|
+
"buildVersion": "###### E.g. 10.6.0",
|
|
21
|
+
"assistiveTechnology": "(## Tester note: Choose one and delete me ##)\nVoiceOver\nTalkBack\nKeyboard"
|
|
22
|
+
}
|
|
23
|
+
},
|
|
24
|
+
{
|
|
25
|
+
"file": "focus-order-is-not-logical.md",
|
|
26
|
+
"title": "Focus order is not logical",
|
|
27
|
+
"severity": "2-Severe",
|
|
28
|
+
"suggestedPriority": "High",
|
|
29
|
+
"fields": {
|
|
30
|
+
"urlPath": "######",
|
|
31
|
+
"stepsToReproduce": "######",
|
|
32
|
+
"element": "(## Tester note: Describe where the thing is in the UI and delete me ##)",
|
|
33
|
+
"whatIsTheIssue": "(## Tester note: Add to this content below describing the focus order — delete me ##)\nThe screen reader focus order does not follow a logical order. In this case, the focus order ######",
|
|
34
|
+
"whyItIsImportant": "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.",
|
|
35
|
+
"codeReference": "(## 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 ##)\n{code:swift}\n...\n{code}",
|
|
36
|
+
"howToFix": "(## Tester note: If needed add to this content to describe expected focus order ##)\n- Review the order of focusable elements and ensure it follows a logical and expected progression that matches the visual layout and intended user flow.\n- Ensure the elements that should receive focus are enabled for accessibility. e.g. {{isAccessibilityElement}} in iOS and {{importantForAccessibility}} in Android.\n- 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).\n- Make sure hidden elements or off-screen controls are not included in the focus order.",
|
|
37
|
+
"compliantCodeExample": "(## Tester note: n/a here if not applicable — code formatting options: code:html, code:css, code:swift, code:java ##)\n{code:swift}\n...\n{code}",
|
|
38
|
+
"howToTest": "Automated: Use tools like Android Accessibility Scanner or iOS Accessibility Inspector to detect potential focus order issues.\nManual: 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.",
|
|
39
|
+
"magentaa11y": "https://www.magentaa11y.com/checklist-native/focus/",
|
|
40
|
+
"resources": "######",
|
|
41
|
+
"wcag": "2.4.3 Focus Order (A)\n1.3.2 Meaningful Sequence (A)",
|
|
42
|
+
"operatingSystem": "iOS\nAndroid",
|
|
43
|
+
"buildVersion": "###### E.g. 10.6.0",
|
|
44
|
+
"assistiveTechnology": "VoiceOver\nTalkBack"
|
|
45
|
+
}
|
|
46
|
+
},
|
|
47
|
+
{
|
|
48
|
+
"file": "heading-trait-is-not-used-in-the-code.md",
|
|
49
|
+
"title": "Heading Trait is not used in the code",
|
|
50
|
+
"severity": "3-Average",
|
|
51
|
+
"suggestedPriority": "Medium",
|
|
52
|
+
"fields": {
|
|
53
|
+
"path": "######",
|
|
54
|
+
"stepsToReproduce": "######",
|
|
55
|
+
"element": "The ##### large text located #####",
|
|
56
|
+
"whatIsTheIssue": "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.",
|
|
57
|
+
"whyItIsImportant": "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.",
|
|
58
|
+
"howToFix": "- Ensure the heading is logical, concise, and represents the hierarchy of content.\n- On iOS, apply the {{.accessibilityTraits}} property with the .header value to the text element.\n- On Android, use the setHeading() method or AccessibilityHeading property to define the heading role for the element.",
|
|
59
|
+
"compliantCodeExample": "iOS\n{code:swift}\nText(\"Section Title\")\n .font(.title)\n .accessibilityAddTraits(.isHeader)\n{code}\n\nAndroid\n{code:java}\nText(\n text = \"Section Title\",\n modifier = Modifier.semantics { heading = true }\n)\n{code}",
|
|
60
|
+
"howToTest": "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.\nManual inspection: Review the code to ensure the heading is marked with appropriate accessibility traits.",
|
|
61
|
+
"magentaa11y": "https://www.magentaa11y.com/checklist-native/headings/",
|
|
62
|
+
"resources": "######",
|
|
63
|
+
"wcag": "(## Tester note: Choose or add and delete me ##)\n1.3.1 Info and Relationships (A)\n2.4.6 Headings and Labels (AA)",
|
|
64
|
+
"operatingSystem": "(## Tester note: Choose one and delete me ##)\niOS\nAndroid",
|
|
65
|
+
"buildVersion": "###### E.g. 10.6.0",
|
|
66
|
+
"assistiveTechnology": "(## Tester note: Choose one and delete me ##)\nVoiceOver\nTalkBack\nKeyboard"
|
|
67
|
+
}
|
|
68
|
+
},
|
|
69
|
+
{
|
|
70
|
+
"file": "image-icon-should-be-marked-as-decorative.md",
|
|
71
|
+
"title": "Image/icon should be marked as decorative",
|
|
72
|
+
"severity": "3-Average",
|
|
73
|
+
"suggestedPriority": "Medium",
|
|
74
|
+
"fields": {
|
|
75
|
+
"urlPath": "######",
|
|
76
|
+
"stepsToReproduce": "######",
|
|
77
|
+
"element": "(## Tester note: Describe where the decorative image is in the UI and delete me ##)",
|
|
78
|
+
"whatIsTheIssue": "The following images do not meet the requirements for properly programmatically hidden decorative images:\n\nA 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.\n\nA 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.\n\nAn 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.",
|
|
79
|
+
"whyItIsImportant": "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.",
|
|
80
|
+
"codeReference": "(## Tester note: iOS and Android image attributes for decorative, hidden, or null go here – delete me ##)\n{code:swift}\n...\n{code}",
|
|
81
|
+
"howToFix": "Ensure that decorative images and icons are programmatically hidden. Use the correct function to hide the decorative image or icon.",
|
|
82
|
+
"compliantCodeExample": "(## Tester note: n/a here if not applicable and is a design change and delete me ##)\n\n**Android — XML**\nUse `android:importantForAccessibility=\"no\"` to ensure that the image is not considered for accessibility purposes. This will prevent TalkBack from announcing the image.\n\n**Android — Jetpack Compose**\nSet `contentDescription = null` for decorative elements to ensure that the content description is not announced by TalkBack.\n{code:java}\nImage(\n painter = painterResource(id = R.drawable.decorative_image),\n contentDescription = null\n)\n{code}\n\n**iOS — SwiftUI**\nUse the modifier `.accessibilityHidden(true)` to hide an icon or image from VoiceOver, Full Keyboard Access, and Switch Control.\nUse 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.\n{code:swift}\nImage(decorative: \"decorative_image\")\n// or\nImage(\"decorative_image\")\n .accessibilityHidden(true)\n{code}\n\n**iOS — UIKit**\nUse `imageView.isAccessibilityElement = false` to ensure the image view is ignored by VoiceOver, meaning it won't be announced or focusable.",
|
|
83
|
+
"howToTest": "Automated:\n- Not Applicable\n\nManual:\n- Inspect the screen to identify images which have adjacent text descriptions or are non-essential.\n- 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.\n- Review the list of decorative images to ensure that each uses a valid programmatic hidden, decorative, or null description value.",
|
|
84
|
+
"magentaa11y": "https://www.magentaa11y.com/checklist-native/image-decorative/",
|
|
85
|
+
"resources": "Decorative Images\nhttps://www.w3.org/WAI/tutorials/images/decorative/\n\nAndroid Developers: Decorative Images\nhttps://developer.android.com/guide/topics/ui/accessibility/principles#decorative",
|
|
86
|
+
"wcag": "1.1.1 Non-text Content (Level A)",
|
|
87
|
+
"operatingSystem": "######",
|
|
88
|
+
"buildVersion": "######",
|
|
89
|
+
"assistiveTechnology": "VoiceOver\nTalkBack"
|
|
90
|
+
}
|
|
91
|
+
},
|
|
92
|
+
{
|
|
93
|
+
"file": "items-should-be-grouped.md",
|
|
94
|
+
"title": "Items should be grouped",
|
|
95
|
+
"severity": "3-Average",
|
|
96
|
+
"suggestedPriority": "Medium",
|
|
97
|
+
"fields": {
|
|
98
|
+
"urlPath": "######",
|
|
99
|
+
"stepsToReproduce": "######",
|
|
100
|
+
"element": "(## Tester note: Describe where the thing is in the UI and delete me ##)",
|
|
101
|
+
"whatIsTheIssue": "Related items are not properly grouped, which impacts the navigation and understanding for users relying on screen readers and braille displays or keyboards.",
|
|
102
|
+
"whyItIsImportant": "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.",
|
|
103
|
+
"codeReference": "- In SwiftUI, group multiple elements with the `.accessibilityElement(children:)` modifier and with the `.combine` option on a parent view.\n- In Jetpack Compose, group elements by using `mergeDescendants`.\n- For Android Views, group all the relevant content elements in a single layout ViewGroup and set `android:importantForAccessibility=\"yes\"` on that ViewGroup.",
|
|
104
|
+
"howToFix": "(## Tester note: If needed add to this content to describe expected grouping ##)\n- Review the order of focusable/swipeable elements and ensure related elements are logically grouped.",
|
|
105
|
+
"compliantCodeExample": "(## Tester note: n/a here if not applicable — code formatting options: code:swift, code:java ##)\n{code:swift}\n...\n{code}",
|
|
106
|
+
"howToTest": "- Automated: Use tools like Android Accessibility Scanner or iOS Accessibility Inspector to detect missing or incorrect groupings.\n- 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.",
|
|
107
|
+
"magentaa11y": "https://www.magentaa11y.com/checklist-native/focus/",
|
|
108
|
+
"resources": "- Android Developers: Groups of Related Content\n https://developer.android.com/guide/topics/ui/accessibility/principles#content-groups\n- Accessibility group in Jetpack Compose\n https://appt.org/en/docs/jetpack-compose/samples/accessibility-group\n- Accessibility Group on iOS\n https://appt.org/en/docs/ios/samples/accessibility-group\n- Accessibility Group on React Native\n https://appt.org/en/docs/react-native/samples/accessibility-group",
|
|
109
|
+
"wcag": "1.3.1 Info and Relationships (A)\n3.3.2 Labels or Instructions (A)",
|
|
110
|
+
"operatingSystem": "iOS\nAndroid",
|
|
111
|
+
"buildVersion": "###### E.g. 10.6.0",
|
|
112
|
+
"assistiveTechnology": "VoiceOver\nTalkBack"
|
|
113
|
+
}
|
|
114
|
+
},
|
|
115
|
+
{
|
|
116
|
+
"file": "state-is-not-communicated-for-button.md",
|
|
117
|
+
"title": "State is not communicated for button",
|
|
118
|
+
"severity": "2-Severe",
|
|
119
|
+
"suggestedPriority": "High",
|
|
120
|
+
"fields": {
|
|
121
|
+
"path": "######",
|
|
122
|
+
"stepsToReproduce": "######",
|
|
123
|
+
"element": "The ##### button located #####",
|
|
124
|
+
"whatIsTheIssue": "The ##### control with a dynamic state of ##### does not communicate its state to screen reader users.",
|
|
125
|
+
"whyItIsImportant": "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.\n\nFor 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.\"",
|
|
126
|
+
"howToFix": "- Use native controls and State will naturally be communicated.\n- For a toggle button, ensure states like \"selected,\" \"pressed,\" or \"disabled\" are programmatically exposed using platform-specific APIs.\n- On iOS, use {{.accessibilityValue}} to indicate the current state of the button (e.g., \"On\" or \"Off\").\n- On Android, set the {{contentDescription}} dynamically to reflect the button's state, or use accessibility APIs like {{AccessibilityNodeInfo.setText()}} to provide state information.",
|
|
127
|
+
"compliantCodeExample": "iOS\n{code:swift}\nToggle(\"Enable Feature\", isOn: $isOn)\n .accessibilityValue(isOn ? \"On\" : \"Off\")\n{code}\n\nAndroid\n{code:java}\nval isChecked = remember { mutableStateOf(false) }\nCheckbox(\n checked = isChecked.value,\n onCheckedChange = { isChecked.value = it },\n modifier = Modifier.semantics { contentDescription = if (isChecked.value) \"Checked\" else \"Unchecked\" }\n)\n{code}",
|
|
128
|
+
"howToTest": "- 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.",
|
|
129
|
+
"magentaa11y": "https://www.magentaa11y.com/checklist-native/button/",
|
|
130
|
+
"resources": "######",
|
|
131
|
+
"wcag": "4.1.2 Name, Role, Value (A)\n1.3.1: Info and Relationships (A)",
|
|
132
|
+
"operatingSystem": "(## Tester note: Choose one and delete me ##)\niOS\nAndroid",
|
|
133
|
+
"buildVersion": "###### E.g. 10.6.0",
|
|
134
|
+
"assistiveTechnology": "(## Tester note: Choose one and delete me ##)\nVoiceOver\nTalkBack\nKeyboard"
|
|
135
|
+
}
|
|
136
|
+
}
|
|
137
|
+
]
|
|
@@ -0,0 +1,236 @@
|
|
|
1
|
+
[
|
|
2
|
+
{
|
|
3
|
+
"file": "control-lacks-a-label-in-the-code.md",
|
|
4
|
+
"title": "Control lacks a label in the code",
|
|
5
|
+
"severity": "1-Critical",
|
|
6
|
+
"suggestedPriority": "Blocker",
|
|
7
|
+
"fields": {
|
|
8
|
+
"urlPath": "######",
|
|
9
|
+
"stepsToReproduce": "######",
|
|
10
|
+
"element": "The ##### located #####",
|
|
11
|
+
"whatIsTheIssue": "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.",
|
|
12
|
+
"whyItIsImportant": "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.",
|
|
13
|
+
"codeReference": "(## Tester note: grab code snippet from experience and delete me ##) \n{code:html} \n<button></button> \n{code}",
|
|
14
|
+
"howToFix": "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. \n\nWhen 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. \n\nAuthors 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.",
|
|
15
|
+
"compliantCodeExample": "(## Tester note: include real code example or just leave generic examples below and delete me ##) \n{code:html} \n<button>My Account</button> \n{code} \n\n{code:html} \n<a href=”/facebook” aria-label=”Facebook”><svg>...</svg></button> \n{code} \n\n{code:html} \n<span id=”example”>Some text</span> \n<a href=”/facebook” aria-labelledby=”example”><svg>...</svg></button> \n{code}",
|
|
16
|
+
"howToTest": "Screen reader testing: Use a screen reader to navigate to the control and verify that the correct label is announced. \n\nVisual 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. \n\nUse 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",
|
|
17
|
+
"magentaa11y": "https://www.magentaa11y.com/how-to-test/link-button/ \nhttps://www.magentaa11y.com/checklist-web/link/ \nhttps://www.magentaa11y.com/checklist-web/button/",
|
|
18
|
+
"wcag": "(## Tester note: Choose or add and delete me ##)\n2.4.4: Link Purpose (In Context) (A) \n2.4.6: Headings and Labels (AA) \n2.5.3: Label in Name (AA) \n4.1.2 Name, Role, Value (A)",
|
|
19
|
+
"operatingSystem": "######",
|
|
20
|
+
"browser": "######",
|
|
21
|
+
"assistiveTechnology": "Keyboard"
|
|
22
|
+
}
|
|
23
|
+
},
|
|
24
|
+
{
|
|
25
|
+
"file": "heading-levels-incorrectly-nested.md",
|
|
26
|
+
"title": "Heading levels incorrectly nested",
|
|
27
|
+
"severity": "3-Average",
|
|
28
|
+
"suggestedPriority": "Medium",
|
|
29
|
+
"fields": {
|
|
30
|
+
"urlPath": "######",
|
|
31
|
+
"stepsToReproduce": "######",
|
|
32
|
+
"element": "(## Tester note: Describe where the heading is in the UI and delete me ##)",
|
|
33
|
+
"whatIsTheIssue": "The following heading level nesting example does not meet the requirements for logically structured heading hierarchy: \n\nThe 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.",
|
|
34
|
+
"whyItIsImportant": "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.",
|
|
35
|
+
"codeReference": "(## Tester note: CSS code references can be helpful here – delete me ##)\n{code:css}\n... \n{code}",
|
|
36
|
+
"howToFix": "Ensure that heading levels are used in a logical, hierarchical order. For example:\n\n- An {{<h1>}} should be the first heading on the page.\n\n- {{<h2>}} headings should follow {{<h1>}}, and {{<h3>}} should follow {{<h2>}}.\n\n- Do not skip heading levels (e.g., {{<h1>}} skipping to {{<h3>}} is incorrect; it should be {{<h1>}} then {{<h2>}} then {{<h3>}}).\n\n- 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.\n\nUse the correct HTML elements for headings: {{<h1>}}, {{<h2>}}, {{<h3>}}, etc. Avoid using styling (like font size) alone to create the appearance of a heading.\n\nRepeating patterns of headings are allowed so long as they follow a logical sequence (example: {{<h2>}},{{<h3>}},{{<h2>}},{{<h3>}})",
|
|
37
|
+
"compliantCodeExample": "(## Tester note: n/a here if not applicable and is a design change and delete me ##)\n{code:html} \n\n<h1>My favorite taco recipe</h1>\n\n<!-- Author's entire life story as it relates to tacos -->\n\n<h2>Ingredients</h2>\n\n<!-- List of ingredients -->\n\n<h2>Steps</h2>\n\n<h3>Preparing the protein</h3>\n\n<!-- List of instructions -->\n\n<h3>Preparing the vegetables</h3>\n\n<!-- List of instructions -->\n\n<h3>Assembly and plating</h3>\n\n<!-- List of instructions-->\n\n<h2>Nutrition information</h2>\n\n<!-- List of nutrition info -->\n\n<h2>Related recipes</h2>\n\n<!-- List of related recipes -->\n{code}",
|
|
38
|
+
"howToTest": "Automated:\n- 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.\n\n- Follow-up with manual verification of the heading hierarchy in the HTML source code. (See Manual checks below.)\n\nManual:\n\n- Inspect the page's HTML code to check the order of the heading elements (<h1>, <h2>, <h3>, etc.).\n\n- 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.\n\n- Review the document structure using browser developer tools to ensure headings follow the correct hierarchy.",
|
|
39
|
+
"magentaa11y": "https://www.magentaa11y.com/checklist-web/heading/",
|
|
40
|
+
"resources": "https://www.w3.org/WAI/tutorials/page-structure/headings",
|
|
41
|
+
"wcag": "1.3.1 Info and Relationships (Level A)",
|
|
42
|
+
"operatingSystem": "######",
|
|
43
|
+
"browser": "######",
|
|
44
|
+
"assistiveTechnology": "######"
|
|
45
|
+
}
|
|
46
|
+
},
|
|
47
|
+
{
|
|
48
|
+
"file": "images-should-be-marked-as-decorative.md",
|
|
49
|
+
"title": "Images should be marked as decorative",
|
|
50
|
+
"severity": "Low",
|
|
51
|
+
"suggestedPriority": "Low",
|
|
52
|
+
"fields": {
|
|
53
|
+
"urlPath": "######",
|
|
54
|
+
"stepsToReproduce": "######",
|
|
55
|
+
"element": "(## Tester note: Describe where the thing is in the UI and delete me ##)",
|
|
56
|
+
"whatIsTheIssue": "The (## Tester note: describe image here – delete me ##) image/icon does not provide meaningful information, however, it is not marked as decorative.",
|
|
57
|
+
"whyItIsImportant": "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.",
|
|
58
|
+
"codeReference": "(## Tester note: CSS code references can be helpful here – delete me ##)\n{code} \n... \n{code}",
|
|
59
|
+
"howToFix": "Ensure standard {{<img>}} elements have an empty {{alt=””}} attribute or {{alt (null)}}.\nEnsure {{<svg>}} elements have {{aria-hidden=”true” focusable=\"false\"}} attributes.",
|
|
60
|
+
"compliantCodeExample": "(## Tester note: n/a here if not applicable and is a design change and delete me ##)\n{code:html}\n\n <img src=\"image.jpg\" alt=\"\">\n\n{code}\n\n{code:html}\n\n<svg aria-hidden=\"true\">...</svg>\n\n{code}",
|
|
61
|
+
"howToTest": "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.\n\n\nManual: 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.",
|
|
62
|
+
"magentaa11y": "www.magentaa11y.com/checklist-web/image-decorative/\n\nwww.magentaa11y.com/how-to-test/images/",
|
|
63
|
+
"wcag": "1.1.1 Non-Text Content (A)",
|
|
64
|
+
"operatingSystem": "######",
|
|
65
|
+
"browser": "######",
|
|
66
|
+
"assistiveTechnology": "JAWS\nNVDA\nVoiceOver",
|
|
67
|
+
"additionalResources": "https://www.w3.org/WAI/tutorials/images/decision-tree/"
|
|
68
|
+
}
|
|
69
|
+
},
|
|
70
|
+
{
|
|
71
|
+
"file": "interactive-element-is-not-keyboard-accessible.md",
|
|
72
|
+
"title": "Interactive element is not keyboard accessible",
|
|
73
|
+
"severity": "1-Critical",
|
|
74
|
+
"suggestedPriority": "Blocker",
|
|
75
|
+
"fields": {
|
|
76
|
+
"urlPath": "######",
|
|
77
|
+
"stepsToReproduce": "######",
|
|
78
|
+
"element": "The ##### button located #####",
|
|
79
|
+
"whatIsTheIssue": "(## Tester note: choose one and delete me ##)\nThe ###### is not keyboard accessible. Keyboard users are not able to reach the control in any way or activate it. \n\nThe ###### is not keyboard accessible. Keyboard users are able to reach the control, but nothing happens when those users try to activate the control.",
|
|
80
|
+
"whyItIsImportant": "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.",
|
|
81
|
+
"codeReference": "(## Tester note: show actual code and delete me ##)\n{code:html} \n... \n{code}",
|
|
82
|
+
"howToFix": "- 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. \n- Use an element that is naturally focusable such as a {{<button>}} or {{<a>}}. \n- In cases where a negative {{tabindex}} has been used, remove {{tabindex=\"-1\"}} from the element. \n- Ensure the button does not own {{aria-hidden=\"true\"}} \n- Ensure anchor tags / links own valid {{href}} attribute values.",
|
|
83
|
+
"compliantCodeExample": "(## Tester note: show a real code fragment here or use generic examples below and delete me ##)\n{code:html} \n<button>My Account</button> \n{code}\n\n{code:html} \n<a href=”/some-page”>Learn more about MagentaA11y</a> \n{code}",
|
|
84
|
+
"howToTest": "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.\n\nManual inspection: Using Chrome DevTools, inspect the control and verify that the {{tabindex=”-1”}} and {{aria-hidden=”true”}} attributes are not present.",
|
|
85
|
+
"magentaa11y": "https://www.magentaa11y.com/how-to-test/keyboard-focus/ \nhttps://www.magentaa11y.com/checklist-web/button/ \nhttps://www.magentaa11y.com/checklist-web/link/",
|
|
86
|
+
"wcag": "(## Tester note: Choose or add and delete me ##)\n2.1.1 Keyboard (A) \n2.4.3 Focus Order (A)",
|
|
87
|
+
"operatingSystem": "######",
|
|
88
|
+
"browser": "######",
|
|
89
|
+
"assistiveTechnology": "Keyboard"
|
|
90
|
+
}
|
|
91
|
+
},
|
|
92
|
+
{
|
|
93
|
+
"file": "wip-link-text-is-not-descriptive-or-lacks-purpose.md",
|
|
94
|
+
"title": "[WIP] Link text is not descriptive or lacks purpose",
|
|
95
|
+
"severity": "3-Average",
|
|
96
|
+
"suggestedPriority": "Medium",
|
|
97
|
+
"fields": {
|
|
98
|
+
"urlPath": "######",
|
|
99
|
+
"stepsToReproduce": "######",
|
|
100
|
+
"element": "(## Tester note: Describe where the thing is in the UI and delete me ##)",
|
|
101
|
+
"whatIsTheIssue": "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.",
|
|
102
|
+
"whyItIsImportant": "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.\n\nWhen multiple links on a screen have the same visible text label but different targets, then providing distinguishing context becomes very important.\n\nVoice 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!!",
|
|
103
|
+
"codeReference": "(## Tester note: CSS code references can be helpful here – delete me ##)\n{code:html}\n...\n{code}",
|
|
104
|
+
"howToFix": "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.\n\nIf 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.\n\nIf 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.",
|
|
105
|
+
"compliantCodeExample": "(## Tester note: tester can leave these generic examples in place or author a tailored solution based on the Code Reference (preferred) ##)\n\n**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.\n{code:html}\n<h2>iPhone 24 Pro</h2>\n<a href=\"#\" aria-label=\"Buy now, iPhone 24 Pro\">Buy Now</a>\n{code}\n\n**aria-describedby:** Nearby text content is programmatically associated.\n{code:html}\n<h2 id=\"unique-id-0\">Some cool heading</h2>\n<a href=\"#\" aria-describedby=\"unique-id-0\">Buy Now</a>\n{code}\n\n**aria-labelledby:** The control itself is referenced as well as other nearby content via {{aria-labelledby}}.\n{code:html}\n<h2 id=\"unique-id-0\">Some cool heading</h2>\n<a href=\"#\" aria-labelledby=\"unique-id-1 unique-id-0\" id=\"unique-id-1\">Buy Now</a>\n{code}\n\n**Link to file:**\n{code:html}\n<a href=\"#\">Download the awesome manual (PDF)</a>\n{code}\n\n**Opens in a new window:**\n{code:html}\n<a href=\"#\" aria-label=\"Learn more, iPhone 24 Pro, opens in a new window\">Learn More</a>\n{code}",
|
|
106
|
+
"howToTest": "Automated: Use tools such as Axe DevTools or the Level Access extension to identify links with generic text.\n\nManual:\n- Review all links and ensure the text clearly conveys their purpose out of context.\n- 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.\n- Use a screen reader to navigate the page by links (e.g., NVDA's \"Links List\"). Confirm the text is descriptive and unambiguous.",
|
|
107
|
+
"magentaa11y": "https://www.magentaa11y.com/checklist-web/link/",
|
|
108
|
+
"resources": "######",
|
|
109
|
+
"wcag": "2.4.4 Link Purpose (In Context) (A)\n2.5.3 Label in Name (A)",
|
|
110
|
+
"operatingSystem": "######",
|
|
111
|
+
"buildVersion": "######",
|
|
112
|
+
"browser": "######",
|
|
113
|
+
"assistiveTechnology": "JAWS\nNVDA\nVoiceOver\nTalkBack"
|
|
114
|
+
}
|
|
115
|
+
},
|
|
116
|
+
{
|
|
117
|
+
"file": "wip-non-text-content-does-not-meet-required-3-1-contrast.md",
|
|
118
|
+
"title": "[WIP] Non-text content does not meet required 3:1 contrast",
|
|
119
|
+
"severity": "2-Severe",
|
|
120
|
+
"suggestedPriority": "High",
|
|
121
|
+
"fields": {
|
|
122
|
+
"urlPath": "######",
|
|
123
|
+
"stepsToReproduce": "######",
|
|
124
|
+
"element": "(## Tester note: Describe where the thing is in the UI and delete me ##)\n\nThe ##### located at #####",
|
|
125
|
+
"whatIsTheIssue": "The ###### lacks 3:1 contrast which is required for non-text content that is important, informative, and contains context (aka not decorative).",
|
|
126
|
+
"colorReference": "(## 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 ##)\n\nNon-text content color XXXXXX fails 3:1 contrast against YYYYYY background.\nhttps://webaim.org/resources/contrastchecker/?fcolor=000000&bcolor=FFFFFF",
|
|
127
|
+
"whyItIsImportant": "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.",
|
|
128
|
+
"howToFix": "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.\n\nConsider TDDS color schemes as well: https://www.figma.com/design/HIvbo95KykcH9kuhwcVgky/1.-Foundations?node-id=1-480151&p=f&m=dev\n\nNote: Fix will likely require consultation with a designer to find a branded and TDDS compliant color.",
|
|
129
|
+
"compliantCodeExample": "n/a — this is typically a design change",
|
|
130
|
+
"howToTest": "Automated:\n- 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.\n- Input hex codes into WebAIM Contrast checker — https://webaim.org/resources/contrastchecker/?fcolor=000000&bcolor=FFFFFF — to verify contrast is less than 3:1.\n\nManual:\n- Open DevTools in your browser window (F12)\n- Right-click and select \"Inspect\" on the different color combinations that you see as you move from the top of the page on down\n- Find the hexadecimal color values in the \"Styles\" tab of your DevTools window\n- 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.",
|
|
131
|
+
"magentaa11y": "https://www.magentaa11y.com/how-to-test/color-contrast/",
|
|
132
|
+
"resources": "Figma contrast checker: https://www.figma.com/community/plugin/732603254453395948/stark-contrast-accessibility-checker",
|
|
133
|
+
"wcag": "1.4.11 Non-text Contrast (AA)",
|
|
134
|
+
"operatingSystem": "######",
|
|
135
|
+
"buildVersion": "######",
|
|
136
|
+
"browser": "######",
|
|
137
|
+
"assistiveTechnology": "######"
|
|
138
|
+
}
|
|
139
|
+
},
|
|
140
|
+
{
|
|
141
|
+
"file": "wip-screen-reader-focus-is-not-retained-while-navigating-between-modal-views.md",
|
|
142
|
+
"title": "[WIP] Screen reader focus is not retained while navigating between modal views",
|
|
143
|
+
"severity": "2-Severe",
|
|
144
|
+
"suggestedPriority": "High",
|
|
145
|
+
"fields": {
|
|
146
|
+
"urlPath": "######",
|
|
147
|
+
"stepsToReproduce": "######",
|
|
148
|
+
"element": "(## Tester note: Describe where the thing is in the UI and delete me ##)",
|
|
149
|
+
"whatIsTheIssue": "When screen reader users activate the **\"[placeholder name]\"** button inside a modal, which updates the content within the modal, screen reader focus is not retained within the modal. Instead, focus often lands outside the modal container — typically on the `<body>` — causing screen reader users to unintentionally navigate the page behind the modal when using arrow keys.\n\n(## Tester note: delete this section if not applicable ##) The same issue occurs when the \"back\" chevron icon button is used to return to the previous modal view. Focus is not retained within the modal.",
|
|
150
|
+
"whyItIsImportant": "Screen reader users rely on logical, programmatically managed focus to stay oriented within dynamic components like modals. If focus is not explicitly managed during view or content changes inside a modal, or when changing to a new modal, users may unknowingly leave the modal context, leading to confusion and difficulty completing tasks. This breaks expected modal behavior.",
|
|
151
|
+
"codeReference": "(## Tester note: grab code snippet from experience and delete me ##)\n{code:html}\n...\n{code}",
|
|
152
|
+
"howToFix": "Ensure that when a user clicks the **\"[placeholder name]\"** button to change the view within the modal or launch another modal, programmatic focus is set to the top-level heading of the newly shown view (e.g., using `.focus()` on the `<h2>`). If there is no heading present on the view, focus can be set to whatever the first interactive element in the modal is, ideally a back or close button. Apply the same approach when changing the modal view with the \"back\" chevron icon button. This ensures screen reader users remain in the intended modal context.",
|
|
153
|
+
"compliantCodeExample": "(## Tester note: Choose to add or delete this section if not working in Phoenix/AEM environment ##)\n\nWhile this isn't the only solution, this is a sample fix that has been implemented to resolve the issue for a Phoenix/AEM multi-view modal:\n{code:html}\n/**\n * Set focus on the heading when the content changes while navigating between promo list to promo details and vice versa.\n *\n * @param visibilityScopeIdTarget - The ID of the visibility scope target to set focus on.\n */\nmanageFocus(visibilityScopeIdTarget?: string): void {\n let focusTarget: HTMLElement;\n\n if (visibilityScopeIdTarget) {\n focusTarget = document.querySelector(`[data-xpr-visibility-scope=\"${visibilityScopeIdTarget}\"]`) as HTMLElement;\n } else {\n focusTarget = this.component;\n }\n const headings: HTMLHeadingElement[] = Array.from(focusTarget?.querySelectorAll(':is(h1,h2,h3,h4,h5,h6)') || []);\n // Find the first visible heading\n const el = headings.find((heading) => {\n return heading.offsetParent !== null && heading.offsetHeight > 0 && heading.offsetWidth > 0;\n }) as HTMLElement | null;\n\n if (el) {\n el.setAttribute('tabindex', '-1');\n el.focus();\n } else {\n (this.component?.closest('.phx-modal') as HTMLElement)?.focus();\n }\n},\n\n setTimeout(() => {\n this.manageFocus();\n }, 100);\n{code}",
|
|
154
|
+
"howToTest": "Automated: Automated tools like Chrome's Lighthouse scanner will not detect this issue. Focus management during modal transitions should be tested manually with a screen reader.\n\nManual:\n- Open the modal and activate the **\"[placeholder name]\"** button to change the view.\n- With NVDA or JAWS in browse mode, press the arrow keys after the view changes.\n- Confirm that arrow key navigation starts at the new modal content and does not land outside the modal or on the main page.\n- Activate the back button and repeat the test.",
|
|
155
|
+
"magentaa11y": "######",
|
|
156
|
+
"resources": "######",
|
|
157
|
+
"wcag": "2.4.3 Focus Order (A)",
|
|
158
|
+
"operatingSystem": "Windows",
|
|
159
|
+
"buildVersion": "######",
|
|
160
|
+
"browser": "Chrome\nFirefox\nEdge",
|
|
161
|
+
"assistiveTechnology": "JAWS\nNVDA"
|
|
162
|
+
}
|
|
163
|
+
},
|
|
164
|
+
{
|
|
165
|
+
"file": "wip-semantic-meaning-of-a-heading-is-not-conveyed-to-a-screen-reader-user.md",
|
|
166
|
+
"title": "[WIP] Semantic meaning of a heading is not conveyed to a screen reader user",
|
|
167
|
+
"severity": "3-Average",
|
|
168
|
+
"suggestedPriority": "Medium",
|
|
169
|
+
"fields": {
|
|
170
|
+
"urlPath": "######",
|
|
171
|
+
"stepsToReproduce": "######",
|
|
172
|
+
"element": "(## Tester note: Describe where the thing is in the UI and delete me ##)",
|
|
173
|
+
"whatIsTheIssue": "A screen reader user does not know that a heading exists on the page because it is not coded with semantic HTML such as h1|h2|h3|h4|h5|h6. The heading is visually conveyed, but a screen reader user misses out on the same meaning, information, and hierarchy of relationships.\n\nThe semantic meaning of a heading is not conveyed to a screen reader user through HTML. This can happen when headings are marked up improperly (e.g., using non-semantic elements like `<div>` or `<span>` instead of proper tags like `<h1>` through `<h6>`).",
|
|
174
|
+
"whyItIsImportant": "Headings give a page a clear and logical structure, helping users of screen readers navigate and understand the content hierarchy. If the semantic HTML meaning is not conveyed correctly, users may struggle to comprehend the page structure.\n\nScreen reader users also often make use of keyboard shortcuts to skip around only the headings on a page to learn more about the content overview quickly and efficiently. When HTML headings are missing, it reduces their ability to interact with the site.",
|
|
175
|
+
"codeReference": "(## Tester note: CSS code references can be helpful here – delete me ##)\n{code:css}\n...\n{code}",
|
|
176
|
+
"howToFix": "Ensure all headings use the appropriate HTML heading tags (`<h1>`, `<h2>`, `<h3>`, etc.) for structuring the content.\n\nDo not use non-semantic elements like `<div>` or `<span>` for headings.\n\nThe heading hierarchy should be logical, with the `<h1>` being the most important and subsequent headings `<h2>`, `<h3>`, etc., used in a meaningful and logical order.",
|
|
177
|
+
"compliantCodeExample": "(## Tester note: n/a here if not applicable and is a design change and delete me ##)\n{code:html}\n...\n{code}",
|
|
178
|
+
"howToTest": "Automated:\nUse an accessibility testing tool (e.g., Level Access) to check for missing or incorrect heading elements. Verify that headings are being used properly in the HTML.\n\nManual:\n1. Navigate through the page using a screen reader (e.g., VoiceOver for MacOS or NVDA for Windows).\n - For VoiceOver, use VO keys + Command + H to skip around by heading\n - For NVDA, use \"H\" key to skip around by heading\n2. Ensure that all headings are conveyed as distinct, sequentially organized elements, and the content hierarchy makes sense.\n3. Inspect the HTML structure to verify that proper HTML tags are used instead of non-semantic elements.",
|
|
179
|
+
"magentaa11y": "https://www.magentaa11y.com/checklist-web/heading/",
|
|
180
|
+
"resources": "######",
|
|
181
|
+
"wcag": "1.3.1 Info and Relationships (A)",
|
|
182
|
+
"operatingSystem": "######",
|
|
183
|
+
"buildVersion": "######",
|
|
184
|
+
"browser": "######",
|
|
185
|
+
"assistiveTechnology": "JAWS\nNVDA\nVoiceOver\nTalkBack"
|
|
186
|
+
}
|
|
187
|
+
},
|
|
188
|
+
{
|
|
189
|
+
"file": "wip-semantic-meaning-of-a-list-is-not-conveyed-to-a-screen-reader-user.md",
|
|
190
|
+
"title": "[WIP] Semantic meaning of a list is not conveyed to a screen reader user",
|
|
191
|
+
"severity": "3-Average",
|
|
192
|
+
"suggestedPriority": "Medium",
|
|
193
|
+
"fields": {
|
|
194
|
+
"urlPath": "######",
|
|
195
|
+
"stepsToReproduce": "######",
|
|
196
|
+
"element": "(## Tester note: Describe where the thing is in the UI and delete me ##)",
|
|
197
|
+
"whatIsTheIssue": "A screen reader user does not know that a list exists on the page because it is not coded with semantic HTML such as `<ul>` or `<ol>`. The list is visually conveyed, but a screen reader user misses out on the same meaning, information, and hierarchy of relationships.\n\nThe semantic meaning of a list is not conveyed to a screen reader user through HTML. This can happen when lists are marked up improperly (e.g., using non-semantic elements like `<div>` or `<span>` instead of proper tags like `<ul>` or `<ol>`).",
|
|
198
|
+
"whyItIsImportant": "Lists (`<ul>` or `<ol>`) provide a clear and logical structure to content, helping users of screen readers navigate and understand the content hierarchy. A screen reader will announce where the list structure begins and ends and normally will announce the number of elements in the list as well (e.g., \"1 of 10\").\n\nIf the semantic meaning is not conveyed correctly, users may struggle to comprehend the page content or find relevant content efficiently, reducing their ability to interact with the site.",
|
|
199
|
+
"codeReference": "(## Tester note: CSS code references can be helpful here – delete me ##)\n{code:css}\n...\n{code}",
|
|
200
|
+
"howToFix": "Ensure all lists use the appropriate HTML list tags (`<ul>`, `<ol>`, and `<li>` for both) for structuring content.\n\nNote: VoiceOver does not announce `<ul>` or `<ol>` when CSS styling removes their numbering or bullets.",
|
|
201
|
+
"compliantCodeExample": "(## Tester note: n/a here if not applicable and is a design change and delete me ##)\n{code:html}\n...\n{code}",
|
|
202
|
+
"howToTest": "Automated:\nUse an accessibility testing tool (e.g., Level Access) to check for missing or incorrect list elements. Verify that lists are being used properly in the HTML.\n\nManual:\n1. Navigate through the page using a screen reader (e.g., VoiceOver for MacOS or NVDA for Windows).\n2. Ensure that all lists are conveyed as distinct, sequentially organized elements, and the content hierarchy makes sense.\n3. Inspect the HTML structure to verify that proper HTML tags are used instead of non-semantic elements.",
|
|
203
|
+
"magentaa11y": "https://www.magentaa11y.com/checklist-web/list/",
|
|
204
|
+
"resources": "######",
|
|
205
|
+
"wcag": "1.3.1 Info and Relationships (A)",
|
|
206
|
+
"operatingSystem": "######",
|
|
207
|
+
"buildVersion": "######",
|
|
208
|
+
"browser": "######",
|
|
209
|
+
"assistiveTechnology": "JAWS\nNVDA\nVoiceOver\nTalkBack"
|
|
210
|
+
}
|
|
211
|
+
},
|
|
212
|
+
{
|
|
213
|
+
"file": "wip-text-does-not-meet-minimum-contrast-requirements.md",
|
|
214
|
+
"title": "[WIP] Text does not meet minimum contrast requirements",
|
|
215
|
+
"severity": "3-Average",
|
|
216
|
+
"suggestedPriority": "Medium",
|
|
217
|
+
"fields": {
|
|
218
|
+
"urlPath": "######",
|
|
219
|
+
"stepsToReproduce": "######",
|
|
220
|
+
"element": "(## Tester note: Describe where the text is in the UI and delete me ##)",
|
|
221
|
+
"whatIsTheIssue": "The following text elements do not meet minimum contrast requirements: \n\nText Element: \nForeground: #xxxxxx \nBackground: #xxxxxx \nCurrent Contrast Ratio: x.x:1",
|
|
222
|
+
"whyItIsImportant": "Good contrast is essential for everyone, particularly for people with low vision, color blindness, or those viewing your website on a mobile device in bright or sunny conditions. If the text doesn't meet WCAG color contrast ratio minimums, it can be difficult for users to read, impacting their overall experience. This applies to any visible element, except those intentionally hidden or sized at 1px by 1px (tracking pixels).",
|
|
223
|
+
"codeReference": "(## Tester note: CSS code references can be helpful here – delete me ##)\n{code:css}\n...\n{code}",
|
|
224
|
+
"howToFix": "- Ensure that text and background colors meet the minimum contrast requirement.\n- Regular Text: For regular size text less than 24px text (or 18.5px if bold), a contrast ratio of at least 4.5:1 is necessary.\n- Large Text: Anything over 24px (or 18.5px if bold) must meet a color contrast ratio of 3:1.\nNote: Partner with Designers to get appropriate colors for use.",
|
|
225
|
+
"compliantCodeExample": "(## Tester note: n/a here if not applicable and is a design change and delete me ##)\n{code:css}\n...\n{code}",
|
|
226
|
+
"howToTest": "Automated: Use an automated accessibility testing tool to test for the existence the color contrast issue. E.g axe DevTools Chrome extension, Level Access Chrome Extension, ANDI\n\nManual: Using Chrome DevTools, inspect the text. You can click on the color swatch in the CSS pane to see the calculated color contrast if a background is defined for the container it lives within.\n\nAlternatively, you can get the foreground hex code using Chrome DevTools by inspecting the text. Using an online color contrast tool such as Deque Color Contrast tool to compare the foreground and background. https://dequeuniversity.com/color-contrast\n\nThe foreground and background comparisons should meet the required WCAG minimums. 4.5:1 or 3:1 based on calculated text sizes.",
|
|
227
|
+
"magentaa11y": "https://www.magentaa11y.com/how-to-test/color-contrast/",
|
|
228
|
+
"resources": "######",
|
|
229
|
+
"wcag": "1.4.3 Contrast (Minimum) (AA)",
|
|
230
|
+
"operatingSystem": "######",
|
|
231
|
+
"buildVersion": "######",
|
|
232
|
+
"browser": "######",
|
|
233
|
+
"assistiveTechnology": "n/a"
|
|
234
|
+
}
|
|
235
|
+
}
|
|
236
|
+
]
|