Add stylelint rule to disallow the order CSS property

.stylelintrc.json

@@ -15,6 +15,12 @@
 		"font-weight-notation": null,
 		"max-line-length": null,
 		"no-descending-specificity": null,
+		"property-disallowed-list": [
+			[ "order" ],
+			{
+				"message": "Avoid the order property. For accessibility reasons, visual, reading, and DOM order must match. Only use the order property when it does not affect reading order, meaning, and interaction"
+			}
+		],
 		"rule-empty-line-before": null,
 		"selector-class-pattern": null,
 		"value-keyword-case": null,
@@ -29,5 +35,6 @@
 		"scss/at-else-empty-line-before": null,
 		"scss/at-if-closing-brace-space-after": null,
 		"no-invalid-position-at-import-rule": null
-	}
+	},
+	"reportDescriptionlessDisables": true
 }

packages/base-styles/_mixins.scss

@@ -284,9 +284,8 @@
 			display: inline-block;
 			vertical-align: middle;
 			width: 16px;
-			/* stylelint-disable */
+			/* stylelint-disable-next-line font-family-no-missing-generic-family-keyword -- dashicons don't need a generic family keyword. */
 			font: normal 30px/1 dashicons;
-			/* stylelint-enable */
 			speak: none;
 			-webkit-font-smoothing: antialiased;
 			-moz-osx-font-smoothing: grayscale;
@@ -518,12 +517,9 @@
 
 // Deprecated from UI, kept for back-compat.
 @mixin gradient-colors-deprecated() {
-	/*
-	 * Our classes uses the same values we set for gradient value attributes,
-	 * and we can not use spacing because of WP multi site kses rule.
-	 */
+	// Our classes uses the same values we set for gradient value attributes.
 
-	/* stylelint-disable function-comma-space-after */
+	/* stylelint-disable function-comma-space-after -- We can not use spacing because of WP multi site kses rule. */
 	.has-vivid-green-cyan-to-vivid-cyan-blue-gradient-background {
 		background: linear-gradient(135deg,rgba(0,208,132,1) 0%,rgba(6,147,227,1) 100%);
 	}

packages/block-editor/src/components/block-list/content.scss

@@ -22,8 +22,8 @@
 // under your actual selection.
 // This uses a CSS hack to show the rules to Safari only. Failing here is okay,
 // it just makes the selection indication slightly less precise. That makes this
-// hack a progressive enhancement. Stylelint is disabled to allow the hack to work.
-/* stylelint-disable */
+// hack a progressive enhancement.
+/* stylelint-disable -- Stylelint is disabled to allow the hack to work. */
 _::-webkit-full-page-media, _:future, :root .block-editor-block-list__layout::selection,
 _::-webkit-full-page-media, _:future, :root .has-multi-selection .block-editor-block-list__layout::selection {
 	background-color: transparent;

packages/block-editor/src/hooks/color.scss

@@ -5,6 +5,7 @@
 		 * injected color controls can appear as a single item group without
 		 * the contrast checkers suddenly appearing between items.
 		 */
+		/* stylelint-disable-next-line property-disallowed-list -- This should be removed when https://github.com/WordPress/gutenberg/issues/58936 is fixed. */
 		order: 9999;
 		grid-column: span 2;
 		margin-top: $grid-unit-20;

packages/block-library/src/buttons/editor.scss

@@ -33,9 +33,7 @@ $blocks-block__margin: 0.5em;
 	//
 	// This back compat rule is ignored if the user decides to use the
 	// newer justification options on the button block, hence the :not.
-	//
-	// Disable the stylelint rule, otherwise this selector is ugly!
-	/* stylelint-disable indentation */
+	/* stylelint-disable indentation -- Disable the stylelint rule, otherwise this selector is ugly! */
 	&:not(
 		.is-content-justification-space-between,
 		.is-content-justification-right,

packages/block-library/src/buttons/style.scss

@@ -55,9 +55,7 @@ $blocks-block__margin: 0.5em;
 	//
 	// This back compat rule is ignored if the user decides to use the
 	// newer justification options on the button block, hence the :not.
-	//
-	// Disable the stylelint rule, otherwise this selector is ugly!
-	/* stylelint-disable indentation */
+	/* stylelint-disable indentation -- Disable the stylelint rule, otherwise this selector is ugly! */
 	&:not(
 		.is-content-justification-space-between,
 		.is-content-justification-right,

packages/block-library/src/code/theme.native.scss

@@ -1,4 +1,4 @@
-/* stylelint-disable font-family-no-missing-generic-family-keyword */
+/* stylelint-disable font-family-no-missing-generic-family-keyword -- iOS will use the Menlo typeface and Android will use monospace, no need for a generic family keyword. */
 
 .blockCode {
 	font-family: $default-monospace-font;

packages/block-library/src/common.scss

@@ -165,8 +165,8 @@ html :where(img[class*="wp-image-"]) {
 // Set the admin bar offset for sticky positioned blocks to the height of the admin bar.
 // This allows sticky positioned blocks to be positioned correctly when the admin bar is visible.
 html :where(.is-position-sticky) {
-	/* stylelint-disable length-zero-no-unit */
-	--wp-admin--admin-bar--position-offset: var(--wp-admin--admin-bar--height, 0px); // 0px is set explicitly so that it can be used in a calc value.
+	/* stylelint-disable length-zero-no-unit -- 0px is set explicitly so that it can be used in a calc value. */
+	--wp-admin--admin-bar--position-offset: var(--wp-admin--admin-bar--height, 0px);
 	/* stylelint-enable length-zero-no-unit */
 }
 
@@ -175,8 +175,8 @@ html :where(.is-position-sticky) {
 // is not fixed to the top on mobile devices, but is fixed on viewports larger than 600px.
 @media screen and (max-width: 600px) {
 	html :where(.is-position-sticky) {
-		/* stylelint-disable length-zero-no-unit */
-		--wp-admin--admin-bar--position-offset: 0px; // 0px is set explicitly so that it can be used in a calc value.
+		/* stylelint-disable length-zero-no-unit -- 0px is set explicitly so that it can be used in a calc value. */
+		--wp-admin--admin-bar--position-offset: 0px;
 		/* stylelint-enable length-zero-no-unit */
 	}
 }

packages/block-library/src/image/style.scss

@@ -98,11 +98,9 @@
 		border-radius: 9999px;
 
 		// If a browser supports it, we will switch to using a circular SVG mask.
-		// The stylelint override is necessary to use the SVG inline here.
 		@supports (mask-image: none) or (-webkit-mask-image: none) {
-			/* stylelint-disable */
+			/* stylelint-disable-next-line function-url-quotes -- We need quotes for the data URL to use the SVG inline. */
 			mask-image: url('data:image/svg+xml;utf8,<svg viewBox="0 0 100 100" xmlns="http://www.w3.org/2000/svg"><circle cx="50" cy="50" r="50"/></svg>');
-			/* stylelint-enable */
 			mask-mode: alpha;
 			mask-repeat: no-repeat;
 			mask-size: contain;

packages/components/src/button/style.scss

@@ -93,8 +93,7 @@
 		&.is-busy[aria-disabled="true"] {
 			color: $components-color-accent-inverted;
 			background-size: 100px 100%;
-			// Disable reason: This function call looks nicer when each argument is on its own line.
-			/* stylelint-disable */
+			/* stylelint-disable -- Disable reason: This function call looks nicer when each argument is on its own line. */
 			background-image: linear-gradient(
 				-45deg,
 				$components-color-accent 33%,
@@ -163,13 +162,13 @@
 
 		&:hover:not(:disabled, [aria-disabled="true"]) {
 			// TODO: Prepare for theming (https://github.com/WordPress/gutenberg/pull/45466/files#r1030872724)
-			/* stylelint-disable-next-line declaration-property-value-disallowed-list */
+			/* stylelint-disable-next-line declaration-property-value-disallowed-list -- Allow tertiary buttons to use colors from the user admin color scheme. */
 			background: rgba(var(--wp-admin-theme-color--rgb), 0.04);
 		}
 
 		&:active:not(:disabled, [aria-disabled="true"]) {
 			// TODO: Prepare for theming (https://github.com/WordPress/gutenberg/pull/45466/files#r1030872724)
-			/* stylelint-disable-next-line declaration-property-value-disallowed-list */
+			/* stylelint-disable-next-line declaration-property-value-disallowed-list -- Allow tertiary buttons to use colors from the user admin color scheme. */
 			background: rgba(var(--wp-admin-theme-color--rgb), 0.08);
 		}
 
@@ -262,8 +261,7 @@
 		}
 		opacity: 1;
 		background-size: 100px 100%;
-		// Disable reason: This function call looks nicer when each argument is on its own line.
-		/* stylelint-disable */
+		/* stylelint-disable -- Disable reason: This function call looks nicer when each argument is on its own line. */
 		background-image: linear-gradient(
 			-45deg,
 			// TODO: Prepare for theming (https://github.com/WordPress/gutenberg/pull/45466/files#r1030872724)

packages/components/src/circular-option-picker/style.scss

@@ -60,8 +60,7 @@ $color-palette-circle-spacing: 12px;
 	border-radius: $radius-round;
 	// Show a thin circular outline in Windows high contrast mode, otherwise the button is invisible.
 	z-index: z-index(".components-circular-option-picker__option-wrapper::before");
-	// Need to disable the lint rule because given that we are in the presence of a data URL that needs quotes we need to wrap it with single quotes.
-	/* stylelint-disable-next-line function-url-quotes */
+	/* stylelint-disable-next-line function-url-quotes -- We need quotes for the data URL to use the SVG inline. */
 	background: url('data:image/svg+xml,%3Csvg width="28" height="28" fill="none" xmlns="http://www.w3.org/2000/svg"%3E%3Cpath d="M6 8V6H4v2h2zM8 8V6h2v2H8zM10 16H8v-2h2v2zM12 16v-2h2v2h-2zM12 18v-2h-2v2H8v2h2v-2h2zM14 18v2h-2v-2h2zM16 18h-2v-2h2v2z" fill="%23555D65"/%3E%3Cpath fill-rule="evenodd" clip-rule="evenodd" d="M18 18h2v-2h-2v-2h2v-2h-2v-2h2V8h-2v2h-2V8h-2v2h2v2h-2v2h2v2h2v2zm-2-4v-2h2v2h-2z" fill="%23555D65"/%3E%3Cpath d="M18 18v2h-2v-2h2z" fill="%23555D65"/%3E%3Cpath fill-rule="evenodd" clip-rule="evenodd" d="M8 10V8H6v2H4v2h2v2H4v2h2v2H4v2h2v2H4v2h2v-2h2v2h2v-2h2v2h2v-2h2v2h2v-2h2v2h2v-2h2v-2h-2v-2h2v-2h-2v-2h2v-2h-2v-2h2V8h-2V6h2V4h-2v2h-2V4h-2v2h-2V4h-2v2h-2V4h-2v2h2v2h-2v2H8zm0 2v-2H6v2h2zm2 0v-2h2v2h-2zm0 2v-2H8v2H6v2h2v2H6v2h2v2h2v-2h2v2h2v-2h2v2h2v-2h2v2h2v-2h-2v-2h2v-2h-2v-2h2v-2h-2v-2h2V8h-2V6h-2v2h-2V6h-2v2h-2v2h2v2h-2v2h-2z" fill="%23555D65"/%3E%3Cpath fill-rule="evenodd" clip-rule="evenodd" d="M4 0H2v2H0v2h2v2H0v2h2v2H0v2h2v2H0v2h2v2H0v2h2v2H0v2h2v2H0v2h2v-2h2v2h2v-2h2v2h2v-2h2v2h2v-2h2v2h2v-2h2v2h2v-2h2v2h2v-2h2v-2h-2v-2h2v-2h-2v-2h2v-2h-2v-2h2v-2h-2v-2h2V8h-2V6h2V4h-2V2h2V0h-2v2h-2V0h-2v2h-2V0h-2v2h-2V0h-2v2h-2V0h-2v2H8V0H6v2H4V0zm0 4V2H2v2h2zm2 0V2h2v2H6zm0 2V4H4v2H2v2h2v2H2v2h2v2H2v2h2v2H2v2h2v2H2v2h2v2h2v-2h2v2h2v-2h2v2h2v-2h2v2h2v-2h2v2h2v-2h2v2h2v-2h-2v-2h2v-2h-2v-2h2v-2h-2v-2h2v-2h-2v-2h2V8h-2V6h2V4h-2V2h-2v2h-2V2h-2v2h-2V2h-2v2h-2V2h-2v2H8v2H6z" fill="%23555D65"/%3E%3C/svg%3E');
 }
 

packages/editor/src/components/autocompleters/style.scss

@@ -1,8 +1,7 @@
 .editor-autocompleters__user {
 	.editor-autocompleters__no-avatar::before {
-		/* stylelint-disable */
+		/* stylelint-disable-next-line font-family-no-missing-generic-family-keyword -- dashicons don't need a generic family keyword. */
 		font: normal 20px/1 dashicons;
-		/* stylelint-enable */
 		content: "\f110";
 		margin-right: 5px;
 		vertical-align: middle;

packages/editor/src/components/list-view-sidebar/style.scss

@@ -14,6 +14,7 @@
 	}
 	.editor-list-view-sidebar__close-button {
 		background: $white;
+		/* stylelint-disable-next-line property-disallowed-list -- This should be removed when https://github.com/WordPress/gutenberg/issues/59013 is fixed. */
 		order: 1;
 		align-self: center;
 		margin-right: $grid-unit-15;