Stylelint: Add design token linting

.stylelintignore

@@ -2,3 +2,4 @@ build
 build-style
 node_modules
 packages/stylelint-config/test
+packages/theme/src/stylelint-plugins/test

packages/stylelint-config/index.js

@@ -3,6 +3,10 @@
 /** @type {import('stylelint').Config} */
 module.exports = {
 	extends: [ 'stylelint-config-recommended' ].map( require.resolve ),
+	plugins: [
+		'@wordpress/theme/stylelint-plugins/no-unknown-ds-tokens',
+		'@wordpress/theme/stylelint-plugins/no-setting-wpds-custom-properties',
+	],
 	rules: {
 		'at-rule-empty-line-before': [
 			'always',
@@ -68,6 +72,8 @@ module.exports = {
 		'selector-pseudo-element-colon-notation': 'double',
 		'selector-type-case': 'lower',
 		'value-keyword-case': 'lower',
+		'plugin-wpds/no-setting-wpds-custom-properties': true,
+		'plugin-wpds/no-unknown-ds-tokens': true,
 
 		/* Disable new rules from stylelint-config-recommended 7 > 14 */
 		'function-no-unknown': null,

packages/stylelint-config/package.json

@@ -42,6 +42,7 @@
 	},
 	"dependencies": {
 		"@stylistic/stylelint-plugin": "^3.0.1",
+		"@wordpress/theme": "file:../theme",
 		"stylelint-config-recommended": "^14.0.1",
 		"stylelint-config-recommended-scss": "^14.1.0"
 	},

packages/theme/package.json

@@ -40,6 +40,8 @@
 		},
 		"./design-tokens.css": "./src/prebuilt/css/design-tokens.css",
 		"./design-tokens.js": "./src/prebuilt/js/design-tokens.js",
+		"./stylelint-plugins/no-unknown-ds-tokens": "./src/stylelint-plugins/no-unknown-ds-tokens.mjs",
+		"./stylelint-plugins/no-setting-wpds-custom-properties": "./src/stylelint-plugins/no-setting-wpds-custom-properties.mjs",
 		"./package.json": "./package.json"
 	},
 	"react-native": "src/index",
@@ -64,7 +66,8 @@
 	},
 	"peerDependencies": {
 		"react": "^18.0.0",
-		"react-dom": "^18.0.0"
+		"react-dom": "^18.0.0",
+		"stylelint": "^16.8.2"
 	},
 	"publishConfig": {
 		"access": "public"

packages/theme/src/stylelint-plugins/no-setting-wpds-custom-properties.mjs

@@ -0,0 +1,45 @@
+import stylelint from 'stylelint';
+
+const {
+	createPlugin,
+	utils: { report, ruleMessages, validateOptions },
+} = stylelint;
+
+const ruleName = 'plugin-wpds/no-setting-wpds-custom-properties';
+
+const messages = ruleMessages( ruleName, {
+	rejected: () =>
+		`Do not set CSS custom properties using the Design System tokens namespace (i.e. beginning with --wpds-*).`,
+} );
+
+/** @type {import('stylelint').Rule} */
+const ruleFunction = ( primary ) => {
+	return ( root, result ) => {
+		const validOptions = validateOptions( result, ruleName, {
+			actual: primary,
+			possible: [ true ],
+		} );
+
+		if ( ! validOptions ) {
+			return;
+		}
+
+		root.walkDecls( ( ruleNode ) => {
+			const { prop } = ruleNode;
+			if ( prop.startsWith( '--wpds' ) ) {
+				report( {
+					message: messages.rejected( prop ),
+					node: ruleNode,
+					result,
+					ruleName,
+				} );
+			}
+		} );
+	};
+};
+
+ruleFunction.ruleName = ruleName;
+ruleFunction.messages = messages;
+
+/** @type {import('stylelint').Plugin} */
+export default createPlugin( ruleName, ruleFunction );

packages/theme/src/stylelint-plugins/no-unknown-ds-tokens.mjs

@@ -0,0 +1,101 @@
+import stylelint from 'stylelint';
+import tokenList from '../prebuilt/js/design-tokens.js';
+
+const DS_TOKEN_PREFIX = 'wpds-';
+
+/**
+ * Extracts all unique CSS custom properties (variables) from a given CSS value string,
+ * including those in fallback positions, optionally filtering by a specific prefix.
+ *
+ * @param {string} value       - The CSS value string to search for variables.
+ * @param {string} [prefix=''] - Optional prefix to filter variables (e.g., 'wpds-').
+ * @return {Set<string>} A Set of unique matched CSS variable names (e.g., Set { '--wpds-token' }).
+ *
+ * @example
+ * extractCSSVariables(
+ *   'border: 1px solid var(--wpds-border-color, var(--wpds-border-fallback)); ' +
+ *   'color: var(--wpds-color-fg, black); ' +
+ *   'background: var(--unrelated-bg);',
+ *   'wpds'
+ * );
+ * // → Set { '--wpds-border-color', '--wpds-border-fallback', '--wpds-color-fg' }
+ */
+function extractCSSVariables( value, prefix = '' ) {
+	const regex = /--[\w-]+/g;
+	const variables = new Set();
+
+	let match;
+	while ( ( match = regex.exec( value ) ) !== null ) {
+		const variableName = match[ 0 ];
+		if ( variableName.startsWith( `--${ prefix }` ) ) {
+			variables.add( variableName );
+		}
+	}
+
+	return variables;
+}
+
+const knownTokens = new Set( tokenList );
+const wpdsTokensRegex = new RegExp( `[^\\w]--${ DS_TOKEN_PREFIX }`, 'i' );
+
+const {
+	createPlugin,
+	utils: { report, ruleMessages, validateOptions },
+} = stylelint;
+
+const ruleName = 'plugin-wpds/no-unknown-ds-tokens';
+
+const messages = ruleMessages( ruleName, {
+	rejected: ( tokenNames ) =>
+		`The following CSS variables are not valid (public) Design System tokens: ${ tokenNames }`,
+} );
+
+/** @type {import('stylelint').Rule} */
+const ruleFunction = ( primary ) => {
+	return ( root, result ) => {
+		const validOptions = validateOptions( result, ruleName, {
+			actual: primary,
+			possible: [ true ],
+		} );
+
+		if ( ! validOptions ) {
+			return;
+		}
+
+		root.walkDecls( ( ruleNode ) => {
+			const { value } = ruleNode;
+			// Early match for WPDS tokens to avoid unnecessary processing.
+			if ( wpdsTokensRegex.test( value ) ) {
+				const usedTokens = extractCSSVariables(
+					value,
+					DS_TOKEN_PREFIX
+				);
+				const unknownTokens = new Set(
+					[ ...usedTokens ].filter(
+						( token ) => ! knownTokens.has( token )
+					)
+				);
+
+				if ( unknownTokens.size > 0 ) {
+					report( {
+						message: messages.rejected(
+							Array.from( unknownTokens )
+								.map( ( token ) => `'${ token }'` )
+								.join( ', ' )
+						),
+						node: ruleNode,
+						result,
+						ruleName,
+					} );
+				}
+			}
+		} );
+	};
+};
+
+ruleFunction.ruleName = ruleName;
+ruleFunction.messages = messages;
+
+/** @type {import('stylelint').Plugin} */
+export default createPlugin( ruleName, ruleFunction );
+

packages/theme/src/stylelint-plugins/test/.stylelintrc.json

@@ -0,0 +1,10 @@
+{
+	"plugins": [
+		"../no-unknown-ds-tokens.mjs",
+		"../no-setting-wpds-custom-properties.mjs"
+	],
+	"rules": {
+		"plugin-wpds/no-unknown-ds-tokens": true,
+		"plugin-wpds/no-setting-wpds-custom-properties": true
+	}
+}

packages/theme/src/stylelint-plugins/test/__snapshots__/no-setting-wpds-custom-properties.js.snap

@@ -0,0 +1,24 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`flags warnings with invalid wpds custom properties css snapshot matches warnings 1`] = `
+[
+  {
+    "column": 2,
+    "endColumn": 31,
+    "endLine": 3,
+    "line": 3,
+    "rule": "plugin-wpds/no-setting-wpds-custom-properties",
+    "severity": "error",
+    "text": "Do not set CSS custom properties using the Design System tokens namespace (i.e. beginning with --wpds-*). (plugin-wpds/no-setting-wpds-custom-properties)",
+  },
+  {
+    "column": 2,
+    "endColumn": 27,
+    "endLine": 7,
+    "line": 7,
+    "rule": "plugin-wpds/no-setting-wpds-custom-properties",
+    "severity": "error",
+    "text": "Do not set CSS custom properties using the Design System tokens namespace (i.e. beginning with --wpds-*). (plugin-wpds/no-setting-wpds-custom-properties)",
+  },
+]
+`;

packages/theme/src/stylelint-plugins/test/__snapshots__/no-unknown-ds-tokens.js.snap

@@ -0,0 +1,24 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`flags warnings with invalid wpds tokens css snapshot matches warnings 1`] = `
+[
+  {
+    "column": 2,
+    "endColumn": 39,
+    "endLine": 3,
+    "line": 3,
+    "rule": "plugin-wpds/no-unknown-ds-tokens",
+    "severity": "error",
+    "text": "The following CSS variables are not valid (public) Design System tokens: '--wpds-nonexistent-token' (plugin-wpds/no-unknown-ds-tokens)",
+  },
+  {
+    "column": 2,
+    "endColumn": 40,
+    "endLine": 7,
+    "line": 7,
+    "rule": "plugin-wpds/no-unknown-ds-tokens",
+    "severity": "error",
+    "text": "The following CSS variables are not valid (public) Design System tokens: '--wpds-made-up-color' (plugin-wpds/no-unknown-ds-tokens)",
+  },
+]
+`;

packages/theme/src/stylelint-plugins/test/fixtures/no-setting-wpds-custom-properties-invalid.css

@@ -0,0 +1,9 @@
+/* Invalid: Setting wpds custom properties is not allowed */
+:root {
+	--wpds-custom-override: #f00;
+}
+
+.example {
+	--wpds-local-token: #00f;
+}
+

packages/theme/src/stylelint-plugins/test/fixtures/no-setting-wpds-custom-properties-valid.css

@@ -0,0 +1,12 @@
+/* Valid: Using wpds tokens as values is allowed */
+.example {
+	color: var(--wpds-color-fg-content-neutral);
+	background-color: var(--wpds-color-bg-surface-neutral);
+}
+
+/* Valid: Setting non-wpds custom properties is allowed */
+:root {
+	--my-custom-color: #f00;
+	--another-property: 10px;
+}
+

packages/theme/src/stylelint-plugins/test/fixtures/no-unknown-ds-tokens-invalid.css

@@ -0,0 +1,9 @@
+/* Invalid: Using unknown design system tokens */
+.example {
+	color: var(--wpds-nonexistent-token);
+}
+
+.another {
+	background: var(--wpds-made-up-color);
+}
+

packages/theme/src/stylelint-plugins/test/fixtures/no-unknown-ds-tokens-valid.css

@@ -0,0 +1,19 @@
+/* Valid: Using known design system tokens */
+.example {
+	background-color: var(--wpds-color-bg-surface-neutral);
+	color: var(--wpds-color-fg-content-neutral);
+	border-radius: var(--wpds-border-radius-surface-sm);
+	padding: var(--wpds-dimension-padding-surface-md);
+}
+
+/* Valid: Using tokens with fallbacks */
+.with-fallback {
+	color: var(--wpds-color-fg-content-neutral, inherit);
+}
+
+/* Valid: Non-wpds custom properties are ignored */
+.other-vars {
+	color: var(--my-custom-color);
+	background: var(--some-other-var);
+}
+

packages/theme/src/stylelint-plugins/test/no-setting-wpds-custom-properties.js

@@ -0,0 +1,48 @@
+const utils = require( './utils' );
+const getStylelintResult = utils.getStylelintResult;
+
+describe( 'flags no warnings with valid wpds custom properties css', () => {
+	let result;
+
+	beforeEach( () => {
+		result = getStylelintResult(
+			'./fixtures/no-setting-wpds-custom-properties-valid.css'
+		);
+	} );
+
+	it( 'did not error', () => {
+		return result.then( ( data ) => expect( data.errored ).toBeFalsy() );
+	} );
+
+	it( 'flags no warnings', () => {
+		return result.then( ( data ) =>
+			expect( data.results[ 0 ].warnings ).toHaveLength( 0 )
+		);
+	} );
+} );
+
+describe( 'flags warnings with invalid wpds custom properties css', () => {
+	let result;
+
+	beforeEach( () => {
+		result = getStylelintResult(
+			'./fixtures/no-setting-wpds-custom-properties-invalid.css'
+		);
+	} );
+
+	it( 'did error', () => {
+		return result.then( ( data ) => expect( data.errored ).toBeTruthy() );
+	} );
+
+	it( 'flags correct number of warnings', () => {
+		return result.then( ( data ) =>
+			expect( data.results[ 0 ].warnings ).toHaveLength( 2 )
+		);
+	} );
+
+	it( 'snapshot matches warnings', () => {
+		return result.then( ( data ) =>
+			expect( data.results[ 0 ].warnings ).toMatchSnapshot()
+		);
+	} );
+} );