@double-great/stylelint-a11y

Stylelint plugin for CSS accessibility rules.

Installation and usage

This plugin requires Stylelint 16.7.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 | Config, fixable | | :----------------------------------------------------------------------------------------- | :------------------------------------------------------------------------- | :------------------- | | content-property-no-static-value | Disallow static text in the content property | | | font-size-is-readable | Disallow font sizes smaller than 15px | | | line-height-is-vertical-rhythmed | Require line heights that fit a baseline grid | | | media-prefers-color-scheme | Require a prefers-color-scheme override for colors | | | media-prefers-reduced-motion | Require a prefers-reduced-motion override for transitions and animations | Recommended, Fixable | | no-display-none | Disallow hiding content with display: none | | | no-obsolete-attribute | Disallow selectors that target obsolete HTML attributes | | | no-obsolete-element | Disallow selectors that target obsolete HTML elements | | | no-outline-none | Disallow removing the focus outline without an alternative | Recommended | | no-spread-text | Require text max-width between 45ch and 80ch | | | no-text-align-justify | Disallow text-align: justify | | | selector-pseudo-class-focus | Require a :focus or :focus-visible companion for :hover selectors | 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

Every rule reports an error by default. To report a warning instead, set severity in the rule's secondary options object:

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

Rule options and severity share the same object:

{
  "rules": {
    "a11y/font-size-is-readable": [true, { "thresholdInPixels": 14, "severity": "warning" }]
  }
}

To report every rule as a warning, set defaultSeverity at the top level of the configuration:

{
  "defaultSeverity": "warning",
  "extends": ["@double-great/stylelint-a11y/recommended"]
}

• "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. Unknown option names and values of the wrong type are reported as configuration errors.

Related Core Rules

Some accessibility checks are already covered by stylelint's built-in rules. For example, to require relative units for font sizes, use declaration-property-unit-disallowed-list:

{
  "rules": {
    "declaration-property-unit-disallowed-list": { "font-size": ["px", "pt"] }
  }
}

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:system - Run the stylelint compatibility tests
• 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
• System tests - Compatibility with the supported stylelint versions

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.