Jeux de règles personnalisés

La commande axe ruleset génère des fichiers de règles JSON qui contrôlent quelles règles d'accessibilité axe exécute et comment elles se comportent. Il existe deux flux de travail :

• Configurations de directives standard : Générez une configuration pré-construite filtrée selon une norme d'accessibilité spécifique (WCAG 2.2, Section 508, etc.).
• Jeux de règles personnalisés : Modifiez ou étendez les règles existantes d'axe-core (ou définissez-en de nouvelles) en décrivant vos changements dans un fichier d'entrée changes.json. Le nom de fichier requis changes.json est celui que axe ruleset utilise pour localiser vos modifications.

Les deux flux de travail produisent un fichier JSON en sortie. Pour l'appliquer lors de l'analyse, passez-le à l'option --custom de la commande d'analyse :

# Standard config workflow
axe ruleset --wcag22                          # generates wcag22.json
axe <url> --custom wcag22.json

# Custom ruleset workflow
axe ruleset --custom ./my-changes/            # reads changes.json from the directory, generates axe-ruleset.json
axe <url> --custom axe-ruleset.json

Configurations de directives standard

Ces options génèrent un fichier JSON pré-configuré pour une norme d'accessibilité spécifique. L'argument optionnel [filename] définit le nom du fichier de sortie ; s'il est omis, le fichier est nommé <standard>.json (par exemple, wcag22.json). Les fichiers sont écrits dans le répertoire courant sauf si vous spécifiez une destination avec -d, --destination.

Exécuter axe ruleset sans aucun de ces drapeaux génère des fichiers de configuration individuels pour toutes les normes prises en charge à la fois.

--all [filename]

Génère un seul fichier JSON contenant toutes les règles et vérifications axe-core, avec chaque règle définie à enabled: false. Utilisez ceci comme point de départ lorsque vous souhaitez une configuration à opt-in. Chaque règle est désactivée par défaut, et vous activez uniquement les règles que vous choisissez en modifiant le fichier.

Options de configuration standard

-d, --destination <path>

Répertoire de sortie pour le fichier JSON généré. Par défaut, le répertoire courant.

-f, --format [format]

Format de sortie : json (par défaut) ou js.

-l, --log

Imprimez une liste de toutes les règles incluses dans le fichier généré sur la console.

-a, --axe-source <path>

Chemin vers un fichier source axe-core personnalisé. Utilisez ceci si vous devez générer des configurations pour une version spécifique ou corrigée d'axe-core.

Jeux de règles personnalisés

Un jeu de règles personnalisé vous permet de modifier le comportement des règles axe-core existantes ou de définir de nouvelles règles entièrement. Les changements sont décrits dans un fichier changes.json, qui utilise le même format que l'objet passé à axe.configure().

Parmi les actions possibles avec des jeux de règles personnalisés, vous pouvez :

• Modifier le niveau d'impact des résultats d'un contrôle (par exemple, abaisser serious à minor)
• Désactiver les règles qui ne s'appliquent pas à votre contexte
• Créer de nouvelles règles pour faire respecter la politique d'accessibilité de votre organisation
• Restreindre les techniques acceptées pour une exigence donnée (par exemple, interdire title comme nom accessible pour les images)
• Modifier les seuils de contraste dans la règle color-contrast
• Mettre à jour les rôles et propriétés ARIA pris en charge

Générer un jeu de règles personnalisé

Pour générer un jeu de règles personnalisé, créez un fichier changes.json décrivant vos modifications, puis exécutez axe ruleset --custom <directory>, où <directory> est le dossier contenant vos changes.json. Si vous omettez --custom, le répertoire courant est utilisé.

Le fichier changes.json peut spécifier des modifications aux règles et contrôles d'axe-core existants, ainsi que de nouvelles règles ou contrôles.

Notez que l'impact est une propriété des vérifications, pas des règles. Bien que la sortie générée axe-ruleset.json affiche un champ impact sur chaque règle, il s'agit d'une valeur résolue calculée à partir des vérifications sous-jacentes de la règle ; ce n'est pas quelque chose que vous définissez sur une règle dans changes.json. Placer impact directement sur une règle dans votre fichier d'entrée entraînera une erreur.

Pour modifier la gravité perçue des résultats d'une règle, modifiez l'impact sur la vérification sous-jacente. Par exemple, pour changer la vérification valid-lang de serious à minor :

{
    "checks": [{
        "id": "valid-lang",
        "metadata": {
            "impact": "minor"
        }
    }]
}

{
    "rules": [{
        "id": "valid-lang",
        "impact": "minor"
    }]
}

Enregistrez cela comme changes.json dans un répertoire et exécutez :

axe ruleset --custom ./my-changes/

Utilisation des répertoires de règles et de vérifications

Pour des personnalisations plus complexes, vous pouvez organiser de nouvelles règles et vérifications dans des répertoires rules/ et checks/ séparés aux côtés de changes.json. Chaque règle ou vérification est son propre fichier JSON. Cela ne change pas la sortie générée, mais facilite la gestion de plusieurs règles et vérifications personnalisées.

Par exemple, pour créer une nouvelle règle appelée h1-no-duplicate qui vérifie la présence de plus d'un <h1> sur une page :

directory
 ├ changes.json
 ├ rules
 │  └ h1-no-duplicate.json
 └ checks
    └ page-no-duplicate-h1.json

Parce que la règle et la vérification sont définies dans des fichiers séparés, changes.json est un objet vide :

{}

Le fichier de règle h1-no-duplicate.json définit quelles vérifications exécuter :

{
    "id": "h1-no-duplicate",
    "selector": "h1:not([role]), [role=heading][aria-level=1]",
    "tags": ["cat.semantics", "best-practice"],
    "metadata": {
        "description": "Ensures the document has at most one h1 element",
        "help": "Document must not have more than one h1 element"
    },
    "all": [],
    "any": ["page-no-duplicate-h1"],
    "none": []
}

Le fichier de vérification page-no-duplicate-h1.json définit la vérification et ses messages de résultat :

{
    "id": "page-no-duplicate-h1",
    "evaluate": "page-no-duplicate-evaluate",
    "after": "page-no-duplicate-after",
    "options": {
        "selector": "h1:not([role]), [role=heading][aria-level=1]"
    },
    "metadata": {
        "impact": "moderate",
        "messages": {
            "pass": "Document does not have more than one h1 element",
            "fail": "Document has more than one h1 element"
        }
    }
}

Les champs evaluate et after se réfèrent aux IDs de fonction JavaScript qui implémentent la logique de vérification. Pour les vérifications qui modifient une vérification axe-core existant, utilisez l'ID d'une fonction évaluer ou après existante de axe-core. Pour des vérifications entièrement nouvelles, vous devez également enregistrer les fonctions JavaScript correspondantes auprès d'axe-core. Voir la documentation API axe-core pour plus de détails.

Après avoir exécuté axe ruleset --custom, le JSON généré combine les définitions de règle et de vérification en un seul fichier (partie pertinente montrée) :

{
    "rules": [{
        "id": "h1-no-duplicate",
        "selector": "h1:not([role]), [role=heading][aria-level=1]",
        "tags": ["cat.semantics", "best-practice"],
        "metadata": {
            "description": "Ensures the document has at most one h1 element",
            "help": "Document must not have more than one h1 element"
        },
        "all": [],
        "any": ["page-no-duplicate-h1"],
        "none": [],
        "enabled": true
    }],
    "checks": [{
        "id": "page-no-duplicate-h1",
        "evaluate": "page-no-duplicate-evaluate",
        "after": "page-no-duplicate-after",
        "options": {
            "selector": "h1:not([role]), [role=heading][aria-level=1]"
        },
        "metadata": {
            "impact": "moderate",
            "messages": {
                "pass": "Document does not have more than one h1 element",
                "fail": "Document has more than one h1 element"
            }
        },
        "enabled": true
    }]
}

Options de jeu de règles personnalisé

-c, --custom [path]

Chemin vers le répertoire contenant votre fichier changes.json (et les sous-répertoires optionnels rules/ et checks/). Par défaut, c'est le répertoire actuel.

-t, --tags <list>

Liste séparée par des virgules de étiquettes axe-core utilisée pour filtrer quelles règles du jeu de règles standard axe-core sont incluses dans la sortie.

-x, --disable-other-rules

Désactive toutes les règles axe-core non explicitement incluses dans la propriété rules de changes.json ou du répertoire rules/. Activé par défaut, de sorte que le jeu de règles généré remplace le jeu de règles complet d'axe-core plutôt que de l'étendre ; seules vos règles personnalisées sont exécutées. Passez --no-disable-other-rules pour inclure toutes les règles axe-core standard avec vos règles personnalisées.

--only-changes

Valide uniquement avec --custom. Générez uniquement les modifications et ajouts décrits dans changes.json, sans les définitions complètes des règles et vérifications axe-core. Produit un fichier plus petit adapté pour être utilisé comme superposition sur un ensemble de règles existant.

-d, --destination <path>, -f, --format, -l, --log, -a, --axe-source <path>

Voir Options de configuration standard. Ces options s'appliquent également aux jeux de règles personnalisés.

Chargement d'un jeu de règles

Il existe trois façons d'appliquer un jeu de règles généré lors de l'analyse. Elles sont vérifiées dans cet ordre :

1. Variable d'environnement : Définissez AXE_RULESET_PATH sur le chemin du fichier de jeu de règles. Ceci a priorité sur toutes les autres méthodes et s'applique à toutes les exécutions dans cet environnement.

2. drapeau --custom : Passez explicitement le fichier de jeu de règles en utilisant le drapeau --custom sur axe <url>, axe spec ou axe bulk-spec.

3. Fichier local : Placez un fichier nommé axe-ruleset.json dans le répertoire où axe s'exécute. Il sera utilisé automatiquement si aucun des précédents n'est défini.

Si aucun de ceux-ci n'est spécifié, ou si Axe DevTools ne peut pas charger le fichier spécifié, le jeu de règles par défaut wcag2.1 est utilisé.

Support

La création de jeux de règles personnalisés nécessite une compréhension significative de axe-core. Pour plus de détails, consultez la documentation API axe-core. Si vous souhaitez obtenir de l'assistance pour créer et maintenir votre jeu de règles personnalisé, contactez votre représentant Deque.