Merge pull request #1120 from nhsuk/stylelint-update

Align Stylelint config with GOV.UK Frontend
nhsuk · Feb 12, 2025 · 4bbcd5d · 4bbcd5d
2 parents 15b8836 + afe8d95
commit 4bbcd5d
Show file tree

Hide file tree

Showing 89 changed files with 2,638 additions and 3,268 deletions.
diff --git a/.stylelintrc.js b/.stylelintrc.js
@@ -1,5 +1,87 @@
 module.exports = {
-  extends: ['stylelint-config-prettier'],
-  plugins: ['stylelint-order', 'stylelint-scss'],
-  rules: require('./tests/linters/stylelint-rules')
+  extends: 'stylelint-config-gds/scss',
+  ignoreFiles: [
+    '**/dist/**',
+    '**/vendor/**',
+
+    // Ignore CSS-in-JS (including dotfiles)
+    '**/?(.)*.{cjs,js,mjs}'
+  ],
+  overrides: [
+    {
+      customSyntax: 'postcss-markdown',
+      files: ['**/*.md']
+    },
+    {
+      customSyntax: 'postcss-markdown',
+      files: ['**/coding-standards.md', '**/README.md'],
+      rules: {
+        // Allow markdown `*.md` CSS bad examples
+        'block-no-empty': null,
+        'color-no-hex': null,
+        'selector-max-id': null,
+        'selector-no-qualifying-type': null,
+
+        // Allow markdown `*.md` Sass bad examples
+        'scss/dollar-variable-pattern': null
+      }
+    },
+    {
+      customSyntax: 'postcss-scss',
+      files: ['**/*.scss'],
+      rules: {
+        // Disallow hex colours
+        // https://stylelint.io/user-guide/rules/color-no-hex/
+        'color-no-hex': true,
+
+        // Properties and values that are disallowed
+        // https://stylelint.io/user-guide/rules/declaration-property-value-disallowed-list/
+        'declaration-property-value-disallowed-list': {
+          transition: ['all'],
+          '/^border/': ['none']
+        },
+
+        // Disallow @mixin before @extends
+        // /~https://github.com/hudochenkov/stylelint-order/blob/master/rules/order/README.md#extended-at-rule-objects
+        'order/order': [
+          {
+            type: 'at-rule',
+            name: 'extend'
+          },
+          {
+            type: 'at-rule',
+            name: 'mixin'
+          }
+        ],
+
+        // Allow underscores (but not numbers) in mixin naming pattern
+        // /~https://github.com/stylelint-scss/stylelint-scss/tree/master/src/rules/at-mixin-pattern
+        'scss/at-mixin-pattern': [
+          /^([a-z-_])*$/,
+          {
+            message: 'Mixin names may only contain [a-z-_] characters'
+          }
+        ],
+
+        // Allow underscores in $variable naming pattern
+        // /~https://github.com/stylelint-scss/stylelint-scss/tree/master/src/rules/dollar-variable-pattern
+        'scss/dollar-variable-pattern': [
+          /^([a-z0-9-_])*$/,
+          {
+            message: 'Variable names may only contain [a-z0-9-_] characters'
+          }
+        ],
+
+        // Allow underscores (but not numbers) in %placeholder naming pattern
+        // /~https://github.com/stylelint-scss/stylelint-scss/tree/master/src/rules/percent-placeholder-pattern
+        'scss/percent-placeholder-pattern': [
+          /^([a-z-_])*$/,
+          {
+            message: 'Placeholders may only contain [a-z-_] characters'
+          }
+        ]
+      }
+    }
+  ],
+  plugins: ['stylelint-order']
 }
diff --git a/docs/contributing/coding-standards.md b/docs/contributing/coding-standards.md
@@ -61,9 +61,9 @@ The naming convention follows this pattern:
 .block__element {}
 .block--modifier {}
 
-.nhsuk-card              // Block - the root of a component
-.nhsuk-card__heading     // Element - a part of the block
-.nhsuk-card--clickable   // Modifier - a variant of the block
+.nhsuk-card {}            // Block - the root of a component
+.nhsuk-card__heading {}   // Element - a part of the block
+.nhsuk-card--clickable {} // Modifier - a variant of the block
 ```
 
 It uses double hyphens (`--`) and underscores (`__`) so that the block, element
@@ -72,9 +72,9 @@ or modifiers themselves can be hyphen delimited without causing ambiguity.
 For example:
 
 ```scss
-.nhsuk-a-z-nav
-.nhsuk-a-z-nav__link
-.nhsuk-a-z-nav__link--disabled
+.nhsuk-a-z-nav {}
+.nhsuk-a-z-nav__link {}
+.nhsuk-a-z-nav__link--disabled {}
 ```
 
 #### BEM further reading:
@@ -97,11 +97,11 @@ Bad:
 
 ```scss
 .nhsuk-contents-list {
-  ...
+  // ...
   &__item {
-    ...
-    &:before {
-      ...
+    // ...
+    &::before {
+      // ...
     }
   }
 }
@@ -111,13 +111,13 @@ Good:
 
 ```scss
 .nhsuk-contents-list {
-  ...
+  // ...
 }
 
 .nhsuk-contents-list__item {
-  ...
-  &:before {
-    ...
+  // ...
+  &::before {
+    // ...
   }
 }
 ```
@@ -134,33 +134,33 @@ This enables the NHSUK styles to be used inside other applications, where, for e
 
 ```scss
 div#nhsuk-ers {
-...
-@import 'node_modules/nhsuk-frontend/packages/core/all';
-...
+// ...
+@import "node_modules/nhsuk-frontend/packages/core/all";
+// ...
 }
 ```
 
 Bad:
 
 ```scss
 .nhsuk-checkboxes__conditional {
-  ...
+  // ...
   .js-enabled &--hidden {
-    ...
+    // ...
   }
- ...
+ // ...
 }
 ```
 
 Good:
 
 ```scss
 .nhsuk-checkboxes__conditional {
-  ...
+  // ...
 }
 
 .js-enabled .nhsuk-checkboxes__conditional--hidden {
-  ...
+  // ...
 }
 ```
 
@@ -200,21 +200,19 @@ the top block comment and then a reference to the number should go next to the l
 Example:
 
 ```scss
-/* ==========================================================================
-   #TITLE
-   ========================================================================== */
-
-/**
- * Long-form comment.
- *
- * This spans multiple lines and is also constrained to no longer than 80
- * characters in width.
- *
- * 1. Provide line-comments like this.
- */
-
-.X-class {
-  color: red; /* [1] */
+////
+/// Title
+////
+
+/// Long-form comment
+///
+/// This spans multiple lines and is also constrained to no longer than 80
+/// characters in width.
+///
+/// 1. Provide line-comments like this.
+
+.nhsuk-example {
+  color: $color_nhsuk-red; // [1]
 }
 ```
 

diff --git a/docs/contributing/linting.md b/docs/contributing/linting.md
@@ -187,15 +187,15 @@ margin: 1px 2px 3px;
 Bad:
 
 ```
-@import '_foo.scss';
-@import '_bar/foo.scss';
+@import "_foo.scss";
+@import "_bar/foo.scss";
 ```
 
 Good:
 
 ```
-@import 'foo';
-@import 'bar/foo';
+@import "foo";
+@import "bar/foo";
 ```
 
 ### Properties should be formatted with a single space separating the colon from the property's value
@@ -204,15 +204,15 @@ Bad:
 
 ```
 .foo {
-  content:'bar';
+  content:"bar";
 }
 ```
 
 Good:
 
 ```
 .foo {
-  content: 'bar';
+  content: "bar";
 }
 ```
 

diff --git a/docs/installation/installing-with-npm.md b/docs/installation/installing-with-npm.md
@@ -38,18 +38,18 @@ To build the stylesheet you will need a pipeline set up to compile [Sass](https:
 
 You need to import the NHS.UK frontend styles into the main Sass file in your project. You should place the below code before your own Sass rules (or Sass imports).
 
-```SCSS
-@import 'node_modules/nhsuk-frontend/packages/nhsuk';
+```scss
+@import "node_modules/nhsuk-frontend/packages/nhsuk";
 ```
 
 Alternatively you can import each of the individual components separately, meaning you can import just the components that you are using.
 
-```SCSS
+```scss
 // Core (required)
-@import 'node_modules/nhsuk-frontend/packages/core/all';
+@import "node_modules/nhsuk-frontend/packages/core/all";
 
 // Individual component (optional)
-@import 'node_modules/nhsuk-frontend/packages/components/action-link/action-link';
+@import "node_modules/nhsuk-frontend/packages/components/action-link/action-link";
 ```
 
 ## Importing JavaScript