Add stylelint CSS linting

.github/workflows/test-and-zip-default-themes.yml

@@ -242,20 +242,20 @@ jobs:
           persist-credentials: false
 
       - name: Set up Node.js for themes needing minification
-        if: matrix.theme == 'twentytwentytwo' || matrix.theme == 'twentytwentyfive'
+        if: matrix.theme == 'twentytwentytwo' || matrix.theme == 'twentytwentyfive' || matrix.theme == 'twentytwentyone'
         uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
         with:
           node-version-file: 'src/wp-content/themes/${{ matrix.theme }}/.nvmrc'
           cache: npm
           cache-dependency-path: src/wp-content/themes/${{ matrix.theme }}/package-lock.json
 
       - name: Install npm dependencies
-        if: matrix.theme == 'twentytwentytwo' || matrix.theme == 'twentytwentyfive'
+        if: matrix.theme == 'twentytwentytwo' || matrix.theme == 'twentytwentyfive' || matrix.theme == 'twentytwentyone'
         run: npm ci
         working-directory: src/wp-content/themes/${{ matrix.theme }}
 
       - name: Build theme assets
-        if: matrix.theme == 'twentytwentytwo' || matrix.theme == 'twentytwentyfive'
+        if: matrix.theme == 'twentytwentytwo' || matrix.theme == 'twentytwentyfive' || matrix.theme == 'twentytwentyone'
         run: npm run build
         working-directory: src/wp-content/themes/${{ matrix.theme }}
 

.stylelintignore

@@ -0,0 +1,27 @@
+# Ignore WordPress plugin files.
+src/wp-content/plugins/**/*
+
+# Ignore WordPress theme files.
+src/wp-content/themes/**/*
+
+# Ignore WordPress block files.
+src/wp-includes/blocks/**/*
+
+# Ignore admin color schemes auto generated files.
+src/wp-admin/css/colors/*/*.css
+
+# Ignore WordPress included dist files.
+src/wp-includes/css/dist/**/*
+
+# Ignore files copied to wp-includes js.
+src/wp-includes/js/**/*
+
+# Ignore WordPress JS vendor files.
+src/js/_enqueues/vendor/**/*
+
+# Ignore minified CSS files.
+**/*.min.css
+
+# Ignore RTL CSS files.
+**/*-rtl.css
+**/*-rtl.min.css

.stylelintignore-themes

@@ -0,0 +1,9 @@
+# Ignore Node modules.
+node_modules
+
+# Ignore minified CSS files.
+**/*.min.css
+
+# Ignore RTL CSS files.
+**/*-rtl.css
+**/*-rtl.min.css

.stylelintrc.js

@@ -0,0 +1,114 @@
+/** @type {import('stylelint').Config} */
+module.exports = {
+	extends: '@wordpress/stylelint-config/scss-stylistic',
+	plugins: [
+		'stylelint-plugin-logical-css',
+		'@wordpress/theme/stylelint-plugins/no-token-fallback-values',
+	],
+	reportNeedlessDisables: true,
+	rules: {
+		'at-rule-empty-line-before': [
+			'always',
+			{
+				except: [ 'blockless-after-blockless' ],
+				ignore: [ 'first-nested', 'after-comment' ],
+			},
+		],
+		'at-rule-no-unknown': null,
+		'comment-empty-line-before': null,
+		'declaration-property-unit-allowed-list': [
+			{
+				'line-height': [],
+			},
+		],
+		'declaration-property-value-allowed-list': [
+			{
+				'flex-direction': '/^(?!(row|column)-reverse).*$/',
+			},
+			{
+				message: ( property, value ) =>
+					`Avoid "${ value }" value for the "${ property }" property. For accessibility reasons, visual, reading, and DOM order must match. Only use the reverse values when they do not affect reading order, meaning, and interaction.`,
+			},
+		],
+		'font-family-no-missing-generic-family-keyword': [
+			true,
+			{
+				ignoreFontFamilies: [ 'dashicons' ],
+			},
+		],
+		'font-weight-notation': 'numeric',
+		'function-disallowed-list': [ 'rgb' ],
+		'no-descending-specificity': null,
+		'no-invalid-position-at-import-rule': 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': [
+			'always',
+			{
+				except: [ 'first-nested' ],
+				ignore: [ 'after-comment' ],
+			},
+		],
+		'selector-class-pattern': [
+			'^[a-z][a-z0-9]*(?:(?:__|--|-)[a-z0-9]+)*$',
+			{
+				message:
+					'Class selector should use lowercase class segments separated with hyphens, double hyphens, or double underscores',
+			},
+		],
+		'selector-id-pattern': [
+			'^([a-z][a-z0-9]*)(-[a-z0-9]+)*$',
+			{
+				message:
+					'ID selector should use lowercase and separate words with hyphens',
+			},
+		],
+		'selector-no-qualifying-type': [
+			true,
+			{
+				severity: 'warning',
+			},
+		],
+		'value-keyword-case': [
+			'lower',
+			{
+				ignoreKeywords: [
+					'currentColor',
+					'optimizeLegibility'
+				],
+			},
+		],
+		'scss/at-else-empty-line-before': null,
+		'scss/at-extend-no-missing-placeholder': null,
+		'scss/at-if-closing-brace-newline-after': null,
+		'scss/at-if-closing-brace-space-after': null,
+		'scss/comment-no-empty': null,
+		'scss/load-partial-extension': null,
+		'scss/no-global-function-names': null,
+		'scss/operator-no-newline-after': null,
+		'scss/operator-no-unspaced': null,
+		'scss/selector-no-redundant-nesting-selector': null,
+		'@stylistic/max-empty-lines': 1,
+		'@stylistic/max-line-length': null,
+		'@stylistic/selector-descendant-combinator-no-non-space': true,
+		// Keep these lines. Don't change their order otherwise indentation will break.
+		// It's not about a literal 'execution order', but rather a compatibility issue.
+		'@stylistic/block-closing-brace-newline-before': 'always',
+		'@stylistic/block-opening-brace-newline-after': 'always',
+		'@stylistic/declaration-block-semicolon-newline-after': 'always',
+		'@stylistic/selector-list-comma-space-after': 'always-single-line',
+		'@stylistic/selector-list-comma-newline-after': 'always',
+		'@stylistic/declaration-colon-newline-after': 'always-multi-line',
+		'@stylistic/indentation': 'tab',
+		// End keep these lines.
+	},
+	reportDescriptionlessDisables: true,
+	ignorePath: '.stylelintignore',
+};
+
+

Gruntfile.js

@@ -1771,8 +1771,21 @@ module.exports = function(grunt) {
 		'qunit:compiled'
 	] );
 
+	grunt.registerTask( 'lint:css', 'Runs Stylelint on core CSS and checks warning-level rule thresholds.', function() {
+		var done = this.async();
+
+		grunt.util.spawn( {
+			cmd: 'node',
+			args: [ 'tools/stylelint/lint-css.js' ],
+			opts: { stdio: 'inherit' }
+		}, function( error ) {
+			done( ! error );
+		} );
+	} );
+
 	grunt.registerTask( 'precommit:css', [
-		'postcss:core'
+		'postcss:core',
+		'lint:css',
 	] );
 
 	grunt.registerTask( 'precommit:php', [

package.json

@@ -76,6 +76,8 @@
 		"sinon": "16.1.3",
 		"sinon-test": "~3.1.6",
 		"source-map-loader": "5.0.0",
+		"stylelint": "16.26.1",
+		"stylelint-plugin-logical-css": "2.1.0",
 		"typescript": "6.0.3",
 		"update-browserslist-db": "1.3.1",
 		"uuid": "14.0.1",
@@ -126,6 +128,12 @@
 		"grunt": "grunt",
 		"lint:jsdoc": "wp-scripts lint-js",
 		"lint:jsdoc:fix": "wp-scripts lint-js --fix",
+		"lint:css": "node ./tools/stylelint/lint-css.js",
+		"lint:css:fix": "wp-scripts lint-style \"src/**/*.{css,scss}\" --fix",
+		"lint:css:thresholds": "node ./tools/stylelint/check-warning-thresholds.js",
+		"lint:css:thresholds:update": "node ./tools/stylelint/check-warning-thresholds.js --update",
+		"lint:css:themes": "wp-scripts lint-style \"src/wp-content/themes/**/*.{css,scss}\" --ignore-path .stylelintignore-themes",
+		"lint:css:themes:fix": "npm run lint:css:themes -- --fix",
 		"typecheck:js": "tsc --build",
 		"env:start": "node ./tools/local-env/scripts/start.js && node ./tools/local-env/scripts/docker.js run -T --rm php composer update -W",
 		"env:stop": "node ./tools/local-env/scripts/docker.js down",

src/wp-content/themes/twentytwenty/assets/css/font-inter.css

@@ -8,15 +8,15 @@ Inter variable font. Usage:
 
 @font-face {
 	font-family: "Inter var";
-	font-weight: 100 900; /* stylelint-disable-line font-weight-notation */
+	font-weight: 100 900;
 	font-style: normal;
 	font-display: swap;
 	src: url(../fonts/inter/Inter-upright-var.woff2) format("woff2");
 }
 
 @font-face {
 	font-family: "Inter var";
-	font-weight: 100 900; /* stylelint-disable-line font-weight-notation */
+	font-weight: 100 900;
 	font-style: italic;
 	font-display: swap;
 	src: url(../fonts/inter/Inter-italic-var.woff2) format("woff2");

src/wp-content/themes/twentytwenty/package.json

@@ -28,8 +28,7 @@
 		"concurrently": "^9.2.1",
 		"postcss": "^8.5.6",
 		"postcss-cli": "^11.0.1",
-		"rtlcss": "^4.3.0",
-		"stylelint-a11y": "^1.2.3"
+		"rtlcss": "^4.3.0"
 	},
 	"browserslist": [
 		"extends @wordpress/browserslist-config"
@@ -56,7 +55,6 @@
 		"build:vendor-prefixes-style": "postcss -r --no-map style.css assets/css/editor-style-block.css assets/css/editor-style-classic.css",
 		"build:vendor-prefixes-esb": "postcss -r --no-map assets/css/editor-style-block.css ",
 		"build:vendor-prefixes-esc": "postcss -r --no-map assets/css/editor-style-classic.css",
-		"lint:css": "wp-scripts lint-style 'style.css' 'assets/**/*.css'",
 		"lint:js": "wp-scripts lint-js 'assets/**/*.js'",
 		"lint:pkg-json": "wp-scripts lint-pkg-json"
 	}

src/wp-content/themes/twentytwenty/style-rtl.css

@@ -257,15 +257,15 @@ Inter variable font. Usage:
 
 @font-face {
 	font-family: "Inter var";
-	font-weight: 100 900; /* stylelint-disable-line font-weight-notation */
+	font-weight: 100 900;
 	font-style: normal;
 	font-display: swap;
 	src: url(./assets/fonts/inter/Inter-upright-var.woff2) format("woff2");
 }
 
 @font-face {
 	font-family: "Inter var";
-	font-weight: 100 900; /* stylelint-disable-line font-weight-notation */
+	font-weight: 100 900;
 	font-style: italic;
 	font-display: swap;
 	src: url(./assets/fonts/inter/Inter-italic-var.woff2) format("woff2");

src/wp-content/themes/twentytwenty/style.css

@@ -257,15 +257,15 @@ Inter variable font. Usage:
 
 @font-face {
 	font-family: "Inter var";
-	font-weight: 100 900; /* stylelint-disable-line font-weight-notation */
+	font-weight: 100 900;
 	font-style: normal;
 	font-display: swap;
 	src: url(./assets/fonts/inter/Inter-upright-var.woff2) format("woff2");
 }
 
 @font-face {
 	font-family: "Inter var";
-	font-weight: 100 900; /* stylelint-disable-line font-weight-notation */
+	font-weight: 100 900;
 	font-style: italic;
 	font-display: swap;
 	src: url(./assets/fonts/inter/Inter-italic-var.woff2) format("woff2");