Update a11y guidelines

docs/source/contributing/accessibility-guidelines.md

@@ -9,16 +9,78 @@ myst:
 
 # Accessibility guidelines
 
-Attention should be paid to improve and maintain accessibility. In documentation, code and filenames you will often see this abbreviated as "a11y".
+Attention should be paid to improve and maintain accessibility, abbreviated as "a11y".
 
-## Clickable elements that have a symbol or icon and no visible text
 
-If the symbol or icon is clear enough for sighted users, for instance a big "X" to close a dialog, it will still need a text for screen reader users.
+## Tools
 
-You can achieve a 'hidden' label by setting the property "aria-label" on the element.
-If available, use the translation machinery available to make the label appear in the correct language.
+Volto developers use several tools to analyze and test the accessibility of their projects.
 
-Example:
+[`cypress-axe`](https://github.com/component-driven/cypress-axe)
+:   Automate accessibility testing with [`axe-core`](https://github.com/dequelabs/axe-core) in [Cypress](https://cypress.io/).
+    See also [axe devTools](https://www.deque.com/axe/devtools/), a tool that helps developers check digital content against accessibility standards.
+
+[IBM Equal Access Accessibility Checker browser extensions](https://www.ibm.com/able/toolkit/tools#develop)
+:   Browser extensions that test your code for accessibility issues.
+
+[Accessible Web](https://accessibleweb.com/)
+:   A commercial tool that helps teams discover, understand, and remediate web accessibility issues.
+
+[VoiceOver](https://developer.apple.com/documentation/accessibility/voiceover/)
+:   A gesture-based screen reader that provides an auditory description of the content onscreen for Apple iOS and macOS devices.
+    See [VoiceOver keyboard shortcuts](https://dequeuniversity.com/screenreaders/voiceover-keyboard-shortcuts) for usage.
+
+[A11Y-Color-Blindness-Empathy-Test](https://vinceumo.github.io/A11Y-Color-Blindness-Empathy-Test/)
+:   Help designers and developers to understand color blindness and visual imparity.
+
+[WAI-ARIA - Screen reader compatibility](https://www.powermapper.com/tests/screen-readers/aria/)
+:   Shows how different WAI-ARIA attributes behave in commonly used screen readers.
+    The results include two types of tests.
+
+    -   Expected to work - these tests show support when accessibility features are used correctly
+    -   Expected to fail - these tests show what happens when accessibility features are used incorrectly 
+
+
+
+
+
+## Tests
+
+We use [`cypress-axe`](https://github.com/component-driven/cypress-axe) for automated testing of accessibility in Volto via Cypress.
+
+Place accessibility test files in the directory {file}`packages/volto/cypress/tests/core/a11y/`.
+
+Name accessibility tests `[THING] tested for a11y axe violations`.
+
+
+## Common accessibility issues
+
+This section describes common issues that you might need to address while developing for Volto core or an add-on.
+
+
+### Understanding assistive technology
+
+Simply activating a screen reader is not enough.
+Developers must understand the underlying mechanics of how these tools interpret the DOM to avoid creating technically "valid" but practically unusable interfaces.
+
+Beyond tool usage
+:   Focus on how assistive technologies announce content.
+    For example, understanding how a screen reader handles "live regions" or how it contextually reads labels helps in building more intuitive layouts.
+
+Logical Flow
+:   Developers should learn the common navigation patterns used by people with disabilities, such as navigating by landmarks or form elements, rather than just testing for linear reading.
+
+The "Why" behind ARIA
+:   Instead of overusing ARIA attributes, understand what each one signals to the browser's accessibility tree.
+    Often, the best ARIA is no ARIA at all, favoring native HTML semantics instead.
+
+
+### Clickable elements that have a symbol or icon and no visible text
+
+If the symbol or icon is clear enough for sighted users—for instance a big "X" to close a dialog—it will still need a text for screen reader users.
+
+You can achieve a "hidden" label by setting the property `aria-label` on the element.
+If available, use the translation machinery to make the label appear in the correct language.
 
 ```jsx
 <button className="cancel" aria-label="Cancel" onClick={() => this.onCancel()}>
@@ -31,16 +93,62 @@ Example:
 </button>
 ```
 
-## Do not use `<a>` tags without href
 
-If an element has an event listener on it and performs an action, but does not point to a proper URL, use a `<button>` and style with CSS to style.
-The reasoning is that the `<a></a>` HTML tag has specific behavior that screenreaders support and that screenreader users expect.
+### Do not use `<a>` tags without `href`
+
+If an element has an event listener on it and performs an action, but does not point to a proper URL, use a `<button>` and style with CSS.
+The `<a></a>` HTML tag has specific behavior that screen readers support and users expect.
+
+
+### Make sure form elements have a label
+
+This is true for single element forms as well, such as the "Search" form on the folder contents component.
+Putting an icon on it does not convey any meaning to screen reader users.
+You should clarify it with an `aria-label` attribute.
+
+
+### Interactive states (focus visible)
+
+Developers often remove the default browser outline for aesthetic reasons.
+Hiding the focus indicator without providing a clear visual alternative is a major accessibility violation.
+
+Rule
+:   Every interactive or clickable element must have a distinct `:focus` state.
+
+Guideline
+:   Avoid using `outline: none` in CSS unless you replace it with an equally evident custom focus style.
+    Keyboard users rely on this indicator to know with which element they are interacting.
+
+
+### Semantic heading hierarchy
+
+A frequent mistake when developing components or add-ons is using `<h2>`, `<h3>`, or `<h4>` tags solely to achieve a specific font size.
+
+Recommendation
+:   Always maintain a logical heading order.
+    If a page starts with an `<h1>`, the subsequent subheading must be an `<h2>`, followed by `<h3>`, and so forth.
+
+Impact
+:   Skipping heading levels—for example, jumping from `<h2>` to `<h4>`—breaks the document structure and confuses screen reader users who use headings to navigate the page layout.
+
+
+### Alternative text for images (alt text)
+
+Images must have an `alt` attribute to be accessible.
+However, the way it is implemented depends on the image's purpose.
+
+Informative images
+:   If an image conveys meaning, the `alt` text should be a brief, descriptive equivalent of the information.
+
+Decorative images
+:   If an image is purely for visual styling and contains no information, use an empty alt attribute, `alt=""`.
+    This tells screen readers to skip the image entirely.
 
-## Make sure form elements have a label
+Avoid redundant text
+:   Do not start `alt` text with "Image of..." or "Photo of...", as screen readers already announce that it is an image.
 
-This is true for one-element forms as well, such as the "Search" form on the folder-contents component. Putting an icon on it does not convey any meaning to screenreader-users, you should clarify it with an aria-label.
 
-## Additional information for non-visual users
+### Additional information for non-visual users
 
 Sometimes extra information needs to be provided to users who are not able to see the screen.
 The `.visually-hidden` class can be used to wrap elements which need to be exposed to assistive technologies, such as screen readers, without them being visible.

packages/volto/news/6361.documentation

@@ -0,0 +1 @@
+Update accessibility guidelines. @stevepiercy