@benhigham/stylelint-config 0.1.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Benjamin Higham
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,83 @@
+# @benhigham/stylelint-config
+
+[![npm version](https://img.shields.io/npm/v/@benhigham/stylelint-config.svg)](https://www.npmjs.com/package/@benhigham/stylelint-config)
+[![npm downloads](https://img.shields.io/npm/dm/@benhigham/stylelint-config.svg)](https://www.npmjs.com/package/@benhigham/stylelint-config)
+[![License](https://img.shields.io/github/license/benhigham/stylelint-config)](LICENSE.md)
+
+My personal [Stylelint](https://stylelint.io/) configuration for maintaining consistent, high-quality CSS/SCSS code.
+
+## Features
+
+This configuration:
+
+- Extends [`stylelint-config-standard-scss`](https://github.com/stylelint-scss/stylelint-config-standard-scss) for SCSS support and best practices
+- Uses [`stylelint-config-recess-order`](https://github.com/stormwarning/stylelint-config-recess-order) for consistent property ordering
+- Enforces strict value usage for colors, font-sizes, and z-indices
+- Prevents performance issues with animations
+- Requires proper use of custom media queries and nesting
+- Enforces BEM naming conventions with SUIT CSS methodology
+- Ensures browser compatibility with [Baseline](https://web.dev/baseline) requirements
+- Includes accessibility checks for better a11y compliance
+- Detects and prevents indistinguishable colors and out-of-gamut colors
+- Provides special handling for CSS modules
+
+## Installation
+
+```bash
+# npm
+npm install --save-dev @benhigham/stylelint-config
+
+# yarn
+yarn add --dev @benhigham/stylelint-config
+
+# pnpm
+pnpm add --save-dev @benhigham/stylelint-config
+```
+
+## Usage
+
+Create a `stylelint.config.js` file in your project root and extend this configuration:
+
+```javascript
+/** @type {import('stylelint').Config} */
+export default {
+  extends: ['@benhigham/stylelint-config'],
+};
+```
+
+## Configuration Details
+
+### Extended Configs
+
+- [`stylelint-config-standard-scss`](https://github.com/stylelint-scss/stylelint-config-standard-scss): Provides standard rules for SCSS files
+- [`stylelint-config-recess-order`](https://github.com/stormwarning/stylelint-config-recess-order): Enforces a consistent property ordering based on the Recess methodology
+
+### Plugins
+
+This configuration includes several plugins:
+
+- [`stylelint-declaration-block-no-ignored-properties`](https://github.com/kristerkari/stylelint-declaration-block-no-ignored-properties): Prevents using ignored or overridden properties
+- [`stylelint-declaration-strict-value`](https://github.com/AndyOGo/stylelint-declaration-strict-value): Enforces the use of variables, functions or custom CSS for specific properties
+- [`stylelint-high-performance-animation`](https://github.com/kristerkari/stylelint-high-performance-animation): Prevents using low-performance animation properties
+- [`stylelint-media-use-custom-media`](https://github.com/csstools/stylelint-media-use-custom-media): Enforces the use of custom media queries
+- [`stylelint-use-nesting`](https://github.com/csstools/stylelint-use-nesting): Enforces proper CSS nesting
+- [`stylelint-plugin-require-baseline`](https://github.com/ryo-manba/stylelint-plugin-require-baseline): Disallow CSS features not in [Baseline](https://web.dev/baseline)
+- [`stylelint-no-unresolved-module`](https://github.com/niksy/stylelint-no-unresolved-module): Ensures all imported modules can be resolved
+- [`stylelint-no-indistinguishable-colors`](https://github.com/ierhyna/stylelint-no-indistinguishable-colors): Prevents colors that are too similar
+- [`stylelint-gamut`](https://github.com/csstools/stylelint-gamut): Prevents colors outside of supported gamut range
+- [`stylelint-selector-bem-pattern`](https://github.com/simonsmith/stylelint-selector-bem-pattern): Enforces BEM naming convention
+- [`stylelint-no-browser-hacks`](https://github.com/stylelint/stylelint-no-browser-hacks): Disallows browser hacks
+- [`stylelint-no-unsupported-browser-features`](https://github.com/ismay/stylelint-no-unsupported-browser-features): Warns about unsupported browser features
+- [`stylelint-a11y`](https://github.com/YozhikM/stylelint-a11y): Ensures CSS is accessible
+
+### Key Rules
+
+- **Browser Compatibility**: Enforces only widely supported CSS features
+- **SCSS Best Practices**: Limits nesting depth, enforces consistent naming patterns
+- **BEM Pattern**: Uses SUIT CSS methodology for class naming
+- **Accessibility**: Ensures focus styles, supports reduced motion, and more
+- **CSS Modules**: Special handling for `.module.scss` files with relaxed naming rules
+
+## License
+
+This project is licensed under the [MIT License](LICENSE.md).

package/package.json

@@ -0,0 +1,91 @@
+{
+  "name": "@benhigham/stylelint-config",
+  "version": "0.1.0",
+  "description": "My personal Stylelint configuration.",
+  "license": "MIT",
+  "homepage": "https://github.com/benhigham/stylelint-config#readme",
+  "bugs": {
+    "url": "https://github.com/benhigham/stylelint-config/issues/new"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/benhigham/stylelint-config.git"
+  },
+  "funding": "https://github.com/sponsors/benhigham",
+  "author": {
+    "name": "Ben Higham",
+    "url": "https://benhigham.com"
+  },
+  "type": "module",
+  "module": "./src/index.js",
+  "exports": "./src/index.js",
+  "sideEffects": false,
+  "engines": {
+    "node": "^18.20.0 || ^20.10.0 || >=21.0.0"
+  },
+  "files": [
+    "src"
+  ],
+  "keywords": [
+    "stylelint",
+    "stylelint-config",
+    "check",
+    "checker",
+    "code",
+    "codeguide",
+    "config",
+    "css",
+    "csslint",
+    "enforce",
+    "formatting",
+    "lint",
+    "linter",
+    "quality",
+    "standard",
+    "strict",
+    "style",
+    "styleguide",
+    "stylistic",
+    "validate",
+    "verify"
+  ],
+  "dependencies": {
+    "stylelint-a11y": "^1.2.3",
+    "stylelint-config-recess-order": "^6.0.0",
+    "stylelint-config-standard-scss": "^14.0.0",
+    "stylelint-declaration-block-no-ignored-properties": "^2.8.0",
+    "stylelint-declaration-strict-value": "^1.10.11",
+    "stylelint-gamut": "^1.3.4",
+    "stylelint-high-performance-animation": "^1.11.0",
+    "stylelint-media-use-custom-media": "^4.0.0",
+    "stylelint-no-browser-hacks": "^1.3.0",
+    "stylelint-no-indistinguishable-colors": "^2.3.1",
+    "stylelint-no-unresolved-module": "^2.3.0",
+    "stylelint-no-unsupported-browser-features": "^8.0.4",
+    "stylelint-plugin-require-baseline": "^0.1.1",
+    "stylelint-selector-bem-pattern": "^4.0.1",
+    "stylelint-use-nesting": "^6.0.0"
+  },
+  "devDependencies": {
+    "@benhigham/commitlint-config": "^0.1.2",
+    "@benhigham/prettier-config": "^0.1.0",
+    "@changesets/changelog-github": "^0.5.1",
+    "@changesets/cli": "^2.28.1",
+    "@commitlint/cli": "^19.8.0",
+    "lefthook": "^1.11.9",
+    "prettier": "^3.5.3",
+    "stylelint": "^16.18.0",
+    "stylelint-find-new-rules": "^5.0.0"
+  },
+  "peerDependencies": {
+    "stylelint": ">=16.0.0"
+  },
+  "scripts": {
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "changeset": "changeset",
+    "changeset:status": "changeset status",
+    "version": "changeset version",
+    "release": "changeset publish"
+  }
+}

package/src/index.js

@@ -0,0 +1,97 @@
+/** @import { Config } from 'stylelint' */
+
+/** @type {Config} */
+const config = {
+  extends: ['stylelint-config-standard-scss', 'stylelint-config-recess-order'],
+  plugins: [
+    'stylelint-declaration-block-no-ignored-properties',
+    'stylelint-declaration-strict-value',
+    'stylelint-no-unresolved-module',
+    'stylelint-high-performance-animation',
+    'stylelint-no-indistinguishable-colors',
+    'stylelint-gamut',
+    'stylelint-selector-bem-pattern',
+    'stylelint-media-use-custom-media',
+    'stylelint-use-nesting',
+    'stylelint-plugin-require-baseline',
+    'stylelint-no-browser-hacks',
+    'stylelint-no-unsupported-browser-features',
+    'stylelint-a11y',
+  ],
+  rules: {
+    // Browser compatibility
+    'plugin/require-baseline': [true, { available: 'widely' }],
+    'plugin/no-browser-hacks': true,
+    'plugin/no-unsupported-browser-features': true,
+
+    // SCSS-specific rules
+    'scss/at-rule-no-unknown': true,
+    'scss/selector-no-redundant-nesting-selector': true,
+    'scss/dollar-variable-pattern': '^[a-z][a-zA-Z0-9]+$',
+    'scss/at-extend-no-missing-placeholder': true,
+    'scss/at-import-partial-extension': 'never',
+    'scss/at-mixin-pattern': '^[a-z][a-zA-Z0-9]+$',
+    'scss/max-nesting-depth': 3,
+
+    // Selector and class naming
+    'plugin/selector-bem-pattern': { preset: 'suit' },
+    'selector-max-id': 0,
+    'selector-max-specificity': '0,3,2',
+
+    // General consistency
+    'color-named': 'never',
+    'scale-unlimited/declaration-strict-value': [
+      ['/color$/', 'font-size', 'z-index'],
+      { ignoreValues: ['currentColor', 'inherit', 'transparent'] },
+    ],
+    'declaration-property-unit-allowed-list': {
+      'font-size': ['rem', '%'],
+      '/^margin|^padding/': ['rem', '%', 'vw', 'vh'],
+      '/^border|^outline/': ['px'],
+      'line-height': ['none', ''],
+    },
+    'unit-allowed-list': [
+      ['%', 'deg', 'rem', 'ms', 's', 'vw', 'vh'],
+      {
+        ignoreProperties: { px: ['border', 'outline'] },
+      },
+    ],
+    'length-zero-no-unit': true,
+    'shorthand-property-no-redundant-values': true,
+    'plugin/declaration-block-no-ignored-properties': true,
+    'csstools/media-use-custom-media': 'always',
+    'csstools/use-nesting': ['always', { syntax: 'scss' }],
+    'plugin/stylelint-no-indistinguishable-colors': true,
+    'gamut/color-no-out-gamut-range': true,
+    'plugin/no-low-performance-animation-properties': true,
+    'plugin/no-unresolved-module': { modules: ['node_modules'] },
+
+    // Accessibility
+    'a11y/media-prefers-reduced-motion': true,
+    'a11y/no-outline-none': true,
+    'a11y/selector-pseudo-class-focus': true,
+    'a11y/no-obsolete-attribute': true,
+    'a11y/no-obsolete-element': true,
+  },
+  overrides: [
+    {
+      files: ['**/*.module.{css,scss}'],
+      rules: {
+        // More permissive rules for CSS modules
+        'selector-class-pattern': null,
+        'plugin/selector-bem-pattern': {
+          preset: 'suit',
+          presetOptions: {
+            namespace: false,
+          },
+        },
+      },
+    },
+  ],
+  reportDescriptionlessDisables: true,
+  reportInvalidScopeDisables: true,
+  reportNeedlessDisables: true,
+  reportUnscopedDisables: true,
+};
+
+export default config;