Axe DevTools linter configuration

Configuring a linter is a bit like explaining house rules to a new roommate: if you aren't clear from the start, you’ll end up fighting over dirty dishes—or in our case, over false positives cluttering your terminal.

If you use axe Linter, the secret to success lies in a small file called axe-linter.yml. Let’s see how to master it.

1. Where do I put it? (Spoiler: The Root)

The configuration file must live in the root directory of your project. Don't hide it in obscure folders; axe expects to find it there, ready to be read every time you save. Create a text file and name it exactly: axe-linter.yml

2. Basic Anatomy

The YAML structure for axe is clean and minimal. It stands on two main pillars: rules (what to check) and exclude (what to ignore).

YAML

rules:
  # Here we define the rules of the game
exclude:
  # Here we tell axe to look the other way

3. Configuring Rules: A Matter of Priority

Not every project needs every default rule active. Maybe you’re working on a quick prototype or a legacy component where color contrast is a lost cause (for now). You can enable or disable rules by specifying the Rule ID and the enabled flag.

Practical Example:

YAML

rules:
  color-contrast:
    enabled: true   # We absolutely want standard-compliant contrast
  image-alt:
    enabled: false  # Disabled (maybe we're using temporary placeholders)
  region:
    enabled: true   # Ensure content is wrapped in ARIA regions

Pro Tip: Don’t disable rules just to make errors disappear! Use this feature only when a specific rule conflicts with external libraries you cannot control.

4. Excluding Elements: "Don’t Look Here"

There are parts of your code axe shouldn't analyze, such as external ad banners or complex SVG-generating chart libraries. In the exclude section, you can use CSS selectors (IDs, classes, tags) to define "safe zones" that will be ignored.

YAML

exclude:
  - "#third-party-widget"   # Excludes a specific element by ID
  - ".legacy-container"     # Ignores everything with this class
  - "svg"                   # If you really want to ignore all SVGs

5. Raising the Bar: Advanced Configuration

If you really want to get serious, you can go further. Axe allows you to define compliance levels (tags). For example, you might want to target strictly WCAG 2.1 Level AA.

Full Configuration Example:

YAML

# Global settings
global-library: axe-core

# WCAG Specifications and Best Practices
tags:
  - wcag2a
  - wcag21aa
  - best-practice

rules:
  color-contrast:
    enabled: true
  html-has-lang:
    enabled: true

exclude:
  - "#banner-ads"
  - ".ignore-accessibility-check"

Tips to Stay Sane

• Iterate slowly: Don’t try to activate 200 rules on day one. Start with the basics (alt text, contrast, form labels) and add complexity as you clean up the code.

• Sync with the Team: The axe-linter.yml file should be committed to Git. This ensures the entire team follows the same accessibility standards.

• Consult the "Sacred Text": If a rule seems obscure, look up the ID directly in the official Deque documentation. Every error has a detailed explanation of why it exists and how to fix it.

Conclusion

Creating an axe-linter.yml file is the first step toward turning accessibility from a "boring chore" into an automated process. It allows you to maintain consistent, clean, and—above all—inclusive code without fighting irrelevant warnings.