Conjuntos de Regras Personalizados

O comando axe ruleset gera arquivos de conjunto de regras JSON que controlam quais regras de acessibilidade axe executa e como elas se comportam. Existem dois fluxos de trabalho:

• Configurações de diretrizes padrão: Gere uma configuração pré-construída filtrada para um padrão específico de acessibilidade (WCAG 2.2, Section 508, etc.).
• Conjuntos de regras personalizados: Modifique ou estenda regras existentes do axe-core (ou defina novas) descrevendo suas alterações em um arquivo de entrada changes.json. O nome de arquivo necessário changes.json é como axe ruleset localiza suas alterações.

Ambos os fluxos de trabalho produzem um arquivo JSON de saída. Para aplicá-lo durante a varredura, passe-o para a flag --custom do comando de varredura:

# 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

Configurações de Diretrizes Padrão

Essas flags geram um arquivo JSON pré-configurado para um padrão específico de acessibilidade. O argumento opcional [filename] define o nome do arquivo de saída; se omitido, o arquivo é nomeado <standard>.json (por exemplo, wcag22.json). Os arquivos são gravados no diretório atual, a menos que você especifique um destino com -d, --destination.

Executar axe ruleset sem nenhuma dessas flags gera arquivos de configuração individuais para todos os padrões suportados de uma só vez.

--all [filename]

Gera um único arquivo JSON contendo todas as regras e verificações do axe-core, com cada regra definida para enabled: false. Use isso como ponto de partida quando você deseja uma configuração de opt-in. Cada regra está desativada por padrão, e você habilita somente as regras que escolher, modificando o arquivo.

Opções de Configuração Padrão

-d, --destination <path>

Diretório de saída para o arquivo JSON gerado. O padrão é o diretório atual.

-f, --format [format]

Formato de saída: json (padrão) ou js.

-l, --log

Imprime uma lista de todas as regras incluídas no arquivo gerado no console.

-a, --axe-source <path>

Caminho para um arquivo de origem customizado do axe-core. Use isso se você precisar gerar configurações para uma versão específica ou corrigida do axe-core.

Conjuntos de Regras Personalizados

Um conjunto de regras personalizado permite que você modifique como as regras existentes do axe-core se comportam ou defina novas regras completamente. As alterações são descritas em um arquivo changes.json, que usa o mesmo formato do objeto passado para axe.configure().

Algumas das ações que você pode realizar com conjuntos de regras personalizadas incluem:

• Alterar o nível de impacto dos resultados de uma verificação (por exemplo, rebaixar serious para minor)
• Desativar regras que não se aplicam ao seu contexto
• Criar novas regras para impor a política de acessibilidade da sua organização
• Restringir quais técnicas são aceitas para um determinado requisito (por exemplo, desautorizar title como um nome acessível para imagens)
• Modificar os limites de contraste na regra color-contrast
• Atualizar quais funções e propriedades ARIA são suportadas

Gerando um Conjunto de Regras Personalizado

Para gerar um conjunto de regras personalizado, crie um arquivo changes.json descrevendo suas alterações, então execute axe ruleset --custom <directory>, onde <directory> é a pasta que contém seu changes.json. Se você omitir --custom, o diretório atual será usado.

O arquivo changes.json pode especificar alterações nas regras e verificações existentes do axe-core, bem como novas regras ou verificações.

Observe que impacto é uma propriedade das verificações, não das regras. Embora a saída gerada axe-ruleset.json mostre um campo impact em cada regra, este é um valor resolvido calculado a partir das verificações subjacentes da regra; não é algo que você define em uma regra em changes.json. Colocar impact diretamente em uma regra no seu arquivo de entrada causará um erro.

Para alterar a severidade percebida dos resultados de uma regra, modifique o impacto na verificação subjacente. Por exemplo, para alterar a verificação valid-lang de serious para minor:

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

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

Salve isso como changes.json em um diretório e execute:

axe ruleset --custom ./my-changes/

Usando Diretórios de Regras e Verificações

Para personalizações mais complexas, você pode organizar novas regras e verificações em diretórios rules/ e checks/ separados, junto com changes.json. Cada regra ou verificação é seu próprio arquivo JSON. Isso não altera a saída gerada, mas facilita o gerenciamento de várias regras e verificações personalizadas.

Por exemplo, para criar uma nova regra chamada h1-no-duplicate que verifica mais de um <h1> em uma página:

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

Como a regra e a verificação estão definidas em arquivos separados, changes.json é um objeto vazio:

{}

O arquivo de regra h1-no-duplicate.json define quais verificações executar:

{
    "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": []
}

O arquivo de verificação page-no-duplicate-h1.json define a verificação e suas mensagens de resultado:

{
    "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"
        }
    }
}

Os campos evaluate e after referenciam IDs de funções JavaScript que implementam a lógica de verificação. Para verificações que modificam uma verificação existente do axe-core, use o ID de uma função existente de avaliação ou após do axe-core. Para verificações totalmente novas, você também deve registrar as funções JavaScript correspondentes com axe-core. Consulte documentação da API do axe-core para detalhes.

Após executar axe ruleset --custom, o JSON gerado combina as definições de regras e verificações em um único arquivo (parte relevante mostrada):

{
    "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
    }]
}

Opções de Conjunto de Regras Personalizadas

-c, --custom [path]

Caminho para o diretório que contém seu arquivo changes.json (e subdiretórios opcionais rules/ e checks/). O padrão é o diretório atual.

-t, --tags <list>

Lista separada por vírgulas de tags do axe-core usada para filtrar quais regras do conjunto de regras padrão do axe-core são incluídas na saída.

-x, --disable-other-rules

Desativa todas as regras do axe-core que não estão explicitamente incluídas na propriedade rules de changes.json ou do diretório rules/. Ativado por padrão, portanto, o conjunto de regras gerado substitui o conjunto de regras completo do axe-core em vez de expandi-lo; apenas suas regras personalizadas são executadas. Passe --no-disable-other-rules para incluir todas as regras padrão do axe-core juntamente com suas personalizadas.

--only-changes

Válido apenas com --custom. Gere apenas as alterações e adições descritas em changes.json, sem as definições completas de regra e verificação do axe-core. Produz um arquivo menor adequado para uso como sobreposição em um conjunto de regras existente.

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

Consulte Opções de Configuração Padrão. Essas opções se aplicam a conjuntos de regras personalizados também.

Carregando um Conjunto de Regras

Existem três maneiras de aplicar um conjunto de regras gerado ao escanear. Elas são verificadas nesta ordem:

1. Variável de ambiente: Defina AXE_RULESET_PATH para o caminho do arquivo do conjunto de regras. Isso tem precedência sobre todos os outros métodos e se aplica a todas as execuções naquele ambiente.

2. flag --custom: Passe o arquivo do conjunto de regras explicitamente usando o flag --custom em axe <url>, axe spec ou axe bulk-spec.

3. Arquivo local: Coloque um arquivo chamado axe-ruleset.json no diretório onde axe é executado. Ele será usado automaticamente se nenhum dos anteriores estiver definido.

Se nenhum destes for especificado, ou se o Axe DevTools não puder carregar o arquivo especificado, o conjunto de regras padrão wcag2.1 é usado.

Suporte

Criar conjuntos de regras personalizados requer um entendimento significativo do axe-core. Para detalhes, veja documentação da API do axe-core. Se você gostaria de suporte na criação e manutenção do seu conjunto de regras personalizado, entre em contato com seu representante Deque.