From 52ddd324779c5868c3894e1527e24547207099ba Mon Sep 17 00:00:00 2001
From: Mark Otto <markdotto@gmail.com>
Date: Sat, 21 Mar 2026 14:55:59 -0700
Subject: [PATCH] Upgrade stylelint config

---
 .stylelintrc.json                    | 78 ---------------------------
 site/src/content/docs/guides/npm.mdx | 13 ++---
 stylelint.config.mjs                 | 79 ++++++++++++++++++++++++++++
 3 files changed, 86 insertions(+), 84 deletions(-)
 delete mode 100644 .stylelintrc.json
 create mode 100644 stylelint.config.mjs

diff --git a/.stylelintrc.json b/.stylelintrc.json
deleted file mode 100644
index 83354613a998..000000000000
--- a/.stylelintrc.json
+++ /dev/null
@@ -1,78 +0,0 @@
-{
-  "extends": [
-    "stylelint-config-twbs-bootstrap"
-  ],
-  "plugins": [
-    "stylelint-order"
-  ],
-  "reportInvalidScopeDisables": true,
-  "reportNeedlessDisables": true,
-  "rules": {
-    "selector-class-pattern": [
-      "^([a-z][a-z0-9]*(-[a-z0-9]+)*:)?([a-z][a-z0-9]*)(-[a-z0-9]+)*$",
-      { "message": "Expected class selector \"%s\" to be kebab-case (with optional breakpoint prefix)" }
-    ],
-    "order/order": [
-      [
-        { "type": "at-rule", "name": "use" },
-        { "type": "at-rule", "name": "forward" },
-        "dollar-variables",
-        "custom-properties",
-        "declarations",
-        "rules"
-      ]
-    ]
-  },
-  "overrides": [
-    {
-      "files": "**/*.scss",
-      "rules": {
-        "declaration-property-value-disallowed-list": {
-          "border": "none",
-          "outline": "none"
-        },
-        "function-disallowed-list": [
-          "lighten",
-          "darken"
-        ],
-        "property-disallowed-list": [
-          "border-radius",
-          "border-top-left-radius",
-          "border-top-right-radius",
-          "border-bottom-right-radius",
-          "border-bottom-left-radius",
-          "transition"
-        ],
-        "scss/dollar-variable-default": [
-          true,
-          {
-            "ignore": "local"
-          }
-        ],
-        "scss/selector-no-union-class-name": true
-      }
-    },
-    {
-      "files": "scss/**/*.{test,spec}.scss",
-      "rules": {
-        "scss/dollar-variable-default": null,
-        "declaration-no-important": null
-      }
-    },
-    {
-      "files": "site/**/*.scss",
-      "rules": {
-        "scss/dollar-variable-default": null
-      }
-    },
-    {
-      "files": "site/**/examples/**/*.css",
-      "rules": {
-        "comment-empty-line-before": null,
-        "property-no-vendor-prefix": null,
-        "selector-no-qualifying-type": null,
-        "value-no-vendor-prefix": null
-      }
-    }
-  ]
-}
diff --git a/site/src/content/docs/guides/npm.mdx b/site/src/content/docs/guides/npm.mdx
index e9edabcc238b..12b81d9cec02 100644
--- a/site/src/content/docs/guides/npm.mdx
+++ b/site/src/content/docs/guides/npm.mdx
@@ -54,7 +54,7 @@ We’ve already created the `my-project` folder and initialized npm. Now we’ll
 
 ```sh
 mkdir {css,scss}
-touch index.html scss/styles.scss postcss.config.js .stylelintrc.json
+touch index.html scss/styles.scss postcss.config.js stylelint.config.mjs
 ```
 
 When you’re done, your project should look like this:
@@ -64,7 +64,7 @@ my-project/
 ├── css/
 ├── scss/
 │   └── styles.scss
-├── .stylelintrc.json
+├── stylelint.config.mjs
 ├── index.html
 ├── package-lock.json
 ├── package.json
@@ -132,11 +132,12 @@ With dependencies installed and our project folder ready for us to start coding,
    }
    ```
 
-4. **Configure `.stylelintrc.json`.** We’re using `stylelint-config-twbs-bootstrap` to keep our Sass linting consistent with Bootstrap’s own code style.
+4. **Configure `stylelint.config.mjs`.** We’re using `stylelint-config-twbs-bootstrap` to keep our Sass linting consistent with Bootstrap’s own code style.
 
-   ```json
-   {
-     "extends": "stylelint-config-twbs-bootstrap"
+   ```js
+   /** @type {import('stylelint').Config} */
+   export default {
+     extends: 'stylelint-config-twbs-bootstrap',
    }
    ```
 
diff --git a/stylelint.config.mjs b/stylelint.config.mjs
new file mode 100644
index 000000000000..bdfaa365c9cd
--- /dev/null
+++ b/stylelint.config.mjs
@@ -0,0 +1,79 @@
+/** @type {import('stylelint').Config} */
+export default {
+  extends: [
+    'stylelint-config-twbs-bootstrap',
+  ],
+  plugins: [
+    'stylelint-order',
+  ],
+  reportInvalidScopeDisables: true,
+  reportNeedlessDisables: true,
+  rules: {
+    'selector-class-pattern': [
+      '^([a-z][a-z0-9]*(-[a-z0-9]+)*:)?([a-z][a-z0-9]*)(-[a-z0-9]+)*$',
+      { message: 'Expected class selector "%s" to be kebab-case (with optional breakpoint prefix)' },
+    ],
+    'order/order': [
+      [
+        { type: 'at-rule', name: 'use' },
+        { type: 'at-rule', name: 'forward' },
+        'dollar-variables',
+        'custom-properties',
+        'declarations',
+        'rules',
+      ],
+    ],
+  },
+  overrides: [
+    {
+      files: '**/*.scss',
+      rules: {
+        'declaration-property-value-disallowed-list': {
+          border: 'none',
+          outline: 'none',
+        },
+        'function-disallowed-list': [
+          'lighten',
+          'darken',
+        ],
+        'property-disallowed-list': [
+          'border-radius',
+          'border-top-left-radius',
+          'border-top-right-radius',
+          'border-bottom-right-radius',
+          'border-bottom-left-radius',
+          'transition',
+        ],
+        'scss/dollar-variable-default': [
+          true,
+          {
+            ignore: 'local',
+          },
+        ],
+        'scss/selector-no-union-class-name': true,
+      },
+    },
+    {
+      files: 'scss/**/*.{test,spec}.scss',
+      rules: {
+        'scss/dollar-variable-default': null,
+        'declaration-no-important': null,
+      },
+    },
+    {
+      files: 'site/**/*.scss',
+      rules: {
+        'scss/dollar-variable-default': null,
+      },
+    },
+    {
+      files: 'site/**/examples/**/*.css',
+      rules: {
+        'comment-empty-line-before': null,
+        'property-no-vendor-prefix': null,
+        'selector-no-qualifying-type': null,
+        'value-no-vendor-prefix': null,
+      },
+    },
+  ],
+}