diff --git a/CHANGELOG.txt b/CHANGELOG.txt index 64acc385cd28..80fd50c9c7de 100644 --- a/CHANGELOG.txt +++ b/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) diff --git a/docs/advanced_topics/accessibility_considerations.md b/docs/advanced_topics/accessibility_considerations.md index a3da86d4b0d1..269818d7d2c1 100644 --- a/docs/advanced_topics/accessibility_considerations.md +++ b/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. diff --git a/docs/releases/6.3.md b/docs/releases/6.3.md index 37c696301174..a7439d6230ec 100644 --- a/docs/releases/6.3.md +++ b/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