@double-great/stylelint-a11y

@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.

Changelog

[3.4.0] - 2025-08-17

Added

• Strict configuration (@double-great/stylelint-a11y/strict) that enables all accessibility rules
• CONTRIBUTING.md with comprehensive guide for adding new rules
• Severity levels documentation showing how to configure rules as errors or warnings
• Basic configuration examples in README
• Inline rule disabling documentation
• Badges for npm version and MIT license
• Links to test directories in Testing Infrastructure section
• Test coverage for strict configuration

Changed

• Enhanced README with better organization and more comprehensive documentation
• Updated Testing Infrastructure section with links instead of bold text

Fixed

• Corrected plugin to plugins in recommended.js configuration