カスタムルールセット

axe rulesetコマンドは、どのアクセシビリティルールがaxeで実行され、それらがどのように動作するかを制御するJSONルールセットファイルを生成します。ワークフローは2つあります。

• 標準ガイドライン構成：特定のアクセシビリティ標準（WCAG 2.2、Section 508など）にフィルターされたプリビルド構成を生成します。
• カスタムルールセット：既存のaxe-coreルールを変更または拡張するか、新しいルールを定義するためにchanges.json入力ファイルに変更内容を記述します。必要なファイル名changes.jsonは、axe rulesetが変更を見つける方法です。

両方のワークフローは出力JSONファイルを生成します。スキャン時に適用するには、スキャンコマンドの--customフラグにパスします：

# 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

標準ガイドライン構成

これらのフラグは、特定のアクセシビリティ標準に事前設定されたJSONファイルを生成します。オプションの[filename]引数は出力ファイル名を設定します。省略した場合、ファイル名は<standard>.jsonになります（例：wcag22.json）。ファイルは、-d, --destinationで指定しない限り、現在のディレクトリに書き込まれます。

これらのフラグのいずれも使用せずにaxe rulesetを実行すると、サポートされているすべての標準の個別設定ファイルが一度に生成されます。

--all [filename]

すべてのaxe-coreルールとチェックを含む単一のJSONファイルを生成し、各ルールはenabled: falseに設定されています。これをオプトイン構成を開始する際の出発点として使用します。すべてのルールはデフォルトで無効になっており、ファイルを変更することで選択したルールのみを有効にします。

標準構成オプション

-d, --destination <path>

生成されたJSONファイルの出力ディレクトリ。デフォルトは現在のディレクトリです。

-f, --format [format]

出力フォーマット：json（デフォルト）またはjs。

-l, --log

生成されたファイルに含まれるすべてのルールのリストをコンソールに表示します。

-a, --axe-source <path>

カスタムaxe-coreソースファイルへのパス。特定または修正されたバージョンのaxe-coreに対して構成を生成する必要がある場合に使用します。

カスタムルールセット

カスタムルールセットを使用すると、既存のaxe-coreルールの動作を変更したり、まったく新しいルールを定義できます。変更はchanges.jsonファイルに記述され、このファイルはaxe.configure()に渡されるオブジェクトと同じ形式を使用します。

カスタムルールセットでできることには、次のようなものがあります：

• チェック結果の影響レベルを変更する（例：seriousをminorに格下げする）
• コンテキストに適さないルールを無効にする
• 組織のアクセシビリティポリシーを強制するための新しいルールを作成する
• ある要求に対して許可される技術を制限する（例：titleを画像のアクセシブルな名前として許可しない）
• color-contrastルールのコントラストしきい値を変更する
• サポートされるARIAロールおよびプロパティを更新する

カスタムルールセットの生成

カスタムルールセットを生成するには、変更を記述したchanges.jsonファイルを作成し、axe ruleset --custom <directory>を実行します。ここで<directory>はchanges.jsonが含まれるフォルダーです。--customを省略した場合、現在のディレクトリが使用されます。

changes.jsonファイルは、既存のaxe-coreルールおよびチェックに対する変更や新しいルールやチェックを指定できます。

影響はルールではなくチェックのプロパティですことに注意してください。生成されたaxe-ruleset.json出力には各ルールにimpactフィールドが表示されますが、これはルールの基になるチェックから計算された解決済みの値であり、changes.jsonでルールに設定するものではありません。入力ファイル内で直接ルールにimpactを設定するとエラーが発生します。

ルールの発見の重要度を変えるには、基になるチェックの影響を変更します。たとえば、valid-langチェックをseriousからminorに変更するには次のようにします：

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

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

これをchanges.jsonとしてディレクトリに保存し、以下を実行します：

axe ruleset --custom ./my-changes/

ルールとチェックのディレクトリ使用

より複雑なカスタマイズのために、新しいルールとチェックをrules/およびchecks/ディレクトリにchanges.jsonと共に整理することができます。各ルールまたはチェックはそれ自体で1つのJSONファイルです。これにより生成された出力が変わるわけではありませんが、複数のカスタムルールとチェックを管理しやすくなります。

たとえば、一つのページに複数の<h1>があるかどうかを確認するh1-no-duplicateという新しいルールを作成するには：

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

ルールとチェックが別々のファイルで定義されているため、changes.jsonは空のオブジェクトです：

{}

h1-no-duplicate.jsonルールファイルは実行するチェックを定義します：

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

page-no-duplicate-h1.jsonチェックファイルはチェックとその結果メッセージを定義します：

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

evaluateおよびafterフィールドは、チェックロジックを実装するJavaScript関数IDを参照します。既存axe-coreチェックを修正するチェックの場合は、既存のaxe-core評価または後処理関数のIDを使用します。完全に新しいチェックの場合は、対応するJavaScript関数をaxe-coreに登録する必要もあります。詳細はaxe-core APIドキュメントをご覧ください。

axe ruleset --customを実行した後、生成されたJSONはルールとチェックの定義を単一のファイルに結合します（関連部分を表示）：

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

カスタムルールセットオプション

-c, --custom [path]

changes.jsonファイルを含むディレクトリへのパス（およびオプションのrules/およびchecks/サブディレクトリ）。デフォルトは現在のディレクトリです。

-t, --tags <list>

標準のaxe-coreルールセットから出力に含めるルールをフィルターするために使用するaxe-coreタグのカンマ区切りリスト。

-x, --disable-other-rules

Disables all axe-core rules not explicitly included in the rules property of changes.json or the rules/ directory. Enabled by default, so the generated ruleset replaces the full axe-core ruleset rather than extending it; only your custom rules run. Pass --no-disable-other-rules to include all standard axe-core rules alongside your custom ones.

--only-changes

--customと一緒にのみ有効です。changes.jsonで説明されている変更と追加のみを生成し、完全なaxe-coreルールとチェックの定義は含めません。既存のルールセットの上にオーバーレイとして使用するのに適した小さいファイルを生成します。

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

標準の設定オプションを参照してください。これらのオプションはカスタムルールセットにも適用されます。

ルールセットを読み込む

スキャン時に生成されたルールセットを適用する方法は3つあります。次の順序でチェックされます：

1. 環境変数：ルールセットファイルのパスをAXE_RULESET_PATHに設定します。これは他のすべての方法よりも優先され、その環境内のすべての実行に適用されます。

2. --customフラグ：--customフラグを使用して、axe <url>、axe spec、またはaxe bulk-specでルールセットファイルを明示的に渡します。

3. ローカルファイル：ファイル名がaxe-ruleset.jsonであるファイルをaxeが実行されるディレクトリに置きます。上記のどちらも設定されていない場合、自動的に使用されます。

これらのいずれも指定されていない場合、またはAxe DevToolsが指定されたファイルをロードできない場合は、wcag2.1デフォルトルールセットが使用されます。

サポート

カスタムルールセットを作成するには、axe-coreに関する十分な理解が必要です。詳細はaxe-core APIドキュメントをご覧ください。カスタムルールセットの作成と維持に関するサポートが必要な場合は、Dequeの担当者に連絡してください。