@double-great/stylelint-a11y 3.2.0 → 3.4.0

package/CHANGELOG.md

@@ -5,6 +5,56 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [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
+
+## [3.3.0] - 2025-08-17
+
+### Added
+
+- Advanced testing infrastructure with comprehensive CI/CD workflows
+- System-level performance regression testing suite
+- Cross-platform compatibility testing for Node.js environments
+- Integration tests for real-world stylelint plugin functionality
+- Enhanced rule configuration options with customizable parameters
+- Meta objects for all rules with documentation URLs and fixable status
+- Comprehensive rule documentation with examples and configuration options
+
+### Changed
+
+- Enhanced stylelint standards compliance with proper meta objects across all rules
+- Standardized rule message formatting for consistent error reporting
+- Improved Jest configuration with proper Node.js module support
+- Updated all rule implementations to follow modern stylelint plugin patterns
+- Enhanced rule functionality with configurable options for better customization
+- Improved error messages for better developer experience
+
+### Fixed
+
+- Removed deprecated experimental VM modules flag from Jest scripts for Node.js compatibility
+- Resolved CI performance test expectations for consistent build environments
+- Cleaned up test infrastructure and removed redundant configuration files
+- Fixed rule message clarity and consistency across all accessibility rules
+
 ## [3.2.0] - 2025-08-16
 
 ### Added

package/CONTRIBUTING.md

@@ -0,0 +1,164 @@
+# Contributing to stylelint-a11y
+
+Thank you for your interest in contributing to stylelint-a11y! This guide will help you get started with contributing to the project.
+
+## Getting Started
+
+1. Fork the repository
+2. Clone your fork locally
+3. Install dependencies with `npm install`
+4. Create a new branch for your feature or fix
+5. Make your changes
+6. Run tests with `npm test`
+7. Submit a pull request
+
+## Adding a New Rule
+
+When adding a new accessibility rule to this plugin, please follow this checklist:
+
+### Rule Implementation Checklist
+
+- [ ] **Create rule directory structure**
+  - [ ] Create new directory under `src/rules/[rule-name]/`
+  - [ ] Rule name should be kebab-case and descriptive
+
+- [ ] **Implement the rule** (`src/rules/[rule-name]/index.js`)
+  - [ ] Export a function that follows stylelint's rule API
+  - [ ] Include proper rule metadata (ruleName, messages)
+  - [ ] Implement the rule logic
+  - [ ] Use stylelint's built-in utilities where appropriate
+  - [ ] Handle edge cases and nested selectors
+
+- [ ] **Write comprehensive tests** (`src/rules/[rule-name]/__tests__/index.js`)
+  - [ ] Test valid cases (code that should pass)
+  - [ ] Test invalid cases (code that should fail)
+  - [ ] Test edge cases and complex selectors
+  - [ ] Test with SCSS syntax if applicable
+  - [ ] Test auto-fix functionality if the rule is fixable
+  - [ ] Ensure good test coverage
+
+- [ ] **Create rule documentation** (`src/rules/[rule-name]/README.md`)
+  - [ ] Provide clear description of what the rule does
+  - [ ] Explain why this accessibility rule is important
+  - [ ] Include links to WCAG guidelines or other authoritative sources
+  - [ ] Show examples of violations
+  - [ ] Show examples of valid code
+  - [ ] Document any options the rule accepts
+  - [ ] Note if the rule is auto-fixable
+
+- [ ] **Register the rule**
+  - [ ] Add the rule to `src/rules/index.js`
+  - [ ] Export it from the main rules index
+
+- [ ] **Update plugin configuration**
+  - [ ] Add the rule to `src/index.js` in the rules export
+  - [ ] Consider if it should be in `recommended.js` config
+
+- [ ] **Update main README**
+  - [ ] Add the rule to the rules table in `README.md`
+  - [ ] Include description and any badges (Recommended, Fixable)
+  - [ ] Keep alphabetical order
+
+- [ ] **Test the rule thoroughly**
+  - [ ] Run unit tests: `npm run test:unit`
+  - [ ] Run integration tests: `npm run test:integration`
+  - [ ] Run all tests: `npm test`
+  - [ ] Ensure no performance regressions: `npm run test:performance`
+
+- [ ] **Code quality checks**
+  - [ ] Run linting: `npm run lint`
+  - [ ] Check formatting: `npm run format:check`
+  - [ ] Fix formatting if needed: `npm run format:fix`
+
+- [ ] **Manual testing**
+  - [ ] Test the rule in a real project
+  - [ ] Verify error messages are clear and helpful
+  - [ ] Check that line numbers are accurate
+  - [ ] Test with different stylelint configurations
+
+### Example Rule Structure
+
+Here's what a typical rule implementation looks like:
+
+```javascript
+// src/rules/my-new-rule/index.js
+import stylelint from 'stylelint';
+
+const ruleName = 'a11y/my-new-rule';
+const messages = stylelint.utils.ruleMessages(ruleName, {
+  expected: 'Expected ...',
+});
+
+const meta = {
+  url: 'https://github.com/double-great/stylelint-a11y/tree/main/src/rules/my-new-rule',
+};
+
+const ruleFunction = (primaryOption, secondaryOptions) => {
+  return (root, result) => {
+    // Rule implementation
+  };
+};
+
+ruleFunction.ruleName = ruleName;
+ruleFunction.messages = messages;
+ruleFunction.meta = meta;
+
+export default ruleFunction;
+```
+
+## Code Style
+
+- Use ES6+ features
+- Follow the existing code style (enforced by ESLint and Prettier)
+- Write clear, self-documenting code
+- Add JSDoc comments for complex functions
+
+## Testing
+
+We maintain high test coverage. Please ensure your changes include appropriate tests:
+
+- Unit tests for individual rules
+- Integration tests for plugin functionality
+- E2E tests for real-world scenarios
+- Performance tests for efficiency
+
+Run the test suite with:
+
+```bash
+npm test           # Run all tests
+npm run test:unit  # Run unit tests only
+npm run coverage   # Run tests with coverage report
+```
+
+## Commit Messages
+
+- Use clear, descriptive commit messages
+- Follow conventional commit format when possible
+- Reference issue numbers when applicable
+
+## Pull Request Process
+
+1. Ensure all tests pass
+2. Update documentation as needed
+3. Add a description of your changes
+4. Link any related issues
+5. Wait for code review
+6. Address any feedback
+
+## Reporting Issues
+
+When reporting issues, please include:
+
+- Stylelint version
+- Plugin version
+- Node.js version
+- Minimal reproduction case
+- Expected vs actual behavior
+
+## Questions?
+
+Feel free to open an issue for any questions about contributing.
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.

package/README.md

@@ -1,5 +1,10 @@
 # @double-great/stylelint-a11y
 
+[![npm version](https://img.shields.io/npm/v/@double-great/stylelint-a11y.svg)](https://www.npmjs.com/package/@double-great/stylelint-a11y)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Stylelint plugin for CSS accessibility rules.
+
 ## Installation and usage
 
 This plugin requires Stylelint 16.0.0 or higher.
@@ -12,6 +17,44 @@ Create the `.stylelintrc.json` config file (or open the existing one), add `styl
 
 Please refer to [stylelint docs](https://stylelint.io/user-guide/) for the detailed info on using this linter.
 
+## Basic Configuration
+
+Here's a basic `.stylelintrc.json` configuration:
+
+```json
+{
+  "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:
+
+```json
+{
+  "extends": ["@double-great/stylelint-a11y/recommended"],
+  "rules": {
+    // Add any additional rules or overrides here
+  }
+}
+```
+
+For stricter accessibility checks:
+
+```json
+{
+  "extends": ["@double-great/stylelint-a11y/strict"],
+  "rules": {
+    // Override any rules if needed
+  }
+}
+```
+
 ## Rules
 
 | Rule ID                                                                                    | Description                                                             |                      |
@@ -29,7 +72,9 @@ Please refer to [stylelint docs](https://stylelint.io/user-guide/) for the detai
 | [no-text-align-justify](./src/rules/no-text-align-justify/README.md)                       | Disallow content with `text-align: justify`                             |                      |
 | [selector-pseudo-class-focus](./src/rules/selector-pseudo-class-focus/README.md)           | Require or disallow a pseudo-element to the selectors with `:hover`     | Recommended, Fixable |
 
-## Recommended config
+## Configurations
+
+### Recommended config
 
 Add recommended configuration by adding the following to `extends` in your stylelint configuration:
 
@@ -50,7 +95,119 @@ This shareable config contains the following:
 }
 ```
 
-Since it adds stylelint-a11y to `plugins`, you don't have to do this yourself when extending this config.
+### Strict config
+
+For a more comprehensive accessibility check, use the strict configuration:
+
+```
+@double-great/stylelint-a11y/strict
+```
+
+This config enables ALL accessibility rules:
+
+```json
+{
+  "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":
+
+```json
+{
+  "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:
+
+```json
+{
+  "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:
+
+```json
+{
+  "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:
+
+```css
+/* stylelint-disable a11y/no-outline-none */
+.button:focus {
+  outline: none;
+}
+/* stylelint-enable a11y/no-outline-none */
+```
+
+Or for a single line:
+
+```css
+.button:focus {
+  outline: none; /* stylelint-disable-line a11y/no-outline-none */
+}
+```
+
+## Contributing
+
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for detailed information on:
+
+- How to add new rules
+- Code style guidelines
+- Testing requirements
+- Pull request process
+
+For quick links:
+
+- [Issue reporting](https://github.com/double-great/stylelint-a11y/issues)
+- [Pull requests](https://github.com/double-great/stylelint-a11y/pulls)
+- [Changelog](https://github.com/double-great/stylelint-a11y/blob/main/CHANGELOG.md)
 
 ## Development
 
@@ -69,10 +226,10 @@ Run tests with the following commands:
 
 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
+- [Unit tests](./src/rules) - Individual rule functionality
+- [Integration tests](./test/integration) - Plugin integration with stylelint
+- [E2E tests](./test/e2e) - Real-world project testing with intentional violations
+- [Performance tests](./test/e2e/performance.test.js) - Benchmark testing for large codebases
 
 ### Other Commands
 
@@ -80,3 +237,7 @@ This project includes testing at a few levels:
 - `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](LICENSE).

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@double-great/stylelint-a11y",
-  "version": "3.2.0",
+  "version": "3.4.0",
   "description": "Plugin for stylelint with a11y rules",
   "main": "src/index.js",
   "type": "module",
   "exports": {
     ".": "./src/index.js",
-    "./recommended": "./recommended.js"
+    "./recommended": "./recommended.js",
+    "./strict": "./strict.js"
   },
   "repository": {
     "type": "git",
@@ -28,14 +29,18 @@
     "pretest": "npm run lint && npm run format:check",
     "format:check": "prettier --check .",
     "format:fix": "prettier --write .",
-    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
-    "test:unit": "node --experimental-vm-modules node_modules/jest/bin/jest.js src",
-    "test:integration": "node --experimental-vm-modules node_modules/jest/bin/jest.js test/integration",
-    "test:e2e": "node --experimental-vm-modules node_modules/jest/bin/jest.js test/e2e",
-    "test:performance": "node --experimental-vm-modules node_modules/jest/bin/jest.js test/e2e/performance.test.js",
-    "test:all": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
-    "coverage": "node --experimental-vm-modules node_modules/jest/bin/jest.js --coverage",
-    "coverage:all": "node --experimental-vm-modules node_modules/jest/bin/jest.js --coverage"
+    "test": "jest",
+    "test:unit": "jest src",
+    "test:integration": "jest test/integration",
+    "test:e2e": "jest test/e2e",
+    "test:performance": "jest test/e2e/performance.test.js",
+    "test:system": "jest test/system",
+    "test:regression": "jest test/system/performance-regression.test.js",
+    "test:compatibility": "jest test/system/compatibility.test.js",
+    "test:ci": "jest test/system/ci-integration.test.js",
+    "test:all": "jest",
+    "coverage": "jest --coverage",
+    "coverage:all": "jest --coverage"
   },
   "prettier": {
     "printWidth": 100,

package/recommended.js

@@ -1,7 +1,7 @@
 /** @type {import('stylelint').Config} */
 
 export default {
-  plugin: ['.'],
+  plugins: ['.'],
 
   rules: {
     'a11y/media-prefers-reduced-motion': true,

package/src/index.js

@@ -3,8 +3,42 @@ const { createPlugin } = stylelint;
 
 import rules from './rules/index.js';
 
+// Import meta objects
+import { meta as contentPropertyMeta } from './rules/content-property-no-static-value/index.js';
+import { meta as fontSizeReadableMeta } from './rules/font-size-is-readable/index.js';
+import { meta as lineHeightRhythmedMeta } from './rules/line-height-is-vertical-rhythmed/index.js';
+import { meta as mediaPrefersColorSchemeMeta } from './rules/media-prefers-color-scheme/index.js';
+import { meta as mediaPrefersReducedMotionMeta } from './rules/media-prefers-reduced-motion/index.js';
+import { meta as noDisplayNoneMeta } from './rules/no-display-none/index.js';
+import { meta as noObsoleteAttributeMeta } from './rules/no-obsolete-attribute/index.js';
+import { meta as noObsoleteElementMeta } from './rules/no-obsolete-element/index.js';
+import { meta as noOutlineNoneMeta } from './rules/no-outline-none/index.js';
+import { meta as noSpreadTextMeta } from './rules/no-spread-text/index.js';
+import { meta as noTextAlignJustifyMeta } from './rules/no-text-align-justify/index.js';
+import { meta as selectorPseudoClassFocusMeta } from './rules/selector-pseudo-class-focus/index.js';
+
+const ruleMetaMap = {
+  'content-property-no-static-value': contentPropertyMeta,
+  'font-size-is-readable': fontSizeReadableMeta,
+  'line-height-is-vertical-rhythmed': lineHeightRhythmedMeta,
+  'media-prefers-color-scheme': mediaPrefersColorSchemeMeta,
+  'media-prefers-reduced-motion': mediaPrefersReducedMotionMeta,
+  'no-display-none': noDisplayNoneMeta,
+  'no-obsolete-attribute': noObsoleteAttributeMeta,
+  'no-obsolete-element': noObsoleteElementMeta,
+  'no-outline-none': noOutlineNoneMeta,
+  'no-spread-text': noSpreadTextMeta,
+  'no-text-align-justify': noTextAlignJustifyMeta,
+  'selector-pseudo-class-focus': selectorPseudoClassFocusMeta,
+};
+
 const rulesPlugins = Object.keys(rules).map((ruleName) => {
-  return createPlugin(`a11y/${ruleName}`, rules[ruleName]);
+  const plugin = createPlugin(`a11y/${ruleName}`, rules[ruleName]);
+
+  // Add meta object to the plugin
+  plugin.meta = ruleMetaMap[ruleName];
+
+  return plugin;
 });
 
 export default rulesPlugins;

package/src/rules/content-property-no-static-value/README.md

@@ -11,6 +11,26 @@ Disallow CSS generated content except aria-label attribute content and empty str
 
 ### true
 
+The rule is enabled with default allowed values: `['""', "''", 'attr(aria-label)']`.
+
+### { allowedValues: string[] }
+
+- `allowedValues` (default: `['""', "''", 'attr(aria-label)']`): Array of allowed content values
+
+#### Example configuration
+
+```javascript
+{
+  "a11y/content-property-no-static-value": [true, {
+    "allowedValues": ["''", '""', "attr(title)", "counter(section)"]
+  }]
+}
+```
+
+### Examples
+
+#### ✓ Default configuration (`true`)
+
 The following pattern is considered a violation:
 
 ```css

package/src/rules/content-property-no-static-value/index.js

@@ -7,9 +7,15 @@ const {
 export const ruleName = 'a11y/content-property-no-static-value';
 
 export const messages = ruleMessages(ruleName, {
-  expected: (selector) => `Unexpected using "content" property in ${selector}`,
+  expected: (selector) => `Expected "content" property to not be used in ${selector}`,
 });
 
+export const meta = {
+  url: 'https://github.com/double-great/stylelint-a11y/blob/main/src/rules/content-property-no-static-value/README.md',
+  fixable: false,
+  deprecated: false,
+};
+
 const isContentPropertyUsedCorrectly = (selectors) =>
   selectors.every((selector) => {
     return /:before|:after/.test(selector);
@@ -18,24 +24,24 @@ const isContentPropertyUsedCorrectly = (selectors) =>
 const checkNodesForContentProperty = (node) =>
   node.nodes.filter((n) => n.prop).some((n) => n.prop.toLowerCase() === 'content');
 
-function check(node) {
+function check(node, options = {}) {
   if (node.type !== 'rule' || !checkNodesForContentProperty(node) || !node.first) {
     return true;
   }
 
+  const allowedValues = options.allowedValues || ["''", '""', 'attr(aria-label)'];
+
   return node.nodes.some((o) => {
     return (
       o.type === 'decl' &&
       o.prop.toLowerCase() === 'content' &&
       isContentPropertyUsedCorrectly(o.parent.selectors) &&
-      (o.value.toLowerCase() === "''" ||
-        o.value.toLowerCase() === '""' ||
-        o.value.toLowerCase() === 'attr(aria-label)')
+      allowedValues.some((allowed) => o.value.toLowerCase() === allowed.toLowerCase())
     );
   });
 }
 
-export default function contentPropertyNoStaticValue(actual) {
+export default function contentPropertyNoStaticValue(actual, options) {
   return (root, result) => {
     const validOptions = validateOptions(result, ruleName, { actual });
 
@@ -60,7 +66,7 @@ export default function contentPropertyNoStaticValue(actual) {
         return;
       }
 
-      const isAccepted = check(node);
+      const isAccepted = check(node, options);
 
       if (!isAccepted) {
         report({

package/src/rules/font-size-is-readable/index.js

@@ -10,6 +10,12 @@ export const messages = ruleMessages(ruleName, {
   expected: (selector) => `Expected a larger font-size in ${selector}`,
 });
 
+export const meta = {
+  url: 'https://github.com/double-great/stylelint-a11y/blob/main/src/rules/font-size-is-readable/README.md',
+  fixable: false,
+  deprecated: false,
+};
+
 const pxToPt = (v) => 0.75 * v;
 
 const checkInPx = (value, THRESHOLD_IN_PX) =>

package/src/rules/line-height-is-vertical-rhythmed/README.md

@@ -10,6 +10,25 @@ Disallow not vertical rhythmed line-height.
 
 ### true
 
+The rule is enabled with default values (24px baseline grid, 1.5 minimum relative line-height).
+
+### { baselineGrid: number, minRelativeLineHeight: number }
+
+- `baselineGrid` (default: `24`): Baseline grid value in pixels for pixel-based line-heights
+- `minRelativeLineHeight` (default: `1.5`): Minimum allowed relative line-height value
+
+#### Example configuration
+
+```javascript
+{
+  "a11y/line-height-is-vertical-rhythmed": [true, { "baselineGrid": 20, "minRelativeLineHeight": 1.3 }]
+}
+```
+
+### Examples
+
+#### ✓ Default configuration (`true`)
+
 The following pattern is considered a violation:
 
 ```css