Stylelint plugin for CSS accessibility rules.

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.

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

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

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.

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)

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.

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 */ }

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

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

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

• 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

This project is licensed under the MIT License.