Reglas Personalizadas

El comando axe ruleset genera archivos de reglas en formato JSON que controlan qué reglas de accesibilidad ejecuta axe y cómo se comportan. Hay dos flujos de trabajo:

• Configuraciones estándar de directrices: Genera una configuración preconstruida filtrada según un estándar de accesibilidad específico (WCAG 2.2, Sección 508, etc.).
• Reglas Personalizadas: Modifica o amplía las reglas existentes de axe-core (o define nuevas) describiendo tus cambios en un archivo de entrada changes.json. El nombre de archivo requerido changes.json es como axe ruleset localiza tus cambios.

Ambos flujos de trabajo producen un archivo JSON de salida. Para aplicarlo al escanear, pásalo con la bandera --custom del comando de escaneo:

# 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

Configuraciones Estándar de Directrices

Estas banderas generan un archivo JSON preconfigurado para un estándar de accesibilidad específico. El argumento opcional [filename] establece el nombre de archivo de salida; si se omite, el archivo se nombra <standard>.json (por ejemplo, wcag22.json). Los archivos se escriben en el directorio actual a menos que especifiques un destino con -d, --destination.

Ejecutar axe ruleset sin ninguna de estas banderas genera archivos de configuración individuales para todos los estándares compatibles a la vez.

--all [filename]

Genera un solo archivo JSON que contiene todas las reglas y verificaciones de axe-core, con cada regla configurada en enabled: false. Usa esto como punto de partida cuando quieras una configuración de inclusión voluntaria. Cada regla está desactivada por defecto y solo habilitas las reglas que elijas modificando el archivo.

Opciones de Configuración Estándar

-d, --destination <path>

Directorio de salida para el archivo JSON generado. Por defecto, el directorio actual.

-f, --format [format]

Formato de salida: json (por defecto) o js.

-l, --log

Imprime en la consola una lista de todas las reglas incluidas en el archivo generado.

-a, --axe-source <path>

Ruta a un archivo fuente personalizado de axe-core. Usa esto si necesitas generar configuraciones contra una versión específica o parcheada de axe-core.

Reglas Personalizadas

Un juego de reglas personalizadas te permite modificar cómo se comportan las reglas existentes de axe-core o definir reglas nuevas por completo. Los cambios se describen en un archivo changes.json, que usa el mismo formato que el objeto pasado a axe.configure().

Algunas de las cosas que puedes hacer con los juegos de reglas personalizados incluyen:

• Cambiar el nivel de impacto de los resultados de una verificación (por ejemplo, degradar serious a minor)
• Deshabilitar reglas que no se aplican a tu contexto
• Crear nuevas reglas para imponer la política de accesibilidad de tu organización
• Restringir qué técnicas son aceptadas para un requisito dado (por ejemplo, no permitir title como nombre accesible para imágenes)
• Modificar los umbrales de contraste en la regla color-contrast
• Actualizar qué roles y propiedades ARIA son compatibles

Generar un Juego de Reglas Personalizado

Para generar un juego de reglas personalizado, crea un archivo changes.json describiendo tus cambios y luego ejecuta axe ruleset --custom <directory>, donde <directory> es la carpeta que contiene tu changes.json. Si omites --custom, se utiliza el directorio actual.

El archivo changes.json puede especificar cambios a las reglas y verificaciones existentes de axe-core, así como nuevas reglas o verificaciones.

Tenga en cuenta que el impacto es una propiedad de las verificaciones, no de las reglas. Aunque la salida generada por axe-ruleset.json muestra un campo impact en cada regla, este es un valor resuelto calculado a partir de las verificaciones subyacentes de la regla; no es algo que se establezca en una regla en changes.json. Colocar impact directamente en una regla en su archivo de entrada causará un error.

Para cambiar la gravedad percibida de los hallazgos de una regla, modifique el impacto en la verificación subyacente. Por ejemplo, para cambiar la verificación de valid-lang de serious a minor:

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

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

Guarde esto como changes.json en un directorio y ejecute:

axe ruleset --custom ./my-changes/

Usar directorios de Reglas y Verificaciones

Para personalizaciones más complejas, puede organizar nuevas reglas y verificaciones en directorios separados de rules/ y checks/ junto a changes.json. Cada regla o verificación es su propio archivo JSON. Esto no cambia la salida generada, pero facilita la gestión de múltiples reglas y verificaciones personalizadas.

Por ejemplo, para crear una nueva regla llamada h1-no-duplicate que verifica más de un <h1> en una página:

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

Debido a que la regla y la verificación se definen en archivos separados, changes.json es un objeto vacío:

{}

El archivo de reglas h1-no-duplicate.json define qué verificaciones ejecutar:

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

El archivo de verificación page-no-duplicate-h1.json define la verificación y sus mensajes 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"
        }
    }
}

Los campos evaluate y after hacen referencia a los IDs de funciones de JavaScript que implementan la lógica de verificación. Para las verificaciones que modifican una verificación de axe-core existente, use el ID de una función existente de evaluación o de posproceso de axe-core. Para verificaciones completamente nuevas, también debe registrar las funciones de JavaScript correspondientes con axe-core. Vea la documentación de la API de axe-core para más detalles.

Después de ejecutar axe ruleset --custom, el JSON generado combina las definiciones de reglas y verificaciones en un solo archivo (porción 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
    }]
}

Opciones de Conjunto de Reglas Personalizado

-c, --custom [path]

Ruta al directorio que contiene su archivo changes.json (y opcionalmente los subdirectorios rules/ y checks/). Por defecto es el directorio actual.

-t, --tags <list>

Lista separada por comas de etiquetas de axe-core utilizada para filtrar qué reglas del conjunto de reglas estándar de axe-core se incluyen en la salida.

-x, --disable-other-rules

Desactiva todas las reglas de axe-core que no se incluyan explícitamente en la propiedad rules de changes.json o en el directorio rules/. Activado por defecto, de modo que el conjunto de reglas generado reemplaza al conjunto de reglas completo de axe-core en lugar de extenderlo; solo sus reglas personalizadas se ejecutan. Pase --no-disable-other-rules para incluir todas las reglas estándar de axe-core junto a sus personalizadas.

--only-changes

Solo válido con --custom. Genera solo los cambios y adiciones descritos en changes.json, sin las definiciones completas de reglas y verificaciones de axe-core. Produce un archivo más pequeño adecuado para usar como una superposición sobre un conjunto de reglas existente.

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

Vea Opciones de Configuración Estándar. Estas opciones también se aplican a conjuntos de reglas personalizadas.

Cargando un Conjunto de Reglas

Hay tres maneras de aplicar un conjunto de reglas generado al escanear. Se revisan en este orden:

1. Variable de entorno: Establezca AXE_RULESET_PATH en la ruta del archivo del conjunto de reglas. Esto tiene prioridad sobre todos los demás métodos y se aplica a todas las ejecuciones en ese entorno.

2. bandera --custom: Pase el archivo del conjunto de reglas explícitamente usando la bandera --custom en axe <url>, axe spec, o axe bulk-spec.

3. Archivo local: Coloque un archivo llamado axe-ruleset.json en el directorio donde se ejecuta axe. Se usará automáticamente si ninguno de los anteriores está configurado.

Si no se especifica ninguno de estos, o si Axe DevTools no puede cargar el archivo especificado, se utiliza el conjunto de reglas predeterminado wcag2.1.

Soporte

Crear conjuntos de reglas personalizados requiere un conocimiento significativo de axe-core. Para más detalles, consulte la documentación de la API de axe-core. Si desea soporte para crear y mantener su conjunto de reglas personalizado, comuníquese con su representante de Deque.