如何为pa11y-ci添加规则？WCAG规则配置报错排查

I ran into this exact issue when mixing WCAG 2A and 2AA rules in pa11y-ci, so I know how frustrating it can be. Here's what's going wrong and how to fix it:

Why You're Seeing the Error #

The full rule path you used (WCAG2AA.Principle1.Guideline1_1.1_1_1.H30.2) isn't the format pa11y-ci expects for rule identifiers. While that full hierarchy exists in HTML CodeSniffer's internal structure, pa11y uses simplified, shorthand rule names (like WCAG2AA.H30.2) that skip the principle/guideline/sub-guideline prefixes. That's why the tool is throwing an invalid rule error.

Correct Configuration Approach #

To combine WCAG 2A as your base standard plus specific WCAG 2AA rules, use the standard field for your base ruleset and the include array to add your extra AA rules. Here's a working example .pa11yci config:

{
  "urls": [
    "https://your-target-url.com"
  ],
  "standard": "WCAG2A",
  "include": [
    "WCAG2AA.H30.2",
    // Add other WCAG 2AA rules you want here, e.g.:
    "WCAG2AA.H37",
    "WCAG2AA.G18"
  ],
  "exclude": [] // Optional: Add rules you want to omit from the base standard
}

Verify Valid Rule Names #

If you're unsure about a rule's correct shorthand name, run this command in your terminal to list all rules supported by your pa11y-ci version:

pa11y --list-rules

This will output every valid rule identifier you can use in your config, so you can cross-check the names you want to add.

Alternative: Explicitly List All Rules #

If you prefer to define every rule explicitly (instead of using a base standard), you can list both WCAG 2A and your chosen 2AA rules in the rules array:

{
  "urls": [
    "https://your-target-url.com"
  ],
  "rules": [
    // WCAG 2A rules (example subset)
    "WCAG2A.H25",
    "WCAG2A.G94",
    // WCAG 2AA rules you want to add
    "WCAG2AA.H30.2",
    "WCAG2AA.H37"
  ]
}

Just note that this approach requires you to list every rule you want to enforce, which can be more maintenance-heavy than using the standard + include method.

内容的提问来源于stack exchange，提问作者jBoive