arc-templated-issues 1.0.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.
Files changed (23) hide show
  1. package/README.md +126 -0
  2. package/arc-accessibility-issue-template.md +83 -0
  3. package/native/button-lacks-a-label-in-the-code.md +75 -0
  4. package/native/focus-order-is-not-logical.md +69 -0
  5. package/native/heading-trait-is-not-used-in-the-code.md +74 -0
  6. package/native/image-icon-should-be-marked-as-decorative.md +99 -0
  7. package/native/items-should-be-grouped.md +71 -0
  8. package/native/state-is-not-communicated-for-button.md +76 -0
  9. package/package.json +23 -0
  10. package/public/native-issue-templates.md +487 -0
  11. package/public/web-issue-templates.md +912 -0
  12. package/template-mappings.json +58 -0
  13. package/template-mappings.schema.json +45 -0
  14. package/web/control-lacks-a-label-in-the-code.md +81 -0
  15. package/web/heading-levels-incorrectly-nested.md +121 -0
  16. package/web/images-should-be-marked-as-decorative.md +79 -0
  17. package/web/interactive-element-is-not-keyboard-accessible.md +75 -0
  18. package/web/wip-link-text-is-not-descriptive-or-lacks-purpose.md +111 -0
  19. package/web/wip-non-text-content-does-not-meet-required-3-1-contrast.md +74 -0
  20. package/web/wip-screen-reader-focus-is-not-retained-while-navigating-between-modal-views.md +105 -0
  21. package/web/wip-semantic-meaning-of-a-heading-is-not-conveyed-to-a-screen-reader-user.md +82 -0
  22. package/web/wip-semantic-meaning-of-a-list-is-not-conveyed-to-a-screen-reader-user.md +78 -0
  23. package/web/wip-text-does-not-meet-minimum-contrast-requirements.md +77 -0
package/web/wip-screen-reader-focus-is-not-retained-while-navigating-between-modal-views.md ADDED
@@ -0,0 +1,105 @@
1
+ # [WIP] Screen reader focus is not retained while navigating between modal views
2
+
3
+ ## Severity
4
+ 2-Severe
5
+
6
+ ## Suggested Priority
7
+ High
8
+
9
+ -------- copy below ---------
10
+
11
+ [URL/Path]
12
+ ######
13
+
14
+ [Steps to reproduce]
15
+ ######
16
+
17
+ [Element]
18
+ (## Tester note: Describe where the thing is in the UI and delete me ##)
19
+
20
+ [What is the issue]
21
+ 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.
22
+
23
+ (## 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.
24
+
25
+ [Why it is important]
26
+ 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.
27
+
28
+ [Code reference]
29
+ (## Tester note: grab code snippet from experience and delete me ##)
30
+ {code:html}
31
+ ...
32
+ {code}
33
+
34
+ [How to fix]
35
+ 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.
36
+
37
+ [Compliant code example]
38
+ (## Tester note: Choose to add or delete this section if not working in Phoenix/AEM environment ##)
39
+
40
+ While 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:
41
+ {code:html}
42
+ /**
43
+ * Set focus on the heading when the content changes while navigating between promo list to promo details and vice versa.
44
+ *
45
+ * @param visibilityScopeIdTarget - The ID of the visibility scope target to set focus on.
46
+ */
47
+ manageFocus(visibilityScopeIdTarget?: string): void {
48
+ let focusTarget: HTMLElement;
49
+
50
+ if (visibilityScopeIdTarget) {
51
+ focusTarget = document.querySelector(`[data-xpr-visibility-scope="${visibilityScopeIdTarget}"]`) as HTMLElement;
52
+ } else {
53
+ focusTarget = this.component;
54
+ }
55
+ const headings: HTMLHeadingElement[] = Array.from(focusTarget?.querySelectorAll(':is(h1,h2,h3,h4,h5,h6)') || []);
56
+ // Find the first visible heading
57
+ const el = headings.find((heading) => {
58
+ return heading.offsetParent !== null && heading.offsetHeight > 0 && heading.offsetWidth > 0;
59
+ }) as HTMLElement | null;
60
+
61
+ if (el) {
62
+ el.setAttribute('tabindex', '-1');
63
+ el.focus();
64
+ } else {
65
+ (this.component?.closest('.phx-modal') as HTMLElement)?.focus();
66
+ }
67
+ },
68
+
69
+ setTimeout(() => {
70
+ this.manageFocus();
71
+ }, 100);
72
+ {code}
73
+
74
+ [How to test]
75
+ 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.
76
+
77
+ Manual:
78
+ - Open the modal and activate the **"[placeholder name]"** button to change the view.
79
+ - With NVDA or JAWS in browse mode, press the arrow keys after the view changes.
80
+ - Confirm that arrow key navigation starts at the new modal content and does not land outside the modal or on the main page.
81
+ - Activate the back button and repeat the test.
82
+
83
+ [MagentaA11y]
84
+ ######
85
+
86
+ [Resources]
87
+ ######
88
+
89
+ [WCAG]
90
+ 2.4.3 Focus Order (A)
91
+
92
+ [Operating system]
93
+ Windows
94
+
95
+ [Build Version]
96
+ ######
97
+
98
+ [Browser]
99
+ Chrome
100
+ Firefox
101
+ Edge
102
+
103
+ [Assistive technology]
104
+ JAWS
105
+ NVDA
package/web/wip-semantic-meaning-of-a-heading-is-not-conveyed-to-a-screen-reader-user.md ADDED
@@ -0,0 +1,82 @@
1
+ # [WIP] Semantic meaning of a heading is not conveyed to a screen reader user
2
+
3
+ ## Severity
4
+ 3-Average
5
+
6
+ ## Suggested Priority
7
+ Medium
8
+
9
+ -------- copy below ---------
10
+
11
+ [URL/Path]
12
+ ######
13
+
14
+ [Steps to reproduce]
15
+ ######
16
+
17
+ [Element]
18
+ (## Tester note: Describe where the thing is in the UI and delete me ##)
19
+
20
+ [What is the issue]
21
+ 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.
22
+
23
+ The 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>`).
24
+
25
+ [Why it is important]
26
+ 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.
27
+
28
+ Screen 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.
29
+
30
+ [Code reference]
31
+ (## Tester note: CSS code references can be helpful here – delete me ##)
32
+ {code:css}
33
+ ...
34
+ {code}
35
+
36
+ [How to fix]
37
+ Ensure all headings use the appropriate HTML heading tags (`<h1>`, `<h2>`, `<h3>`, etc.) for structuring the content.
38
+
39
+ Do not use non-semantic elements like `<div>` or `<span>` for headings.
40
+
41
+ The 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.
42
+
43
+ [Compliant code example]
44
+ (## Tester note: n/a here if not applicable and is a design change and delete me ##)
45
+ {code:html}
46
+ ...
47
+ {code}
48
+
49
+ [How to test]
50
+ Automated:
51
+ Use 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.
52
+
53
+ Manual:
54
+ 1. Navigate through the page using a screen reader (e.g., VoiceOver for MacOS or NVDA for Windows).
55
+ - For VoiceOver, use VO keys + Command + H to skip around by heading
56
+ - For NVDA, use "H" key to skip around by heading
57
+ 2. Ensure that all headings are conveyed as distinct, sequentially organized elements, and the content hierarchy makes sense.
58
+ 3. Inspect the HTML structure to verify that proper HTML tags are used instead of non-semantic elements.
59
+
60
+ [MagentaA11y]
61
+ https://www.magentaa11y.com/checklist-web/heading/
62
+
63
+ [Resources]
64
+ ######
65
+
66
+ [WCAG]
67
+ 1.3.1 Info and Relationships (A)
68
+
69
+ [Operating system]
70
+ ######
71
+
72
+ [Build Version]
73
+ ######
74
+
75
+ [Browser]
76
+ ######
77
+
78
+ [Assistive technology]
79
+ JAWS
80
+ NVDA
81
+ VoiceOver
82
+ TalkBack
package/web/wip-semantic-meaning-of-a-list-is-not-conveyed-to-a-screen-reader-user.md ADDED
@@ -0,0 +1,78 @@
1
+ # [WIP] Semantic meaning of a list is not conveyed to a screen reader user
2
+
3
+ ## Severity
4
+ 3-Average
5
+
6
+ ## Suggested Priority
7
+ Medium
8
+
9
+ -------- copy below ---------
10
+
11
+ [URL/Path]
12
+ ######
13
+
14
+ [Steps to reproduce]
15
+ ######
16
+
17
+ [Element]
18
+ (## Tester note: Describe where the thing is in the UI and delete me ##)
19
+
20
+ [What is the issue]
21
+ 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.
22
+
23
+ The 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>`).
24
+
25
+ [Why it is important]
26
+ 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").
27
+
28
+ If 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.
29
+
30
+ [Code reference]
31
+ (## Tester note: CSS code references can be helpful here – delete me ##)
32
+ {code:css}
33
+ ...
34
+ {code}
35
+
36
+ [How to fix]
37
+ Ensure all lists use the appropriate HTML list tags (`<ul>`, `<ol>`, and `<li>` for both) for structuring content.
38
+
39
+ Note: VoiceOver does not announce `<ul>` or `<ol>` when CSS styling removes their numbering or bullets.
40
+
41
+ [Compliant code example]
42
+ (## Tester note: n/a here if not applicable and is a design change and delete me ##)
43
+ {code:html}
44
+ ...
45
+ {code}
46
+
47
+ [How to test]
48
+ Automated:
49
+ Use 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.
50
+
51
+ Manual:
52
+ 1. Navigate through the page using a screen reader (e.g., VoiceOver for MacOS or NVDA for Windows).
53
+ 2. Ensure that all lists are conveyed as distinct, sequentially organized elements, and the content hierarchy makes sense.
54
+ 3. Inspect the HTML structure to verify that proper HTML tags are used instead of non-semantic elements.
55
+
56
+ [MagentaA11y]
57
+ https://www.magentaa11y.com/checklist-web/list/
58
+
59
+ [Resources]
60
+ ######
61
+
62
+ [WCAG]
63
+ 1.3.1 Info and Relationships (A)
64
+
65
+ [Operating system]
66
+ ######
67
+
68
+ [Build Version]
69
+ ######
70
+
71
+ [Browser]
72
+ ######
73
+
74
+ [Assistive technology]
75
+ JAWS
76
+ NVDA
77
+ VoiceOver
78
+ TalkBack
package/web/wip-text-does-not-meet-minimum-contrast-requirements.md ADDED
@@ -0,0 +1,77 @@
1
+ # [WIP] Text does not meet minimum contrast requirements
2
+
3
+ ## Severity
4
+ 3-Average
5
+
6
+ ## Suggested Priority
7
+ Medium
8
+
9
+ -------- copy below ---------
10
+
11
+ [URL/Path]
12
+ ######
13
+
14
+ [Steps to reproduce]
15
+ ######
16
+
17
+ [Element]
18
+ (## Tester note: Describe where the text is in the UI and delete me ##)
19
+
20
+ [What is the issue]
21
+ The following text elements do not meet minimum contrast requirements:
22
+
23
+ Text Element:
24
+ Foreground: #xxxxxx
25
+ Background: #xxxxxx
26
+ Current Contrast Ratio: x.x:1
27
+
28
+ [Why it is important]
29
+ 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).
30
+
31
+ [Code reference]
32
+ (## Tester note: CSS code references can be helpful here – delete me ##)
33
+ {code:css}
34
+ ...
35
+ {code}
36
+
37
+ [How to fix]
38
+ - Ensure that text and background colors meet the minimum contrast requirement.
39
+ - 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.
40
+ - Large Text: Anything over 24px (or 18.5px if bold) must meet a color contrast ratio of 3:1.
41
+ Note: Partner with Designers to get appropriate colors for use.
42
+
43
+ [Compliant code example]
44
+ (## Tester note: n/a here if not applicable and is a design change and delete me ##)
45
+ {code:css}
46
+ ...
47
+ {code}
48
+
49
+ [How to test]
50
+ 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
51
+
52
+ Manual: 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.
53
+
54
+ Alternatively, 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
55
+
56
+ The foreground and background comparisons should meet the required WCAG minimums. 4.5:1 or 3:1 based on calculated text sizes.
57
+
58
+ [MagentaA11y]
59
+ https://www.magentaa11y.com/how-to-test/color-contrast/
60
+
61
+ [Resources]
62
+ ######
63
+
64
+ [WCAG]
65
+ 1.4.3 Contrast (Minimum) (AA)
66
+
67
+ [Operating system]
68
+ ######
69
+
70
+ [Build Version]
71
+ ######
72
+
73
+ [Browser]
74
+ ######
75
+
76
+ [Assistive technology]
77
+ n/a