ESLint: Add no-ds-tokens rule (#75872)

* Add no-ds-tokens ESLint rule

* Enable no-ds-tokens rule for packages/components

* Fix regex to also match tokens at start of string

* Add changelog

* Add comment to eslintrc

* Add word-boundary valid test case

Co-authored-by: mirka <0mirka00@git.wordpress.org>
Co-authored-by: ciampo <mciampini@git.wordpress.org>

Author: mirka

.eslintrc.js

@@ -436,6 +436,16 @@ module.exports = {
 			plugins: [ 'ssr-friendly' ],
 			extends: [ 'plugin:ssr-friendly/recommended' ],
 		},
+		{
+			files: [ 'packages/components/src/**' ],
+			excludedFiles: [ 'packages/components/src/**/@(test|stories)/**' ],
+			rules: {
+				// Disallow usage of Design System token CSS custom properties (`--wpds-*`)
+				// because the fallback injection in the build process is not compatible with Emotion files.
+				// Can be removed when there are no more Emotion files in the package.
+				'@wordpress/no-ds-tokens': 'error',
+			},
+		},
 		{
 			files: [
 				'packages/block-editor/src/**',

packages/eslint-plugin/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+### New Features
+
+-   Added [`no-ds-tokens`](https://github.com/WordPress/gutenberg/blob/HEAD/packages/eslint-plugin/docs/rules/no-ds-tokens.md) rule to disallow usage of Design System token CSS custom properties (`--wpds-*`).
+
 ## 24.2.0 (2026-02-18)
 
 ## 24.1.0 (2026-01-29)

packages/eslint-plugin/docs/rules/no-ds-tokens.md

@@ -0,0 +1,35 @@
+# Disallow usage of Design System tokens (no-ds-tokens)
+
+Disallows any usage of Design System token CSS custom properties (beginning with `--wpds-`) in string literals and template literals.
+
+This is useful in contexts where Design System tokens should not be referenced directly. It is not included in any preset and must be explicitly enabled.
+
+## Rule details
+
+Examples of **incorrect** code for this rule:
+
+```js
+const style = 'color: var(--wpds-color-fg-content-neutral)';
+```
+
+```js
+const style = `border: 1px solid var(--wpds-border-color)`;
+```
+
+```jsx
+<div style={ { color: 'var(--wpds-color-fg-content-neutral)' } } />
+```
+
+Examples of **correct** code for this rule:
+
+```js
+const style = 'color: var(--my-custom-prop)';
+```
+
+```js
+const style = `border: 1px solid var(--other-prefix-token)`;
+```
+
+```jsx
+<div style={ { color: 'blue' } } />
+```

packages/eslint-plugin/rules/__tests__/no-ds-tokens.js

@@ -0,0 +1,81 @@
+import { RuleTester } from 'eslint';
+import rule from '../no-ds-tokens';
+
+const ruleTester = new RuleTester( {
+	parserOptions: {
+		ecmaVersion: 6,
+		ecmaFeatures: {
+			jsx: true,
+		},
+	},
+} );
+
+ruleTester.run( 'no-ds-tokens', rule, {
+	valid: [
+		{
+			code: `const style = 'color: var(--my-custom-prop)';`,
+		},
+		{
+			code: `const style = 'color: blue';`,
+		},
+		{
+			code: 'const style = `border: 1px solid var(--other-prefix-token)`;',
+		},
+		{
+			code: `const name = 'something--wpds-color';`,
+		},
+		{
+			code: `<div style={ { color: 'var(--my-custom-prop)' } } />`,
+		},
+	],
+	invalid: [
+		{
+			code: `const style = 'color: var(--wpds-color-fg-content-neutral)';`,
+			errors: [
+				{
+					messageId: 'disallowed',
+				},
+			],
+		},
+		{
+			code: 'const style = `color: var(--wpds-color-fg-content-neutral)`;',
+			errors: [
+				{
+					messageId: 'disallowed',
+				},
+			],
+		},
+		{
+			code: `<div style={ { color: 'var(--wpds-color-fg-content-neutral)' } } />`,
+			errors: [
+				{
+					messageId: 'disallowed',
+				},
+			],
+		},
+		{
+			code: 'const style = `border: 1px solid var(--wpds-border-color, var(--wpds-border-fallback))`;',
+			errors: [
+				{
+					messageId: 'disallowed',
+				},
+			],
+		},
+		{
+			code: `const token = '--wpds-color-fg';`,
+			errors: [
+				{
+					messageId: 'disallowed',
+				},
+			],
+		},
+		{
+			code: 'const style = `--wpds-color-fg: red`;',
+			errors: [
+				{
+					messageId: 'disallowed',
+				},
+			],
+		},
+	],
+} );

packages/eslint-plugin/rules/no-ds-tokens.js

@@ -0,0 +1,29 @@
+const DS_TOKEN_PREFIX = 'wpds-';
+
+const wpdsTokensRegex = new RegExp( `(?:^|[^\\w])--${ DS_TOKEN_PREFIX }`, 'i' );
+
+module.exports = /** @type {import('eslint').Rule.RuleModule} */ ( {
+	meta: {
+		type: 'problem',
+		docs: {
+			description: 'Disallow any usage of --wpds-* CSS custom properties',
+		},
+		schema: [],
+		messages: {
+			disallowed:
+				'Design System tokens (--wpds-*) should not be used in this context.',
+		},
+	},
+	create( context ) {
+		const selector = `:matches(Literal[value=${ wpdsTokensRegex }], TemplateLiteral TemplateElement[value.raw=${ wpdsTokensRegex }])`;
+		return {
+			/** @param {import('estree').Literal | import('estree').TemplateElement} node */
+			[ selector ]( node ) {
+				context.report( {
+					node,
+					messageId: 'disallowed',
+				} );
+			},
+		};
+	},
+} );