@wordpress/theme-build-tools 0.0.0-stage → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (25) hide show
  1. package/LICENSE.md +788 -0
  2. package/README.md +133 -2
  3. package/build-types/esbuild-plugins/esbuild-ds-token-fallbacks.d.mts +12 -0
  4. package/build-types/js-plugins/transform-ds-token-fallbacks.d.mts +14 -0
  5. package/build-types/lib/theme-tokens.d.mts +28 -0
  6. package/build-types/lightningcss-plugins/lightningcss-ds-token-fallbacks.d.mts +13 -0
  7. package/build-types/postcss-plugins/add-fallback-to-var.d.mts +38 -0
  8. package/build-types/postcss-plugins/ds-token-fallbacks.d.mts +41 -0
  9. package/build-types/postcss-plugins/postcss-ds-token-fallbacks.d.mts +4 -0
  10. package/build-types/stylelint-plugins/no-setting-wpds-custom-properties.d.mts +5 -0
  11. package/build-types/stylelint-plugins/no-token-fallback-values.d.mts +5 -0
  12. package/build-types/stylelint-plugins/no-unknown-ds-tokens.d.mts +5 -0
  13. package/build-types/vite-plugins/vite-ds-token-fallbacks.d.mts +12 -0
  14. package/esbuild-plugins/esbuild-ds-token-fallbacks.mjs +130 -0
  15. package/js-plugins/transform-ds-token-fallbacks.mjs +211 -0
  16. package/lib/theme-tokens.mjs +58 -0
  17. package/lightningcss-plugins/lightningcss-ds-token-fallbacks.mjs +89 -0
  18. package/package.json +125 -5
  19. package/postcss-plugins/add-fallback-to-var.mjs +65 -0
  20. package/postcss-plugins/ds-token-fallbacks.mjs +53 -0
  21. package/postcss-plugins/postcss-ds-token-fallbacks.mjs +17 -0
  22. package/stylelint-plugins/no-setting-wpds-custom-properties.mjs +45 -0
  23. package/stylelint-plugins/no-token-fallback-values.mjs +55 -0
  24. package/stylelint-plugins/no-unknown-ds-tokens.mjs +102 -0
  25. package/vite-plugins/vite-ds-token-fallbacks.mjs +33 -0
@@ -0,0 +1,58 @@
1
+ /**
2
+ * Token data from the installed `@wordpress/theme`.
3
+ *
4
+ * The plugins do nothing when `@wordpress/theme` cannot be loaded.
5
+ */
6
+
7
+ import { createRequire } from 'node:module';
8
+
9
+ /**
10
+ * @typedef {Object} DesignTokensModule
11
+ * @property {Record<string, { fallback: string }>} tokens Token metadata, keyed by CSS custom property name.
12
+ */
13
+
14
+ /**
15
+ * Load `@wordpress/theme/design-tokens.js`, or return `undefined` when it
16
+ * cannot be loaded.
17
+ *
18
+ * This loads the module synchronously, without a top-level `await`, so that
19
+ * CommonJS consumers can still `require()` the plugins.
20
+ *
21
+ * @return {DesignTokensModule | undefined} The module, or `undefined`.
22
+ */
23
+ function loadDesignTokens() {
24
+ try {
25
+ return createRequire( import.meta.url )(
26
+ '@wordpress/theme/design-tokens.js'
27
+ );
28
+ } catch {
29
+ return undefined;
30
+ }
31
+ }
32
+
33
+ const designTokens = loadDesignTokens();
34
+
35
+ /**
36
+ * Map of design token names to their generated fallback values, or
37
+ * `undefined` when `@wordpress/theme` is unavailable.
38
+ *
39
+ * @type {Record<string, string> | undefined}
40
+ */
41
+ export const tokenFallbacks = designTokens
42
+ ? Object.fromEntries(
43
+ Object.entries( designTokens.tokens ).map( ( [ name, token ] ) => [
44
+ name,
45
+ token.fallback,
46
+ ] )
47
+ )
48
+ : undefined;
49
+
50
+ /**
51
+ * List of design token names, or `undefined` when `@wordpress/theme` is
52
+ * unavailable.
53
+ *
54
+ * @type {string[] | undefined}
55
+ */
56
+ export const tokenList = designTokens
57
+ ? Object.keys( designTokens.tokens )
58
+ : undefined;
@@ -0,0 +1,89 @@
1
+ import { transform } from 'lightningcss';
2
+ import { tokenFallbacks } from '../lib/theme-tokens.mjs';
3
+ import { getTokenFallback } from '../postcss-plugins/ds-token-fallbacks.mjs';
4
+
5
+ /** @type {Map<string, import('lightningcss').TokenOrValue[]>} */
6
+ const parsedFallbacks = new Map();
7
+
8
+ // Raw replacements discard CSS Modules reference metadata. Parse the generated
9
+ // fallbacks once so the visitor can combine them with each original reference.
10
+ if ( tokenFallbacks ) {
11
+ const fallbacks = tokenFallbacks;
12
+ transform( {
13
+ filename: 'design-token-fallbacks.css',
14
+ code: Buffer.from(
15
+ `:root {\n${ Object.entries( fallbacks )
16
+ .map(
17
+ ( [ tokenName, fallback ] ) =>
18
+ `\t${ tokenName }: var(${ tokenName }, ${ fallback });`
19
+ )
20
+ .join( '\n' ) }\n}`
21
+ ),
22
+ visitor: {
23
+ Variable( variable ) {
24
+ if (
25
+ variable.fallback &&
26
+ Object.hasOwn( fallbacks, variable.name.ident )
27
+ ) {
28
+ // Generated fallbacks reference global custom properties.
29
+ // Keep CSS Modules from scoping them to the consumer's file.
30
+ const fallback = JSON.parse(
31
+ JSON.stringify( variable.fallback, ( key, value ) =>
32
+ key === 'from' && value === null
33
+ ? { type: 'global' }
34
+ : value
35
+ )
36
+ );
37
+ parsedFallbacks.set( variable.name.ident, fallback );
38
+ }
39
+ },
40
+ },
41
+ } );
42
+ }
43
+
44
+ /**
45
+ * Lightning CSS visitor that injects design-system token fallbacks into CSS.
46
+ *
47
+ * Replaces bare `var(--wpds-*)` references with `var(--wpds-*, <fallback>)`.
48
+ *
49
+ * Existing fallbacks are left untouched. Unknown tokens throw. Does nothing
50
+ * when `@wordpress/theme` is not installed.
51
+ *
52
+ * @type {import('lightningcss').Visitor<never>}
53
+ */
54
+ const plugin = {
55
+ /** @param {import('lightningcss').Variable} variable */
56
+ Variable( variable ) {
57
+ // Leave existing fallbacks alone, including the valid empty fallback
58
+ // form `var(--token,)` which Lightning CSS parses as `fallback: []`.
59
+ if ( variable.fallback !== null || ! tokenFallbacks ) {
60
+ return;
61
+ }
62
+
63
+ const tokenName = variable.name.ident;
64
+ if ( ! tokenName.startsWith( '--wpds-' ) ) {
65
+ return;
66
+ }
67
+
68
+ const fallback = parsedFallbacks.get( tokenName );
69
+ if ( ! fallback ) {
70
+ getTokenFallback( tokenName );
71
+ throw new Error(
72
+ `No parsed fallback for design token: ${ tokenName }. ` +
73
+ 'Check that its generated fallback can be parsed by Lightning CSS.'
74
+ );
75
+ }
76
+
77
+ return {
78
+ type: 'var',
79
+ value: {
80
+ name: variable.name.from
81
+ ? variable.name
82
+ : { ident: variable.name.ident },
83
+ fallback: structuredClone( fallback ),
84
+ },
85
+ };
86
+ },
87
+ };
88
+
89
+ export default plugin;
package/package.json CHANGED
@@ -1,6 +1,126 @@
1
1
  {
2
- "name": "@wordpress/theme-build-tools",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
2
+ "name": "@wordpress/theme-build-tools",
3
+ "version": "1.0.0",
4
+ "description": "Build plugins and Stylelint rules for the WordPress Design System design tokens.",
5
+ "author": "The WordPress Contributors",
6
+ "license": "GPL-2.0-or-later",
7
+ "keywords": [
8
+ "wordpress",
9
+ "gutenberg",
10
+ "design-system",
11
+ "design-tokens",
12
+ "stylelint",
13
+ "postcss",
14
+ "lightningcss",
15
+ "esbuild",
16
+ "vite"
17
+ ],
18
+ "homepage": "https://github.com/WordPress/gutenberg/tree/HEAD/packages/theme-build-tools/README.md",
19
+ "repository": {
20
+ "type": "git",
21
+ "url": "git+https://github.com/WordPress/gutenberg.git",
22
+ "directory": "packages/theme-build-tools"
23
+ },
24
+ "bugs": {
25
+ "url": "https://github.com/WordPress/gutenberg/issues"
26
+ },
27
+ "engines": {
28
+ "node": ">=22.13.0"
29
+ },
30
+ "files": [
31
+ "build-types",
32
+ "*-plugins/**",
33
+ "lib/**",
34
+ "!build-types/**/*.d.mts.map",
35
+ "!build-types/**/*.d.ts.map",
36
+ "!**/test/**"
37
+ ],
38
+ "type": "module",
39
+ "exports": {
40
+ "./postcss-plugins/postcss-ds-token-fallbacks": {
41
+ "types": "./build-types/postcss-plugins/postcss-ds-token-fallbacks.d.mts",
42
+ "default": "./postcss-plugins/postcss-ds-token-fallbacks.mjs"
43
+ },
44
+ "./lightningcss-plugins/lightningcss-ds-token-fallbacks": {
45
+ "types": "./build-types/lightningcss-plugins/lightningcss-ds-token-fallbacks.d.mts",
46
+ "default": "./lightningcss-plugins/lightningcss-ds-token-fallbacks.mjs"
47
+ },
48
+ "./esbuild-plugins/esbuild-ds-token-fallbacks": {
49
+ "types": "./build-types/esbuild-plugins/esbuild-ds-token-fallbacks.d.mts",
50
+ "default": "./esbuild-plugins/esbuild-ds-token-fallbacks.mjs"
51
+ },
52
+ "./vite-plugins/vite-ds-token-fallbacks": {
53
+ "types": "./build-types/vite-plugins/vite-ds-token-fallbacks.d.mts",
54
+ "default": "./vite-plugins/vite-ds-token-fallbacks.mjs"
55
+ },
56
+ "./stylelint-plugins/no-unknown-ds-tokens": {
57
+ "types": "./build-types/stylelint-plugins/no-unknown-ds-tokens.d.mts",
58
+ "default": "./stylelint-plugins/no-unknown-ds-tokens.mjs"
59
+ },
60
+ "./stylelint-plugins/no-setting-wpds-custom-properties": {
61
+ "types": "./build-types/stylelint-plugins/no-setting-wpds-custom-properties.d.mts",
62
+ "default": "./stylelint-plugins/no-setting-wpds-custom-properties.mjs"
63
+ },
64
+ "./stylelint-plugins/no-token-fallback-values": {
65
+ "types": "./build-types/stylelint-plugins/no-token-fallback-values.d.mts",
66
+ "default": "./stylelint-plugins/no-token-fallback-values.mjs"
67
+ },
68
+ "./package.json": "./package.json"
69
+ },
70
+ "wpScript": false,
71
+ "sideEffects": false,
72
+ "dependencies": {
73
+ "@babel/parser": "^7.28.6",
74
+ "@babel/types": "^7.29.7",
75
+ "@jridgewell/remapping": "^2.3.5",
76
+ "@jridgewell/trace-mapping": "^0.3.31",
77
+ "magic-string": "^0.30.21"
78
+ },
79
+ "devDependencies": {
80
+ "@types/node": "^24.13.3",
81
+ "@wordpress/theme": "^4.0.0",
82
+ "@wordpress/validation-tools": "file:../../tools/validation",
83
+ "esbuild": "^0.27.2",
84
+ "lightningcss": "^1.33.0",
85
+ "postcss": "^8.4.38",
86
+ "source-map": "^0.6.1",
87
+ "stylelint": "^17.14.1",
88
+ "vite": "^8.3.5",
89
+ "vitest": "^5.0.5"
90
+ },
91
+ "peerDependencies": {
92
+ "@wordpress/theme": "^3.0.0 || ^4.0.0",
93
+ "esbuild": ">=0.27.2 <1.0.0",
94
+ "lightningcss": ">=1.33.0 <2.0.0",
95
+ "postcss": "^8.0.0",
96
+ "stylelint": "^16 || ^17",
97
+ "vite": "^7 || ^8"
98
+ },
99
+ "peerDependenciesMeta": {
100
+ "@wordpress/theme": {
101
+ "optional": true
102
+ },
103
+ "esbuild": {
104
+ "optional": true
105
+ },
106
+ "lightningcss": {
107
+ "optional": true
108
+ },
109
+ "postcss": {
110
+ "optional": true
111
+ },
112
+ "stylelint": {
113
+ "optional": true
114
+ },
115
+ "vite": {
116
+ "optional": true
117
+ }
118
+ },
119
+ "publishConfig": {
120
+ "access": "public"
121
+ },
122
+ "scripts": {
123
+ "lint:package-contents": "wp-validate-package-contents . --disallow-path test"
124
+ },
125
+ "gitHead": "9b70363b9f93cff0583a1f3153738d383cf5a49e"
126
+ }
@@ -0,0 +1,65 @@
1
+ /**
2
+ * Replace bare `var(--wpds-*)` references in a CSS value string with
3
+ * `var(--wpds-*, <fallback>)` using the provided token fallback map.
4
+ *
5
+ * Existing fallbacks (i.e. `var()` calls that already contain a comma)
6
+ * are left untouched, making the function safe to run multiple times
7
+ * (idempotent).
8
+ *
9
+ * This is the generic, reusable implementation that takes the fallback
10
+ * map as an argument. For the variant prebound with the package's
11
+ * generated token fallback map, see `./ds-token-fallbacks.mjs`.
12
+ *
13
+ * @param {string} cssValue A CSS declaration value.
14
+ * @param {Record<string, string>} tokenFallbacks Map of CSS variable names to their fallback expressions.
15
+ * @param {Object} [options] Options.
16
+ * @param {boolean} [options.escapeQuotes] When true, escape `"` and `'` in fallback values.
17
+ * Use this when the input is JS/TS source so that
18
+ * injected quotes don't break string literals. JS
19
+ * will unescape them at parse time, so the browser's
20
+ * CSS engine still sees the correct value.
21
+ * @return {string} The value with fallbacks injected.
22
+ */
23
+ export function addFallbackToVar(
24
+ cssValue,
25
+ tokenFallbacks,
26
+ { escapeQuotes = false } = {}
27
+ ) {
28
+ return cssValue.replace(
29
+ /var\(\s*(--wpds-[\w-]+)\s*\)/g,
30
+ ( match, tokenName ) => {
31
+ const fallback = getTokenFallback( tokenName, tokenFallbacks, {
32
+ escapeQuotes,
33
+ } );
34
+ return `var(${ tokenName }, ${ fallback })`;
35
+ }
36
+ );
37
+ }
38
+
39
+ /**
40
+ * Get the fallback for a design token.
41
+ *
42
+ * @param {string} tokenName CSS variable name.
43
+ * @param {Record<string, string>} tokenFallbacks Map of CSS variable names to fallback expressions.
44
+ * @param {Object} [options] Options.
45
+ * @param {boolean} [options.escapeQuotes] Whether to escape quotes in the fallback.
46
+ * @return {string} The token fallback.
47
+ */
48
+ export function getTokenFallback(
49
+ tokenName,
50
+ tokenFallbacks,
51
+ { escapeQuotes = false } = {}
52
+ ) {
53
+ let fallback = tokenFallbacks[ tokenName ];
54
+ if ( fallback === undefined ) {
55
+ throw new Error(
56
+ `Unknown design token: ${ tokenName }. ` +
57
+ 'This token is not in the design system. ' +
58
+ 'If this token was recently renamed, update all references to use the new name.'
59
+ );
60
+ }
61
+ if ( escapeQuotes ) {
62
+ fallback = fallback.replaceAll( '"', '\\"' ).replaceAll( "'", "\\'" );
63
+ }
64
+ return fallback;
65
+ }
@@ -0,0 +1,53 @@
1
+ import { tokenFallbacks } from '../lib/theme-tokens.mjs';
2
+ import {
3
+ addFallbackToVar as _addFallbackToVar,
4
+ getTokenFallback as _getTokenFallback,
5
+ } from './add-fallback-to-var.mjs';
6
+
7
+ /**
8
+ * Replace bare `var(--wpds-*)` references in a CSS value string with
9
+ * `var(--wpds-*, <fallback>)` using the package's generated token
10
+ * fallback map.
11
+ *
12
+ * Existing fallbacks (i.e. var() calls that already contain a comma) are
13
+ * left untouched, making the function safe to run multiple times.
14
+ *
15
+ * This is a thin wrapper around the generic `addFallbackToVar` helper in
16
+ * `./add-fallback-to-var.mjs`, prebound to the package's token fallback
17
+ * map. Update the regex/replacement logic in that file, not here.
18
+ *
19
+ * Returns the value unchanged when `@wordpress/theme` is not installed.
20
+ *
21
+ * @param {string} cssValue A CSS declaration value.
22
+ * @param {Object} [options] Options.
23
+ * @param {boolean} [options.escapeQuotes] When true, escape `"` and `'` in
24
+ * fallback values. Use this when the
25
+ * input is JS/TS source so that
26
+ * injected quotes don't break string
27
+ * literals. JS will unescape them at
28
+ * parse time, so the browser's CSS
29
+ * engine still sees the correct value.
30
+ * @return {string} The value with fallbacks injected.
31
+ */
32
+ export function addFallbackToVar( cssValue, options ) {
33
+ if ( ! tokenFallbacks ) {
34
+ return cssValue;
35
+ }
36
+ return _addFallbackToVar( cssValue, tokenFallbacks, options );
37
+ }
38
+
39
+ /**
40
+ * Whether design token fallbacks are available, i.e. whether
41
+ * `@wordpress/theme` is installed. The plugins do nothing without them.
42
+ */
43
+ export const hasTokenFallbacks = tokenFallbacks !== undefined;
44
+
45
+ /**
46
+ * Get the generated fallback for a design token.
47
+ *
48
+ * @param {string} tokenName CSS variable name.
49
+ * @return {string} The token fallback.
50
+ */
51
+ export function getTokenFallback( tokenName ) {
52
+ return _getTokenFallback( tokenName, tokenFallbacks ?? {} );
53
+ }
@@ -0,0 +1,17 @@
1
+ import { addFallbackToVar } from './ds-token-fallbacks.mjs';
2
+
3
+ /** @type {import('postcss').PluginCreator<never>} */
4
+ const plugin = () => ( {
5
+ postcssPlugin: 'postcss-ds-token-fallbacks',
6
+ /** @param {import('postcss').Declaration} decl */
7
+ Declaration( decl ) {
8
+ const updated = addFallbackToVar( decl.value );
9
+ if ( updated !== decl.value ) {
10
+ decl.value = updated;
11
+ }
12
+ },
13
+ } );
14
+
15
+ plugin.postcss = true;
16
+
17
+ export default plugin;
@@ -0,0 +1,45 @@
1
+ import stylelint from 'stylelint';
2
+
3
+ const {
4
+ createPlugin,
5
+ utils: { report, ruleMessages, validateOptions },
6
+ } = stylelint;
7
+
8
+ const ruleName = 'plugin-wpds/no-setting-wpds-custom-properties';
9
+
10
+ const messages = ruleMessages( ruleName, {
11
+ rejected: () =>
12
+ `Do not set CSS custom properties using the Design System tokens namespace (i.e. beginning with --wpds-*).`,
13
+ } );
14
+
15
+ /** @type {import('stylelint').Rule} */
16
+ const ruleFunction = ( primary ) => {
17
+ return ( root, result ) => {
18
+ const validOptions = validateOptions( result, ruleName, {
19
+ actual: primary,
20
+ possible: [ true ],
21
+ } );
22
+
23
+ if ( ! validOptions ) {
24
+ return;
25
+ }
26
+
27
+ root.walkDecls( ( ruleNode ) => {
28
+ const { prop } = ruleNode;
29
+ if ( prop.startsWith( '--wpds-' ) ) {
30
+ report( {
31
+ message: messages.rejected(),
32
+ node: ruleNode,
33
+ result,
34
+ ruleName,
35
+ } );
36
+ }
37
+ } );
38
+ };
39
+ };
40
+
41
+ ruleFunction.ruleName = ruleName;
42
+ ruleFunction.messages = messages;
43
+
44
+ /** @type {import('stylelint').Plugin} */
45
+ export default createPlugin( ruleName, ruleFunction );
@@ -0,0 +1,55 @@
1
+ import stylelint from 'stylelint';
2
+
3
+ const {
4
+ createPlugin,
5
+ utils: { report, ruleMessages, validateOptions },
6
+ } = stylelint;
7
+
8
+ const ruleName = 'plugin-wpds/no-token-fallback-values';
9
+
10
+ /**
11
+ * Matches `var(--wpds-<name>,` — the comma signals a fallback value.
12
+ * Captures the token name (e.g. `--wpds-color-foreground-content-neutral`).
13
+ */
14
+ const varWithFallbackRegex = /var\(\s*(--wpds-[\w-]+)\s*,/g;
15
+
16
+ const messages = ruleMessages( ruleName, {
17
+ rejected: ( tokenName ) =>
18
+ `Do not add a fallback value for Design System token '${ tokenName }'. Fallbacks should be injected automatically at build time (see @wordpress/theme-build-tools package README).`,
19
+ } );
20
+
21
+ /** @type {import('stylelint').Rule} */
22
+ const ruleFunction = ( primary ) => {
23
+ return ( root, result ) => {
24
+ const validOptions = validateOptions( result, ruleName, {
25
+ actual: primary,
26
+ possible: [ true ],
27
+ } );
28
+
29
+ if ( ! validOptions ) {
30
+ return;
31
+ }
32
+
33
+ root.walkDecls( ( ruleNode ) => {
34
+ const { value } = ruleNode;
35
+
36
+ let match;
37
+ varWithFallbackRegex.lastIndex = 0;
38
+ while ( ( match = varWithFallbackRegex.exec( value ) ) !== null ) {
39
+ report( {
40
+ message: messages.rejected( match[ 1 ] ),
41
+ node: ruleNode,
42
+ word: match[ 0 ],
43
+ result,
44
+ ruleName,
45
+ } );
46
+ }
47
+ } );
48
+ };
49
+ };
50
+
51
+ ruleFunction.ruleName = ruleName;
52
+ ruleFunction.messages = messages;
53
+
54
+ /** @type {import('stylelint').Plugin} */
55
+ export default createPlugin( ruleName, ruleFunction );
@@ -0,0 +1,102 @@
1
+ import stylelint from 'stylelint';
2
+ import { tokenList } from '../lib/theme-tokens.mjs';
3
+
4
+ const DS_TOKEN_PREFIX = 'wpds-';
5
+
6
+ /**
7
+ * Extracts all unique CSS custom properties (variables) from a given CSS value string,
8
+ * including those in fallback positions, optionally filtering by a specific prefix.
9
+ *
10
+ * @param {string} value - The CSS value string to search for variables.
11
+ * @param {string} [prefix=''] - Optional prefix to filter variables (e.g., 'wpds-').
12
+ * @return {Set<string>} A Set of unique matched CSS variable names (e.g., Set { '--wpds-token' }).
13
+ *
14
+ * @example
15
+ * extractCSSVariables(
16
+ * 'border: 1px solid var(--wpds-border-radius-sm, var(--wpds-border-radius-md)); ' +
17
+ * 'color: var(--wpds-color-foreground-content-neutral, black); ' +
18
+ * 'background: var(--unrelated-bg);',
19
+ * 'wpds'
20
+ * );
21
+ * // → Set { '--wpds-border-radius-sm', '--wpds-border-radius-md', '--wpds-color-foreground-content-neutral' }
22
+ */
23
+ function extractCSSVariables( value, prefix = '' ) {
24
+ const regex = /--[\w-]+/g;
25
+ /** @type {Set<string>} */
26
+ const variables = new Set();
27
+
28
+ let match;
29
+ while ( ( match = regex.exec( value ) ) !== null ) {
30
+ const variableName = match[ 0 ];
31
+ if ( variableName.startsWith( `--${ prefix }` ) ) {
32
+ variables.add( variableName );
33
+ }
34
+ }
35
+
36
+ return variables;
37
+ }
38
+
39
+ const knownTokens = new Set( tokenList ?? [] );
40
+ const wpdsTokensRegex = new RegExp( `[^\\w]--${ DS_TOKEN_PREFIX }`, 'i' );
41
+
42
+ const {
43
+ createPlugin,
44
+ utils: { report, ruleMessages, validateOptions },
45
+ } = stylelint;
46
+
47
+ const ruleName = 'plugin-wpds/no-unknown-ds-tokens';
48
+
49
+ const messages = ruleMessages( ruleName, {
50
+ rejected: ( tokenNames ) =>
51
+ `The following CSS variables are not valid Design System tokens: ${ tokenNames }`,
52
+ } );
53
+
54
+ /** @type {import('stylelint').Rule} */
55
+ const ruleFunction = ( primary ) => {
56
+ return ( root, result ) => {
57
+ const validOptions = validateOptions( result, ruleName, {
58
+ actual: primary,
59
+ possible: [ true ],
60
+ } );
61
+
62
+ // Without `@wordpress/theme` there is no token list to validate against.
63
+ if ( ! validOptions || ! tokenList ) {
64
+ return;
65
+ }
66
+
67
+ root.walkDecls( ( ruleNode ) => {
68
+ const { value } = ruleNode;
69
+ // Early match for WPDS tokens to avoid unnecessary processing.
70
+ if ( wpdsTokensRegex.test( value ) ) {
71
+ const usedTokens = extractCSSVariables(
72
+ value,
73
+ DS_TOKEN_PREFIX
74
+ );
75
+ const unknownTokens = new Set(
76
+ [ ...usedTokens ].filter(
77
+ ( token ) => ! knownTokens.has( token )
78
+ )
79
+ );
80
+
81
+ if ( unknownTokens.size > 0 ) {
82
+ report( {
83
+ message: messages.rejected(
84
+ Array.from( unknownTokens )
85
+ .map( ( token ) => `'${ token }'` )
86
+ .join( ', ' )
87
+ ),
88
+ node: ruleNode,
89
+ result,
90
+ ruleName,
91
+ } );
92
+ }
93
+ }
94
+ } );
95
+ };
96
+ };
97
+
98
+ ruleFunction.ruleName = ruleName;
99
+ ruleFunction.messages = messages;
100
+
101
+ /** @type {import('stylelint').Plugin} */
102
+ export default createPlugin( ruleName, ruleFunction );
@@ -0,0 +1,33 @@
1
+ import { transformDsTokenFallbacks } from '../js-plugins/transform-ds-token-fallbacks.mjs';
2
+
3
+ /**
4
+ * Vite plugin that injects design-system token fallbacks into JS/TS files.
5
+ *
6
+ * Replaces bare `var(--wpds-*)` references in string literals with
7
+ * `var(--wpds-*, <fallback>)` so components render correctly without
8
+ * a ThemeProvider. Does nothing when `@wordpress/theme` is not installed.
9
+ *
10
+ * @type {() => import('vite').Plugin}
11
+ */
12
+ const plugin = () => ( {
13
+ name: 'ds-token-fallbacks-js',
14
+ enforce: 'pre',
15
+ transform( code, id ) {
16
+ const [ filename, query = '' ] = id.split( '?' );
17
+ const params = new URLSearchParams( query );
18
+ if (
19
+ ! /\.[mc]?[jt]sx?$/.test( filename ) ||
20
+ params.has( 'raw' ) ||
21
+ params.has( 'url' )
22
+ ) {
23
+ return null;
24
+ }
25
+ if ( id.includes( 'node_modules' ) ) {
26
+ return null;
27
+ }
28
+ const result = transformDsTokenFallbacks( code, filename );
29
+ return result ? { code: result.code, map: result.map } : null;
30
+ },
31
+ } );
32
+
33
+ export default plugin;