Update Stylelint to v14, extend SCSS plugins, remove primer-* configs, resolve issues (#821)

This is a catch-all PR that modernizes and updates our Stylelint config, and resolves all open issues. This is a pretty big change - so I want to update all of our related dependencies in lockstep.

In particular, this PR

- [x] updates stylelint to `v14`
- [x] adds in the standard stylelint config for SCSS (`stylelint-config-standard-scss`)
- [x] swaps out `stylelint-config-prettier` for `stylelint-config-prettier-scss`
- [x] ~~properly update `@primer`-related plugins:~~ completely remove `primer` from our configuration
- [x] autofix, manually resolve, or disable all newly-introduced lint errors; **I've avoided manually resolving errors that would be a behavioural change**
- [x] re-runs `npm run format`

See the "next steps" section on some extra thoughts on disabling errors.

(implicitly, I'm also using node 16/the new package-lock format).

### disabling rules and next steps

I've introduced several new disabled rules. Let me quickly explain what's going on; there are two categories of rules I've disabled:

1. rules that were temporary disables; they were frequent enough that I couldn't manually resolve them, but should be simple. **I plan on opening issues to re-enable each of these rules**, just after this PR
    - `declaration-block-no-redundant-longhand-properties`: this is just tedious and error-prone
    - `no-descending-specificity`: this one is tricky since it could have impacts on the cascade (though that seems unlikely)
    - `scss/no-global-function-names`: I think we need to [import map and then use `map.get`](https://stackoverflow.com/questions/64210390/sass-map-get-doesnt-work-map-get-does-what-gives), but I'll leave this as out of scope for now
2. rules that are long-term disables; due to the SASS-based nature of our theme, I think we'll keep these in limbo
    - `alpha-value-notation` causes problems with SASS using the `modern` syntax - literals like `50%` are not properly interpolated, and they cause formatting issues on the site
    - `color-function-notation` also causes problems with SASS, but in this case the `modern` syntax breaks SASS compilation; we're not alone (see this [SO post](https://stackoverflow.com/questions/71805735/error-function-rgb-is-missing-argument-green-in-sass)). 

In addition, we have many inline `stylelint-disable` comments. I'd open a separate issue to audit them, especially since I think some disables are unnecessary.

### on Primer 

**note: there hasn't been much other discussion, so I'm going to remove primer's stylelint config.**

If I do add `@primer/stylelint-config`, I get *a ton* of errors about now using `@primer`'s in-built SCSS variables. I imagine that we probably won't want to use these presets (though I could be wrong). In that case, I think we could either:

1. disable all of those rules
4. not use `@primer/stylelint-config`, since we're not actually using primer, and shift back to the standard SCSS config provided by Stylelint

~~Any thoughts here? I also don't have the original context as to why we do use the primer rules, perhaps @pmarsceill can chime in?~~

.devcontainer/devcontainer.json

 // For format details, see https://aka.ms/devcontainer.json. For config options, see the README at:
 // https://github.com/microsoft/vscode-dev-containers/tree/v0.224.2/containers/jekyll
 {
-	"name": "Just the docs",
-	"build": {
-		"dockerfile": "Dockerfile",
-		"args": {
-			// Update 'VARIANT' to pick a Debian OS version: bullseye, buster
-			// Use bullseye when on local arm64/Apple Silicon.
-			"VARIANT": "bullseye",
-			// Enable Node.js: pick the latest LTS version
-			"NODE_VERSION": "lts/*"
-		}	
-	},
+  "name": "Just the docs",
+  "build": {
+    "dockerfile": "Dockerfile",
+    "args": {
+      // Update 'VARIANT' to pick a Debian OS version: bullseye, buster
+      // Use bullseye when on local arm64/Apple Silicon.
+      "VARIANT": "bullseye",
+      // Enable Node.js: pick the latest LTS version
+      "NODE_VERSION": "lts/*"
+    }
+  },
 
-	// Set *default* container specific settings.json values on container create.
-	"settings": {},
+  // Set *default* container specific settings.json values on container create.
+  "settings": {},
 
-	// Add the IDs of extensions you want installed when the container is created.
-	"extensions": [
-		"GitHub.vscode-pull-request-github"
-	],
+  // Add the IDs of extensions you want installed when the container is created.
+  "extensions": ["GitHub.vscode-pull-request-github"],
 
-	// Use 'forwardPorts' to make a list of ports inside the container available locally.
-	"forwardPorts": [
-		// Jekyll server
-		4000,
-		// Live reload server
-		35729
-	],
+  // Use 'forwardPorts' to make a list of ports inside the container available locally.
+  "forwardPorts": [
+    // Jekyll server
+    4000,
+    // Live reload server
+    35729
+  ],
 
-	// Use 'postCreateCommand' to run commands after the container is created.
-	"postCreateCommand": "sh .devcontainer/post-create.sh",
+  // Use 'postCreateCommand' to run commands after the container is created.
+  "postCreateCommand": "sh .devcontainer/post-create.sh",
 
-	// Comment out to connect as root instead. More info: https://aka.ms/vscode-remote/containers/non-root.
-	"remoteUser": "vscode"
+  // Comment out to connect as root instead. More info: https://aka.ms/vscode-remote/containers/non-root.
+  "remoteUser": "vscode"
 }

.stylelintrc.json

@@ -5,9 +5,17 @@
     "assets/css/just-the-docs-dark.scss",
     "_sass/vendor/**/*.scss"
   ],
-  "extends": ["stylelint-config-primer", "stylelint-config-prettier"],
+  "extends": [
+    "stylelint-config-standard-scss",
+    "stylelint-config-prettier-scss"
+  ],
   "plugins": ["stylelint-prettier"],
   "rules": {
-    "prettier/prettier": true
+    "prettier/prettier": true,
+    "alpha-value-notation": null,
+    "color-function-notation": null,
+    "declaration-block-no-redundant-longhand-properties": null,
+    "no-descending-specificity": null,
+    "scss/no-global-function-names": null
   }
 }

.vscode/tasks.json

 {
-    // See https://go.microsoft.com/fwlink/?LinkId=733558
-    // for the documentation about the tasks.json format
-    "version": "2.0.0",
-    "tasks": [
-        {
-            "label": "Serve",
-            "type": "shell",
-            "command": "bundle exec jekyll serve --livereload",
-            "group": {
-                "kind": "test",
-                "isDefault": true
-            },
-            "isBackground": true,
-        },
-        {
-            "label": "Build",
-            "type": "shell",
-            "command": "bundle exec jekyll build",
-            "group": {
-                "kind": "build",
-                "isDefault": true
-            },
-        }
-    ]
-}
\ No newline at end of file
+  // See https://go.microsoft.com/fwlink/?LinkId=733558
+  // for the documentation about the tasks.json format
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "label": "Serve",
+      "type": "shell",
+      "command": "bundle exec jekyll serve --livereload",
+      "group": {
+        "kind": "test",
+        "isDefault": true
+      },
+      "isBackground": true
+    },
+    {
+      "label": "Build",
+      "type": "shell",
+      "command": "bundle exec jekyll build",
+      "group": {
+        "kind": "build",
+        "isDefault": true
+      }
+    }
+  ]
+}

_sass/base.scss

-//
 // Base element style overrides
-//
 // stylelint-disable selector-no-type, selector-max-type, selector-max-specificity, selector-max-id
 
 * {
@@ -14,6 +12,7 @@
 
 html {
   @include fs-4;
+
   scroll-behavior: smooth;
 }
 

_sass/buttons.scss

-//
 // Buttons and things that look like buttons
-//
 // stylelint-disable color-named
 
 .btn {

_sass/code.scss

-//
 // Code and syntax highlighting
-//
-// stylelint-disable selector-no-qualifying-type, declaration-block-semicolon-newline-after,declaration-block-single-line-max-declarations, selector-no-type, selector-max-type
+// stylelint-disable selector-no-qualifying-type, declaration-block-semicolon-newline-after,declaration-block-single-line-max-declarations, selector-no-type, selector-max-type, scss/comment-no-empty
 
 // {% raw %}
 
@@ -100,6 +98,7 @@ figure.highlight {
   td,
   pre {
     @include fs-2;
+
     min-width: 0;
     padding: 0;
     background-color: $code-background-color;

_sass/color_schemes/dark.scss

 $body-background-color: $grey-dk-300;
 $sidebar-color: $grey-dk-300;
 $border-color: $grey-dk-200;
-
 $body-text-color: $grey-lt-300;
 $body-heading-color: $grey-lt-000;
 $nav-child-link-color: $grey-dk-000;
 $search-result-preview-color: $grey-dk-000;
-
 $link-color: $blue-000;
 $btn-primary-color: $blue-200;
 $base-button-color: $grey-dk-250;
-
 $search-background-color: $grey-dk-250;
 $table-background-color: $grey-dk-250;
 $feedback-color: darken($sidebar-color, 3%);
 
-//
 // The following highlight theme is more legible than that used for the light color scheme
-//
 
 // @import "./vendor/OneDarkJekyll/syntax-one-dark";
 // $code-background-color: #282c34;
 
 @import "./vendor/OneDarkJekyll/syntax-one-dark-vivid";
+
 $code-background-color: #31343f;
 
 // @import "./vendor/OneDarkJekyll/syntax-firewatch";

_sass/content.scss

 @charset "UTF-8";
 
-//
 // Styles for rendered markdown in the .main-content container
-//
 // stylelint-disable selector-no-type, max-nesting-depth, selector-max-compound-selectors, selector-max-type, selector-max-specificity, selector-max-id
 
 .main-content {
@@ -91,6 +89,7 @@
   .task-list-item-checkbox {
     margin-right: 0.6em;
     margin-left: -1.4em;
+
     // The same margin-left is used above for ul > li::before
   }
 
@@ -116,6 +115,7 @@
     grid-column: 1;
     font-weight: 500;
     text-align: right;
+
     &::after {
       content: ":";
     }
@@ -125,6 +125,7 @@
     grid-column: 2;
     margin-bottom: 0;
     margin-left: 1em;
+
     blockquote,
     div,
     dl,

_sass/labels.scss

-//
 // Labels (not the form kind)
-//
 
 .label,
 .label-blue {
@@ -16,6 +14,7 @@
   vertical-align: middle;
   background-color: $blue-100;
   @include fs-2;
+
   border-radius: 12px;
 }
 

_sass/layout.scss

-//
 // The basic two column layout
-//
 
 .side-bar {
   z-index: 0;
@@ -40,6 +38,7 @@
 
 .main-content-wrap {
   @include container;
+
   padding-top: $gutter-spacing-sm;
   padding-bottom: $gutter-spacing-sm;
 
@@ -111,6 +110,7 @@
 
 .site-title {
   @include container;
+
   flex-grow: 1;
   display: flex;
   height: 100%;
@@ -184,6 +184,7 @@ body {
 
 .site-footer {
   @include container;
+
   position: absolute;
   bottom: 0;
   left: 0;

_sass/modules.scss

-//
 // Import external dependencies
-//
-@import "./vendor/normalize.scss/normalize.scss";
+@import "./vendor/normalize.scss/normalize";
 
-//
 // Modules
-//
 @import "./base";
 @import "./layout";
 @import "./content";

_sass/navigation.scss

-//
 // Main nav, breadcrumb, etc...
-//
 // stylelint-disable selector-no-type, max-nesting-depth, selector-max-compound-selectors, selector-max-type, selector-max-specificity
 
 .nav-list {
@@ -11,6 +9,7 @@
 
   .nav-list-item {
     @include fs-4;
+
     position: relative;
     margin: 0;
 
@@ -71,6 +70,7 @@
       @if $nav-list-expander-right {
         right: 0;
       }
+
       width: $nav-list-item-height-sm;
       height: $nav-list-item-height-sm;
       padding-top: #{$nav-list-item-height-sm / 4};

_sass/print.scss

-// stylelint-disable selector-max-specificity, selector-max-id, selector-max-type, selector-no-qualifying-type, primer/no-override,
+// stylelint-disable selector-max-specificity, selector-max-id, selector-max-type, selector-no-qualifying-type
 
 @media print {
   .site-footer,

_sass/search.scss

-//
 // Search input and autocomplete
-//
 
 .search {
   position: relative;

_sass/support/_functions.scss

 @function rem($size, $unit: "") {
-  $remSize: $size / $root-font-size;
+  $rem-size: $size / $root-font-size;
 
-  @if ($unit == false) {
-    @return #{$remSize};
+  @if $unit == false {
+    @return #{$rem-size};
   } @else {
-    @return #{$remSize}rem;
+    @return #{$rem-size}rem;
   }
 }

_sass/support/_variables.scss

-//
 // Typography
-//
 
-$body-font-family: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI",
-  Roboto, "Helvetica Neue", Arial, sans-serif !default;
-$mono-font-family: "SFMono-Regular", Menlo, Consolas, Monospace !default;
+$body-font-family: system-ui, -apple-system, blinkmacsystemfont, "Segoe UI",
+  roboto, "Helvetica Neue", arial, sans-serif !default;
+$mono-font-family: "SFMono-Regular", menlo, consolas, monospace !default;
 $root-font-size: 16px !default; // Base font-size for rems
 $body-line-height: 1.4 !default;
 $content-line-height: 1.6 !default;
 $body-heading-line-height: 1.25 !default;
 
-//
 // Font size
 // `-sm` suffix is the size at the small (and above) media query
-//
 
 $font-size-1: 9px !default;
 $font-size-1-sm: 10px !default;
-$font-size-2: 11px !default; //h4 - uppercased!, h6 not uppercased, text-small
-$font-size-3: 12px !default; //h5
+$font-size-2: 11px !default; // h4 - uppercased!, h6 not uppercased, text-small
+$font-size-3: 12px !default; // h5
 $font-size-4: 14px !default;
-$font-size-5: 16px !default; //h3
-$font-size-6: 18px !default; //h2
+$font-size-5: 16px !default; // h3
+$font-size-6: 18px !default; // h2
 $font-size-7: 24px !default;
-$font-size-8: 32px !default; //h1
+$font-size-8: 32px !default; // h1
 $font-size-9: 36px !default;
 $font-size-10: 42px !default;
 $font-size-10-sm: 48px !default;
 
-//
 // Colors
-//
 
 $white: #fff !default;
-
 $grey-dk-000: #959396 !default;
 $grey-dk-100: #5c5962 !default;
 $grey-dk-200: #44434d !default;
 $grey-dk-250: #302d36 !default;
 $grey-dk-300: #27262b !default;
-
 $grey-lt-000: #f5f6fa !default;
 $grey-lt-100: #eeebee !default;
 $grey-lt-200: #ecebed !default;
 $grey-lt-300: #e6e1e8 !default;
-
 $purple-000: #7253ed !default;
 $purple-100: #5e41d0 !default;
 $purple-200: #4e26af !default;
 $purple-300: #381885 !default;
-
 $blue-000: #2c84fa !default;
 $blue-100: #2869e6 !default;
 $blue-200: #264caf !default;
 $blue-300: #183385 !default;
-
 $green-000: #41d693 !default;
 $green-100: #11b584 !default;
 $green-200: #009c7b !default;
 $green-300: #026e57 !default;
-
 $yellow-000: #ffeb82 !default;
 $yellow-100: #fadf50 !default;
 $yellow-200: #f7d12e !default;
 $yellow-300: #e7af06 !default;
-
 $red-000: #f77e7e !default;
 $red-100: #f96e65 !default;
 $red-200: #e94c4c !default;
 $red-300: #dd2e2e !default;
-
 $body-background-color: $white !default;
 $sidebar-color: $grey-lt-000 !default;
 $search-background-color: $white !default;
 $table-background-color: $white !default;
 $code-background-color: $grey-lt-000 !default;
 $feedback-color: darken($sidebar-color, 3%) !default;
-
 $body-text-color: $grey-dk-100 !default;
 $body-heading-color: $grey-dk-300 !default;
 $search-result-preview-color: $grey-dk-000 !default;
@@ -85,9 +70,7 @@ $link-color: $purple-000 !default;
 $btn-primary-color: $purple-100 !default;
 $base-button-color: #f7f7f7 !default;
 
-//
 // Spacing
-//
 
 $spacing-unit: 1rem; // 1rem == 16px
 
@@ -104,7 +87,6 @@ $spacers: (
   sp-9: $spacing-unit * 3.5,
   sp-10: $spacing-unit * 4,
 ) !default;
-
 $sp-1: map-get($spacers, sp-1) !default; // 0.25 rem == 4px
 $sp-2: map-get($spacers, sp-2) !default; // 0.5  rem == 8px
 $sp-3: map-get($spacers, sp-3) !default; // 0.75 rem == 12px
@@ -116,17 +98,13 @@ $sp-8: map-get($spacers, sp-8) !default; // 3    rem == 48px
 $sp-9: map-get($spacers, sp-9) !default; // 3.5  rem == 56px
 $sp-10: map-get($spacers, sp-10) !default; // 4  rem == 64px
 
-//
 // Borders
-//
 
 $border: 1px solid !default;
 $border-radius: 4px !default;
 $border-color: $grey-lt-100 !default;
 
-//
 // Grid system
-//
 
 $gutter-spacing: $sp-6 !default;
 $gutter-spacing-sm: $sp-4 !default;
@@ -140,9 +118,7 @@ $header-height: 60px !default;
 $search-results-width: $content-width - $nav-width !default;
 $transition-duration: 400ms;
 
-//
 // Media queries in pixels
-//
 
 $media-queries: (
   xs: 320px,

_sass/support/mixins/_layout.scss

@@ -10,7 +10,7 @@
   $value: map-get($media-queries, $name);
 
   // If the key exists in the map
-  @if $value != null {
+  @if $value {
     // Prints a media query based on the value
     @media (min-width: rem($value)) {
       @content;

_sass/tables.scss

-//
 // Tables
-//
 // stylelint-disable max-nesting-depth, selector-no-type, selector-max-type
 
 .table-wrapper {
@@ -22,6 +20,7 @@ table {
 th,
 td {
   @include fs-3;
+
   min-width: 120px;
   padding-top: $sp-2;
   padding-right: $sp-3;

_sass/typography.scss

-//
 // Typography
-//
-// stylelint-disable primer/selector-no-utility, primer/no-override, selector-no-type, selector-max-type, selector-max-specificity, selector-max-id
+
+// stylelint-disable selector-no-type, selector-max-type, selector-max-specificity, selector-max-id
 
 h1,
 .text-alpha {
   @include fs-8;
+
   font-weight: 300;
 }
 
@@ -23,6 +23,7 @@ h3,
 h4,
 .text-delta {
   @include fs-2;
+
   font-weight: 400;
   text-transform: uppercase;
   letter-spacing: 0.1em;

_sass/utilities/_colors.scss

-//
 // Utility classes for colors
-//
 
 // Text colors