@double-great/stylelint-a11y

Stylelint plugin for CSS accessibility rules.

Installation and usage

This plugin requires Stylelint 16.0.0 or higher.

npm i --save-dev stylelint @double-great/stylelint-a11y

Create the .stylelintrc.json config file (or open the existing one), add stylelint-a11y to the plugins array and the rules you need to the rules list. All rules from stylelint-a11y need to be namespaced with a11y.

Please refer to stylelint docs for the detailed info on using this linter.

Basic Configuration

Here's a basic .stylelintrc.json configuration:

{
  "plugins": ["@double-great/stylelint-a11y"],
  "rules": {
    "a11y/no-outline-none": true,
    "a11y/font-size-is-readable": true,
    "a11y/media-prefers-reduced-motion": true,
    "a11y/selector-pseudo-class-focus": true
  }
}

Or extend one of the provided configs:

{
  "extends": ["@double-great/stylelint-a11y/recommended"],
  "rules": {
    // Add any additional rules or overrides here
  }
}

For stricter accessibility checks:

{
  "extends": ["@double-great/stylelint-a11y/strict"],
  "rules": {
    // Override any rules if needed
  }
}

Rules

| Rule ID | Description | | | :----------------------------------------------------------------------------------------- | :---------------------------------------------------------------------- | -------------------- | | content-property-no-static-value | Disallow unaccessible CSS generated content in pseudo-elements | | | font-size-is-readable | Disallow font sizes less than 15px | | | line-height-is-vertical-rhythmed | Disallow not vertical rhythmed line-height | | | media-prefers-reduced-motion | Require certain styles if the animation or transition in media features | Recommended, Fixable | | media-prefers-color-scheme | Require implementation of certain styles for selectors with colors. | | | no-display-none | Disallow content hiding with display: none property | | | no-obsolete-attribute | Disallow obsolete attribute using | | | no-obsolete-element | Disallow obsolete selectors using | | | no-spread-text | Require width of text in a comfortable range | | | no-outline-none | Disallow outline clearing | Recommended | | no-text-align-justify | Disallow content with text-align: justify | | | selector-pseudo-class-focus | Require or disallow a pseudo-element to the selectors with :hover | Recommended, Fixable |

Configurations

Recommended config

Add recommended configuration by adding the following to extends in your stylelint configuration:

@double-great/stylelint-a11y/recommended

This shareable config contains the following:

{
  "plugins": ["@double-great/stylelint-a11y"],
  "rules": {
    "a11y/media-prefers-reduced-motion": true,
    "a11y/no-outline-none": true,
    "a11y/selector-pseudo-class-focus": true
  }
}

Strict config

For a more comprehensive accessibility check, use the strict configuration:

@double-great/stylelint-a11y/strict

This config enables ALL accessibility rules:

{
  "plugins": ["@double-great/stylelint-a11y"],
  "rules": {
    "a11y/content-property-no-static-value": true,
    "a11y/font-size-is-readable": true,
    "a11y/line-height-is-vertical-rhythmed": true,
    "a11y/media-prefers-color-scheme": true,
    "a11y/media-prefers-reduced-motion": true,
    "a11y/no-display-none": true,
    "a11y/no-obsolete-attribute": true,
    "a11y/no-obsolete-element": true,
    "a11y/no-outline-none": true,
    "a11y/no-spread-text": true,
    "a11y/no-text-align-justify": true,
    "a11y/selector-pseudo-class-focus": true
  }
}

Since both configs add stylelint-a11y to plugins, you don't have to do this yourself when extending these configs.

Rule Configuration

Severity Levels

Stylelint supports configuring rules with different severity levels. You can set rules to either "error" or "warning":

{
  "rules": {
    "a11y/no-outline-none": "error",
    "a11y/font-size-is-readable": "warning",
    "a11y/media-prefers-reduced-motion": ["warning", { "ignore": ["animation"] }]
  }
}

You can also use array syntax with severity as the first element:

{
  "rules": {
    "a11y/no-outline-none": ["error"],
    "a11y/font-size-is-readable": ["warning", { "thresholdInPixels": 14 }],
    "a11y/selector-pseudo-class-focus": ["error", "always"]
  }
}

• "error" - The rule will report an error (exit code 2 when running stylelint)
• "warning" - The rule will report a warning (exit code 0 unless there are errors)

Rule Options

Many rules support additional configuration options for customization. For example:

{
  "rules": {
    "a11y/font-size-is-readable": [true, { "thresholdInPixels": 16 }],
    "a11y/no-spread-text": [true, { "minWidth": 30, "maxWidth": 60 }],
    "a11y/line-height-is-vertical-rhythmed": [true, { "baselineGrid": 20 }]
  }
}

Refer to individual rule documentation for available options.

Disabling Rules

You can disable rules inline using stylelint's comment syntax:

/* stylelint-disable a11y/no-outline-none */
.button:focus {
  outline: none;
}
/* stylelint-enable a11y/no-outline-none */

Or for a single line:

.button:focus {
  outline: none; /* stylelint-disable-line a11y/no-outline-none */
}

Contributing

We welcome contributions! Please see our Contributing Guide for detailed information on:

• How to add new rules
• Code style guidelines
• Testing requirements
• Pull request process

For quick links:

• Issue reporting
• Pull requests
• Changelog

Development

Testing

Run tests with the following commands:

• npm run test - Run unit tests for all rules
• npm run test:unit - Run unit tests only
• npm run test:integration - Run integration tests
• npm run test:e2e - Run end-to-end tests with real projects
• npm run test:performance - Run performance benchmarks
• npm run test:all - Run complete test suite

Testing Infrastructure

This project includes testing at a few levels:

• Unit tests - Individual rule functionality
• Integration tests - Plugin integration with stylelint
• E2E tests - Real-world project testing with intentional violations
• Performance tests - Benchmark testing for large codebases

Other Commands

• npm run lint - Run ESLint
• npm run format:check - Check code formatting
• npm run format:fix - Fix code formatting
• npm run coverage - Run tests with coverage report

License

This project is licensed under the MIT License.