Added example for customizing a default accessibility check (#12267)

Co-authored-by: Albina <51043550+albinazs@users.noreply.github.com>
Co-authored-by: Thibaud Colas <thibaudcolas@gmail.com>

CHANGELOG.txt

@@ -34,6 +34,7 @@ Changelog
  * Docs: Create a new documentation section for deployment and move fly.io deployment from the tutorial to this section (Vince Salvino)
  * Docs: Clarify process for UserViewSet customization (Sage Abdullah)
  * Docs: Correct `WAGTAIL_WORKFLOW_REQUIRE_REAPPROVAL_ON_EDIT` documentation to state that it defaults to `False` (Matt Westcott)
+ * Docs: Add an example of customizing a default accessibility check (Cynthia Kiser)
  * Maintenance: Removed support for Python 3.8 (Matt Westcott)
  * Maintenance: Drop pytz dependency in favour of `zoneinfo.available_timezones` (Sage Abdullah)
  * Maintenance: Relax django-taggit dependency to allow 6.0 (Matt Westcott)

docs/advanced_topics/accessibility_considerations.md

@@ -146,6 +146,71 @@ By default, the checker includes the following rules to find common accessibilit
 
 To customize how the checker is run (such as what rules to test), you can define a custom subclass of {class}`~wagtail.admin.userbar.AccessibilityItem` and override the attributes to your liking. Then, swap the instance of the default `AccessibilityItem` with an instance of your custom class via the [`construct_wagtail_userbar`](construct_wagtail_userbar) hook.
 
+For example, Axe's [`p-as-heading`](https://github.com/dequelabs/axe-core/blob/develop/lib/checks/navigation/p-as-heading.json) rule evaluates combinations of font weight, size, and italics to decide if a paragraph is acting as a heading visually. Depending on your heading styles, you might want Axe to rely only on font weight to flag short, bold paragraphs as potential headings.
+
+
+```python
+from wagtail.admin.userbar import AccessibilityItem
+
+
+class CustomAccessibilityItem(AccessibilityItem):
+    axe_custom_checks = [
+        {
+	    # Flag heading-like paragraphs based only on font weight compared to surroundings.
+            "id": "p-as-heading",
+            "options": {
+                "margins": [
+                    { "weight": 150 },
+                ],
+                "passLength": 1,
+                "failLength": 0.5
+            },
+        },
+    ]
+
+
+@hooks.register('construct_wagtail_userbar')
+def replace_userbar_accessibility_item(request, items):
+    items[:] = [CustomAccessibilityItem() if isinstance(item, AccessibilityItem) else item for item in items]
+```
+
+The checks you run in production should be restricted to issues your content editors can fix themselves; warnings about things out of their control will only teach them to ignore all warnings. However, it may be useful for you to run additional checks in your development environment.
+
+```python
+from wagtail.admin.userbar import AccessibilityItem
+
+
+class CustomAccessibilityItem(AccessibilityItem):
+    # Run all Axe rules with these tags in the development environment
+    axe_rules_in_dev = [
+        "wcag2a",
+        "wcag2aa",
+        "wcag2aaa",
+        "wcag21a",
+        "wcag21aa",
+        "wcag22aa",
+        "best-practice",
+    ]
+    # Except for the color-contrast-enhanced rule
+    axe_rules = {
+        "color-contrast-enhanced": {"enabled": False},
+    }
+
+    def get_axe_run_only(self, request):
+        if env.bool('DEBUG', default=False):
+            return self.axe_rules_in_dev
+        else:
+            # In production, run Wagtail's default accessibility rules for authored content only
+            return self.axe_run_only
+
+
+@hooks.register('construct_wagtail_userbar')
+def replace_userbar_accessibility_item(request, items):
+    items[:] = [CustomAccessibilityItem() if isinstance(item, AccessibilityItem) else item for item in items]
+```
+
+#### AccessibilityItem reference
+
 The following is the reference documentation for the `AccessibilityItem` class:
 
 ```{eval-rst}
@@ -183,40 +248,6 @@ The following is the reference documentation for the `AccessibilityItem` class:
     .. automethod:: get_axe_spec
 ```
 
-Here is an example of a custom `AccessibilityItem` subclass that enables more rules:
-
-```python
-from wagtail.admin.userbar import AccessibilityItem
-
-
-class CustomAccessibilityItem(AccessibilityItem):
-    # Run all rules with these tags
-    axe_run_only = [
-        "wcag2a",
-        "wcag2aa",
-        "wcag2aaa",
-        "wcag21a",
-        "wcag21aa",
-        "wcag22aa",
-        "best-practice",
-    ]
-    # Except for the color-contrast-enhanced rule
-    axe_rules = {
-        "color-contrast-enhanced": {"enabled": False},
-    }
-
-    def get_axe_rules(self, request):
-        # Do not disable any rules if the user is a superuser
-        if request.user.is_superuser:
-            return {}
-        return self.axe_rules
-
-
-@hooks.register('construct_wagtail_userbar')
-def replace_userbar_accessibility_item(request, items):
-    items[:] = [CustomAccessibilityItem() if isinstance(item, AccessibilityItem) else item for item in items]
-```
-
 ### wagtail-accessibility
 
 [wagtail-accessibility](https://github.com/neon-jungle/wagtail-accessibility) is a third-party package which adds [tota11y](https://blog.khanacademy.org/tota11y-an-accessibility-visualization-toolkit/) to Wagtail previews.

docs/releases/6.3.md

@@ -52,6 +52,7 @@ This release adds formal support for Django 5.1.
  * Create a new documentation section for [deployment](deployment_guide) and move `fly.io` deployment from the tutorial to this section (Vince Salvino)
  * Clarify process for [UserViewSet customization](custom_userviewset) (Sage Abdullah)
  * Correct `WAGTAIL_WORKFLOW_REQUIRE_REAPPROVAL_ON_EDIT` documentation to state that it defaults to `False` (Matt Westcott)
+ * Add an example of customizing a default accessibility check (Cynthia Kiser)
 
 
 ### Maintenance