Add stylelint CSS linting

.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

.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

@@ -1775,8 +1775,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,10 @@
 		"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",
 		"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",

tools/stylelint/check-warning-thresholds.js

@@ -0,0 +1,35 @@
+/**
+ * CLI entry point for checking or updating Stylelint warning-level rule thresholds.
+ * See tools/stylelint/lib/warning-thresholds.js for the underlying logic.
+ */
+
+const {
+	lintCss,
+	getWarningLevelRules,
+	countWarnings,
+	checkThresholds,
+	updateThresholds,
+} = require( './lib/warning-thresholds' );
+
+const shouldUpdate = process.argv.includes( '--update' );
+
+async function main() {
+	console.log( 'Checking Stylelint warnings thresholds...' );
+
+	const warningLevelRules = getWarningLevelRules();
+	const { results } = await lintCss();
+	const actualCounts = countWarnings( results, warningLevelRules );
+
+	const success = shouldUpdate
+		? updateThresholds( actualCounts )
+		: checkThresholds( actualCounts, warningLevelRules );
+
+	if ( ! success ) {
+		process.exitCode = 1;
+	}
+}
+
+main().catch( ( error ) => {
+	console.error( error );
+	process.exitCode = 1;
+} );