From 57b5021b587e6a30d8c6115de7eabccc6281faa1 Mon Sep 17 00:00:00 2001 From: Albina Starykova Date: Tue, 25 Jun 2024 12:19:25 +0300 Subject: [PATCH] Add docs --- client/src/includes/a11y-result.ts | 2 +- .../accessibility_considerations.md | 6 ++++++ wagtail/admin/userbar.py | 16 ++++++++-------- 3 files changed, 15 insertions(+), 9 deletions(-) diff --git a/client/src/includes/a11y-result.ts b/client/src/includes/a11y-result.ts index b24fdccd8885..45ee165c9c0c 100644 --- a/client/src/includes/a11y-result.ts +++ b/client/src/includes/a11y-result.ts @@ -74,7 +74,7 @@ export const getAxeConfiguration = ( /** * Custom rule for checking image alt text. This rule checks if the alt text for images - * contains poor quality text like file extensions or URLs. + * contains poor quality text like file extensions. * The rule will be added via the Axe.configure() API. * https://github.com/dequelabs/axe-core/blob/master/doc/API.md#api-name-axeconfigure */ diff --git a/docs/advanced_topics/accessibility_considerations.md b/docs/advanced_topics/accessibility_considerations.md index 8e125e9315e7..9833fa7886ae 100644 --- a/docs/advanced_topics/accessibility_considerations.md +++ b/docs/advanced_topics/accessibility_considerations.md @@ -142,6 +142,7 @@ By default, the checker includes the following rules to find common accessibilit - `input-button-name`: `` button elements must always have a text label. - `link-name`: `` link elements must always have a text label. - `p-as-heading`: This rule checks for paragraphs that are styled as headings. Paragraphs should not be styled as headings, as they don’t help users who rely on headings to navigate content. +- `alt-text-quality`: A custom rule ensures that image alt texts don't contain antipatterns like file extensions. 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. @@ -155,6 +156,8 @@ The following is the reference documentation for the `AccessibilityItem` class: .. autoattribute:: axe_run_only :no-value: .. autoattribute:: axe_rules + .. autoattribute:: axe_custom_rules + .. autoattribute:: axe_custom_checks .. autoattribute:: axe_messages :no-value: @@ -167,12 +170,15 @@ The following is the reference documentation for the `AccessibilityItem` class: .. method:: get_axe_exclude(request) .. method:: get_axe_run_only(request) .. method:: get_axe_rules(request) + .. method:: get_axe_custom_rules(request) + .. method:: get_axe_custom_checks(request) .. method:: get_axe_messages(request) For more advanced customization, you can also override the following methods: .. automethod:: get_axe_context .. automethod:: get_axe_options + .. automethod:: get_axe_spec ``` Here is an example of a custom `AccessibilityItem` subclass that enables more rules: diff --git a/wagtail/admin/userbar.py b/wagtail/admin/userbar.py index 0ce91d3c1ce2..1fb7b0b032be 100644 --- a/wagtail/admin/userbar.py +++ b/wagtail/admin/userbar.py @@ -67,7 +67,7 @@ class AccessibilityItem(BaseItem): #: or to override the properties of existing Axe rules. A custom rule #: to check the quality of the images alt texts is added to the list #: and enabled by default. This rule ensures that alt texts don't contain - #: antipatterns like file extensions or URLs. Returns zero false positives. + #: antipatterns like file extensions. Returns zero false positives. #: Should be used in conjunction with `axe_custom_checks` #: For more details, see `Axe documentation `_. axe_custom_rules = [ @@ -147,13 +147,6 @@ def get_axe_custom_checks(self, request): """List of check objects per axe.run API, without evaluate function.""" return self.axe_custom_checks - def get_axe_spec(self, request): - """Returns spec for Axe, including custom rules and custom checks""" - return { - "rules": self.get_axe_custom_rules(request), - "checks": self.get_axe_custom_checks(request), - } - def get_axe_messages(self, request): """Returns a dictionary that maps axe-core rule IDs to custom translatable strings.""" return self.axe_messages @@ -188,6 +181,13 @@ def get_axe_options(self, request): options.pop("runOnly") return options + def get_axe_spec(self, request): + """Returns spec for Axe, including custom rules and custom checks""" + return { + "rules": self.get_axe_custom_rules(request), + "checks": self.get_axe_custom_checks(request), + } + def get_axe_configuration(self, request): return { "context": self.get_axe_context(request),