@wordpress/theme 0.8.1-next.v.202603161435.0 → 0.9.0

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+## 0.9.0 (2026-03-18)
+
+### New Features
+
+-   Added `no-token-fallback-values` stylelint rule that disallows manual fallback values for `--wpds-*` design tokens. Available as `@wordpress/theme/stylelint-plugins/no-token-fallback-values` ([#76415](https://github.com/WordPress/gutenberg/pull/76415)).
+
 ## 0.8.0 (2026-03-04)
 
 ### New Features

package/README.md

@@ -204,11 +204,13 @@ This package provides Stylelint plugins to help enforce consistent usage of desi
 {
 	"plugins": [
 		"@wordpress/theme/stylelint-plugins/no-unknown-ds-tokens",
-		"@wordpress/theme/stylelint-plugins/no-setting-wpds-custom-properties"
+		"@wordpress/theme/stylelint-plugins/no-setting-wpds-custom-properties",
+		"@wordpress/theme/stylelint-plugins/no-token-fallback-values"
 	],
 	"rules": {
 		"plugin-wpds/no-unknown-ds-tokens": true,
-		"plugin-wpds/no-setting-wpds-custom-properties": true
+		"plugin-wpds/no-setting-wpds-custom-properties": true,
+		"plugin-wpds/no-token-fallback-values": true
 	}
 }
 ```
@@ -250,6 +252,27 @@ This rule reports an error when a CSS declaration sets (defines) a custom proper
 }
 ```
 
+### `plugin-wpds/no-token-fallback-values`
+
+This rule reports an error when a `var()` call for a `--wpds-*` token includes a manual fallback value. Fallback values for design tokens are injected automatically at build time by the [build plugins](#build-plugins), so manual fallbacks in source are redundant and can drift out of sync with the token definitions.
+
+```css
+/* ✗ Error: Do not add a fallback value for Design System token '--wpds-color-fg-content-neutral' */
+.example {
+	color: var(--wpds-color-fg-content-neutral, #1e1e1e);
+}
+
+/* ✓ OK */
+.example {
+	color: var(--wpds-color-fg-content-neutral);
+}
+
+/* ✓ OK: Non-wpds custom properties are not checked */
+.example {
+	color: var(--my-custom-color, red);
+}
+```
+
 ## Build Plugins
 
 This package provides build plugins that inject fallback values into bare `var(--wpds-*)` references at build time. This ensures components render correctly even when a `ThemeProvider` or design tokens stylesheet is not present — for example, `var(--wpds-color-fg-content-neutral)` becomes `var(--wpds-color-fg-content-neutral, #1e1e1e)`.

package/build/esbuild-plugins/esbuild-ds-token-fallbacks.cjs

@@ -47,7 +47,7 @@ var plugin = {
       }
       const ext = args.path.match(/(\.[^.]+)$/)?.[1] || ".js";
       return {
-        contents: (0, import_ds_token_fallbacks.addFallbackToVar)(source),
+        contents: (0, import_ds_token_fallbacks.addFallbackToVar)(source, { escapeQuotes: true }),
         loader: LOADER_MAP[ext] || "jsx"
       };
     });

package/build/esbuild-plugins/esbuild-ds-token-fallbacks.cjs.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/esbuild-plugins/esbuild-ds-token-fallbacks.mjs"],
-  "sourcesContent": ["import { readFile } from 'fs/promises';\nimport { addFallbackToVar } from '../postcss-plugins/ds-token-fallbacks.mjs';\n\nconst LOADER_MAP = {\n\t'.js': 'jsx',\n\t'.jsx': 'jsx',\n\t'.ts': 'tsx',\n\t'.tsx': 'tsx',\n\t'.mjs': 'jsx',\n\t'.mts': 'tsx',\n\t'.cjs': 'jsx',\n\t'.cts': 'tsx',\n};\n\n/**\n * esbuild plugin that injects design-system token fallbacks into JS/TS files.\n *\n * Replaces bare `var(--wpds-*)` references in string literals with\n * `var(--wpds-*, <fallback>)` so components render correctly without\n * a ThemeProvider.\n */\nconst plugin = {\n\tname: 'ds-token-fallbacks-js',\n\tsetup( build ) {\n\t\tbuild.onLoad( { filter: /\\.[mc]?[jt]sx?$/ }, async ( args ) => {\n\t\t\t// Skip node_modules.\n\t\t\tif ( args.path.includes( 'node_modules' ) ) {\n\t\t\t\treturn undefined;\n\t\t\t}\n\n\t\t\tconst source = await readFile( args.path, 'utf8' );\n\n\t\t\tif ( ! source.includes( '--wpds-' ) ) {\n\t\t\t\treturn undefined;\n\t\t\t}\n\n\t\t\tconst ext = args.path.match( /(\\.[^.]+)$/ )?.[ 1 ] || '.js';\n\n\t\t\treturn {\n\t\t\t\tcontents: addFallbackToVar( source ),\n\t\t\t\tloader: LOADER_MAP[ ext ] || 'jsx',\n\t\t\t};\n\t\t} );\n\t},\n};\n\nexport default plugin;\n"],
-  "mappings": ";;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,sBAAyB;AACzB,gCAAiC;AAEjC,IAAM,aAAa;AAAA,EAClB,OAAO;AAAA,EACP,QAAQ;AAAA,EACR,OAAO;AAAA,EACP,QAAQ;AAAA,EACR,QAAQ;AAAA,EACR,QAAQ;AAAA,EACR,QAAQ;AAAA,EACR,QAAQ;AACT;AASA,IAAM,SAAS;AAAA,EACd,MAAM;AAAA,EACN,MAAO,OAAQ;AACd,UAAM,OAAQ,EAAE,QAAQ,kBAAkB,GAAG,OAAQ,SAAU;AAE9D,UAAK,KAAK,KAAK,SAAU,cAAe,GAAI;AAC3C,eAAO;AAAA,MACR;AAEA,YAAM,SAAS,UAAM,0BAAU,KAAK,MAAM,MAAO;AAEjD,UAAK,CAAE,OAAO,SAAU,SAAU,GAAI;AACrC,eAAO;AAAA,MACR;AAEA,YAAM,MAAM,KAAK,KAAK,MAAO,YAAa,IAAK,CAAE,KAAK;AAEtD,aAAO;AAAA,QACN,cAAU,4CAAkB,MAAO;AAAA,QACnC,QAAQ,WAAY,GAAI,KAAK;AAAA,MAC9B;AAAA,IACD,CAAE;AAAA,EACH;AACD;AAEA,IAAO,qCAAQ;",
+  "sourcesContent": ["import { readFile } from 'fs/promises';\nimport { addFallbackToVar } from '../postcss-plugins/ds-token-fallbacks.mjs';\n\nconst LOADER_MAP = {\n\t'.js': 'jsx',\n\t'.jsx': 'jsx',\n\t'.ts': 'tsx',\n\t'.tsx': 'tsx',\n\t'.mjs': 'jsx',\n\t'.mts': 'tsx',\n\t'.cjs': 'jsx',\n\t'.cts': 'tsx',\n};\n\n/**\n * esbuild plugin that injects design-system token fallbacks into JS/TS files.\n *\n * Replaces bare `var(--wpds-*)` references in string literals with\n * `var(--wpds-*, <fallback>)` so components render correctly without\n * a ThemeProvider.\n */\nconst plugin = {\n\tname: 'ds-token-fallbacks-js',\n\tsetup( build ) {\n\t\tbuild.onLoad( { filter: /\\.[mc]?[jt]sx?$/ }, async ( args ) => {\n\t\t\t// Skip node_modules.\n\t\t\tif ( args.path.includes( 'node_modules' ) ) {\n\t\t\t\treturn undefined;\n\t\t\t}\n\n\t\t\tconst source = await readFile( args.path, 'utf8' );\n\n\t\t\tif ( ! source.includes( '--wpds-' ) ) {\n\t\t\t\treturn undefined;\n\t\t\t}\n\n\t\t\tconst ext = args.path.match( /(\\.[^.]+)$/ )?.[ 1 ] || '.js';\n\n\t\t\treturn {\n\t\t\t\tcontents: addFallbackToVar( source, { escapeQuotes: true } ),\n\t\t\t\tloader: LOADER_MAP[ ext ] || 'jsx',\n\t\t\t};\n\t\t} );\n\t},\n};\n\nexport default plugin;\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,sBAAyB;AACzB,gCAAiC;AAEjC,IAAM,aAAa;AAAA,EAClB,OAAO;AAAA,EACP,QAAQ;AAAA,EACR,OAAO;AAAA,EACP,QAAQ;AAAA,EACR,QAAQ;AAAA,EACR,QAAQ;AAAA,EACR,QAAQ;AAAA,EACR,QAAQ;AACT;AASA,IAAM,SAAS;AAAA,EACd,MAAM;AAAA,EACN,MAAO,OAAQ;AACd,UAAM,OAAQ,EAAE,QAAQ,kBAAkB,GAAG,OAAQ,SAAU;AAE9D,UAAK,KAAK,KAAK,SAAU,cAAe,GAAI;AAC3C,eAAO;AAAA,MACR;AAEA,YAAM,SAAS,UAAM,0BAAU,KAAK,MAAM,MAAO;AAEjD,UAAK,CAAE,OAAO,SAAU,SAAU,GAAI;AACrC,eAAO;AAAA,MACR;AAEA,YAAM,MAAM,KAAK,KAAK,MAAO,YAAa,IAAK,CAAE,KAAK;AAEtD,aAAO;AAAA,QACN,cAAU,4CAAkB,QAAQ,EAAE,cAAc,KAAK,CAAE;AAAA,QAC3D,QAAQ,WAAY,GAAI,KAAK;AAAA,MAC9B;AAAA,IACD,CAAE;AAAA,EACH;AACD;AAEA,IAAO,qCAAQ;",
   "names": []
 }

package/build/postcss-plugins/add-fallback-to-var.cjs

@@ -22,12 +22,18 @@ __export(add_fallback_to_var_exports, {
   addFallbackToVar: () => addFallbackToVar
 });
 module.exports = __toCommonJS(add_fallback_to_var_exports);
-function addFallbackToVar(cssValue, tokenFallbacks) {
+function addFallbackToVar(cssValue, tokenFallbacks, { escapeQuotes = false } = {}) {
   return cssValue.replace(
     /var\(\s*(--wpds-[\w-]+)\s*\)/g,
     (match, tokenName) => {
-      const fallback = tokenFallbacks[tokenName];
-      return fallback !== void 0 ? `var(${tokenName}, ${fallback})` : match;
+      let fallback = tokenFallbacks[tokenName];
+      if (fallback === void 0) {
+        return match;
+      }
+      if (escapeQuotes) {
+        fallback = fallback.replaceAll('"', '\\"').replaceAll("'", "\\'");
+      }
+      return `var(${tokenName}, ${fallback})`;
     }
   );
 }

package/build/postcss-plugins/add-fallback-to-var.cjs.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/postcss-plugins/add-fallback-to-var.ts"],
-  "sourcesContent": ["/**\n * Replace bare `var(--wpds-*)` references in a CSS value string with\n * `var(--wpds-*, <fallback>)` using the provided token fallback map.\n *\n * Existing fallbacks (i.e. `var()` calls that already contain a comma)\n * are left untouched, making the function safe to run multiple times\n * (idempotent).\n *\n * NOTE: The regex and replacement logic here is mirrored in\n * `ds-token-fallbacks.mjs`. If you update one, update the other to match.\n *\n * @param cssValue       A CSS declaration value.\n * @param tokenFallbacks Map of CSS variable names to their fallback expressions.\n * @return The value with fallbacks injected.\n */\nexport function addFallbackToVar(\n\tcssValue: string,\n\ttokenFallbacks: Record< string, string >\n): string {\n\treturn cssValue.replace(\n\t\t/var\\(\\s*(--wpds-[\\w-]+)\\s*\\)/g,\n\t\t( match, tokenName: string ) => {\n\t\t\tconst fallback = tokenFallbacks[ tokenName ];\n\t\t\treturn fallback !== undefined\n\t\t\t\t? `var(${ tokenName }, ${ fallback })`\n\t\t\t\t: match;\n\t\t}\n\t);\n}\n"],
-  "mappings": ";;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAeO,SAAS,iBACf,UACA,gBACS;AACT,SAAO,SAAS;AAAA,IACf;AAAA,IACA,CAAE,OAAO,cAAuB;AAC/B,YAAM,WAAW,eAAgB,SAAU;AAC3C,aAAO,aAAa,SACjB,OAAQ,SAAU,KAAM,QAAS,MACjC;AAAA,IACJ;AAAA,EACD;AACD;",
+  "sourcesContent": ["/**\n * Replace bare `var(--wpds-*)` references in a CSS value string with\n * `var(--wpds-*, <fallback>)` using the provided token fallback map.\n *\n * Existing fallbacks (i.e. `var()` calls that already contain a comma)\n * are left untouched, making the function safe to run multiple times\n * (idempotent).\n *\n * NOTE: The regex and replacement logic here is mirrored in\n * `ds-token-fallbacks.mjs`. If you update one, update the other to match.\n *\n * @param cssValue             A CSS declaration value.\n * @param tokenFallbacks       Map of CSS variable names to their fallback expressions.\n * @param options              Options.\n * @param options.escapeQuotes When true, escape `\"` and `'` in fallback values.\n *                             Use this when the input is JS/TS source so that\n *                             injected quotes don't break string literals.\n * @return                     The value with fallbacks injected.\n */\nexport function addFallbackToVar(\n\tcssValue: string,\n\ttokenFallbacks: Record< string, string >,\n\t{ escapeQuotes = false }: { escapeQuotes?: boolean } = {}\n): string {\n\treturn cssValue.replace(\n\t\t/var\\(\\s*(--wpds-[\\w-]+)\\s*\\)/g,\n\t\t( match, tokenName: string ) => {\n\t\t\tlet fallback = tokenFallbacks[ tokenName ];\n\t\t\tif ( fallback === undefined ) {\n\t\t\t\treturn match;\n\t\t\t}\n\t\t\tif ( escapeQuotes ) {\n\t\t\t\tfallback = fallback\n\t\t\t\t\t.replaceAll( '\"', '\\\\\"' )\n\t\t\t\t\t.replaceAll( \"'\", \"\\\\'\" );\n\t\t\t}\n\t\t\treturn `var(${ tokenName }, ${ fallback })`;\n\t\t}\n\t);\n}\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAmBO,SAAS,iBACf,UACA,gBACA,EAAE,eAAe,MAAM,IAAgC,CAAC,GAC/C;AACT,SAAO,SAAS;AAAA,IACf;AAAA,IACA,CAAE,OAAO,cAAuB;AAC/B,UAAI,WAAW,eAAgB,SAAU;AACzC,UAAK,aAAa,QAAY;AAC7B,eAAO;AAAA,MACR;AACA,UAAK,cAAe;AACnB,mBAAW,SACT,WAAY,KAAK,KAAM,EACvB,WAAY,KAAK,KAAM;AAAA,MAC1B;AACA,aAAO,OAAQ,SAAU,KAAM,QAAS;AAAA,IACzC;AAAA,EACD;AACD;",
   "names": []
 }

package/build/postcss-plugins/ds-token-fallbacks.cjs

@@ -34,12 +34,18 @@ __export(ds_token_fallbacks_exports, {
 module.exports = __toCommonJS(ds_token_fallbacks_exports);
 var import_design_token_fallbacks = __toESM(require("../prebuilt/js/design-token-fallbacks.mjs"), 1);
 var tokenFallbacks = import_design_token_fallbacks.default;
-function addFallbackToVar(cssValue) {
+function addFallbackToVar(cssValue, { escapeQuotes = false } = {}) {
   return cssValue.replace(
     /var\(\s*(--wpds-[\w-]+)\s*\)/g,
     (match, tokenName) => {
-      const fallback = tokenFallbacks[tokenName];
-      return fallback !== void 0 ? `var(${tokenName}, ${fallback})` : match;
+      let fallback = tokenFallbacks[tokenName];
+      if (fallback === void 0) {
+        return match;
+      }
+      if (escapeQuotes) {
+        fallback = fallback.replaceAll('"', '\\"').replaceAll("'", "\\'");
+      }
+      return `var(${tokenName}, ${fallback})`;
     }
   );
 }

package/build/postcss-plugins/ds-token-fallbacks.cjs.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/postcss-plugins/ds-token-fallbacks.mjs"],
-  "sourcesContent": ["import _tokenFallbacks from '../prebuilt/js/design-token-fallbacks.mjs';\n\n/** @type {Record<string, string>} */\nconst tokenFallbacks = _tokenFallbacks;\n\n/**\n * Replace bare `var(--wpds-*)` references in a CSS value string with\n * `var(--wpds-*, <fallback>)` using the generated token fallback map.\n *\n * Existing fallbacks (i.e. var() calls that already contain a comma) are\n * left untouched, making the function safe to run multiple times.\n *\n * NOTE: The regex and replacement logic here mirrors `add-fallback-to-var.ts`.\n * If you update one, update the other to match.\n *\n * @param {string} cssValue A CSS declaration value.\n * @return {string} The value with fallbacks injected.\n */\nexport function addFallbackToVar( cssValue ) {\n\treturn cssValue.replace(\n\t\t/var\\(\\s*(--wpds-[\\w-]+)\\s*\\)/g,\n\t\t( match, tokenName ) => {\n\t\t\tconst fallback = tokenFallbacks[ tokenName ];\n\t\t\treturn fallback !== undefined\n\t\t\t\t? `var(${ tokenName }, ${ fallback })`\n\t\t\t\t: match;\n\t\t}\n\t);\n}\n"],
-  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,oCAA4B;AAG5B,IAAM,iBAAiB,8BAAAA;AAehB,SAAS,iBAAkB,UAAW;AAC5C,SAAO,SAAS;AAAA,IACf;AAAA,IACA,CAAE,OAAO,cAAe;AACvB,YAAM,WAAW,eAAgB,SAAU;AAC3C,aAAO,aAAa,SACjB,OAAQ,SAAU,KAAM,QAAS,MACjC;AAAA,IACJ;AAAA,EACD;AACD;",
+  "sourcesContent": ["import _tokenFallbacks from '../prebuilt/js/design-token-fallbacks.mjs';\n\n/** @type {Record<string, string>} */\nconst tokenFallbacks = _tokenFallbacks;\n\n/**\n * Replace bare `var(--wpds-*)` references in a CSS value string with\n * `var(--wpds-*, <fallback>)` using the generated token fallback map.\n *\n * Existing fallbacks (i.e. var() calls that already contain a comma) are\n * left untouched, making the function safe to run multiple times.\n *\n * NOTE: The regex and replacement logic here mirrors `add-fallback-to-var.ts`.\n * If you update one, update the other to match.\n *\n * @param {string}  cssValue               A CSS declaration value.\n * @param {Object}  [options]              Options.\n * @param {boolean} [options.escapeQuotes] When true, escape `\"` and `'` in\n *                                         fallback values. Use this when the\n *                                         input is JS/TS source so that\n *                                         injected quotes don't break string\n *                                         literals. JS will unescape them at\n *                                         parse time, so the browser's CSS\n *                                         engine still sees the correct value.\n * @return {string}                        The value with fallbacks injected.\n */\nexport function addFallbackToVar( cssValue, { escapeQuotes = false } = {} ) {\n\treturn cssValue.replace(\n\t\t/var\\(\\s*(--wpds-[\\w-]+)\\s*\\)/g,\n\t\t( match, tokenName ) => {\n\t\t\tlet fallback = tokenFallbacks[ tokenName ];\n\t\t\tif ( fallback === undefined ) {\n\t\t\t\treturn match;\n\t\t\t}\n\t\t\tif ( escapeQuotes ) {\n\t\t\t\tfallback = fallback\n\t\t\t\t\t.replaceAll( '\"', '\\\\\"' )\n\t\t\t\t\t.replaceAll( \"'\", \"\\\\'\" );\n\t\t\t}\n\t\t\treturn `var(${ tokenName }, ${ fallback })`;\n\t\t}\n\t);\n}\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,oCAA4B;AAG5B,IAAM,iBAAiB,8BAAAA;AAuBhB,SAAS,iBAAkB,UAAU,EAAE,eAAe,MAAM,IAAI,CAAC,GAAI;AAC3E,SAAO,SAAS;AAAA,IACf;AAAA,IACA,CAAE,OAAO,cAAe;AACvB,UAAI,WAAW,eAAgB,SAAU;AACzC,UAAK,aAAa,QAAY;AAC7B,eAAO;AAAA,MACR;AACA,UAAK,cAAe;AACnB,mBAAW,SACT,WAAY,KAAK,KAAM,EACvB,WAAY,KAAK,KAAM;AAAA,MAC1B;AACA,aAAO,OAAQ,SAAU,KAAM,QAAS;AAAA,IACzC;AAAA,EACD;AACD;",
   "names": ["_tokenFallbacks"]
 }

package/build/stylelint-plugins/no-token-fallback-values.cjs

@@ -0,0 +1,73 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// packages/theme/src/stylelint-plugins/no-token-fallback-values.mjs
+var no_token_fallback_values_exports = {};
+__export(no_token_fallback_values_exports, {
+  default: () => no_token_fallback_values_default
+});
+module.exports = __toCommonJS(no_token_fallback_values_exports);
+var import_stylelint = __toESM(require("stylelint"), 1);
+var {
+  createPlugin,
+  utils: { report, ruleMessages, validateOptions }
+} = import_stylelint.default;
+var ruleName = "plugin-wpds/no-token-fallback-values";
+var varWithFallbackRegex = /var\(\s*(--wpds-[\w-]+)\s*,/g;
+var messages = ruleMessages(ruleName, {
+  rejected: (tokenName) => `Do not add a fallback value for Design System token '${tokenName}'. Fallbacks are injected automatically at build time.`
+});
+var ruleFunction = (primary) => {
+  return (root, result) => {
+    const validOptions = validateOptions(result, ruleName, {
+      actual: primary,
+      possible: [true]
+    });
+    if (!validOptions) {
+      return;
+    }
+    root.walkDecls((ruleNode) => {
+      const { value } = ruleNode;
+      let match;
+      varWithFallbackRegex.lastIndex = 0;
+      while ((match = varWithFallbackRegex.exec(value)) !== null) {
+        report({
+          message: messages.rejected(match[1]),
+          node: ruleNode,
+          word: match[0],
+          result,
+          ruleName
+        });
+      }
+    });
+  };
+};
+ruleFunction.ruleName = ruleName;
+ruleFunction.messages = messages;
+var no_token_fallback_values_default = createPlugin(ruleName, ruleFunction);
+//# sourceMappingURL=no-token-fallback-values.cjs.map

package/build/stylelint-plugins/no-token-fallback-values.cjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/stylelint-plugins/no-token-fallback-values.mjs"],
+  "sourcesContent": ["import stylelint from 'stylelint';\n\nconst {\n\tcreatePlugin,\n\tutils: { report, ruleMessages, validateOptions },\n} = stylelint;\n\nconst ruleName = 'plugin-wpds/no-token-fallback-values';\n\n/**\n * Matches `var(--wpds-<name>,` \u2014 the comma signals a fallback value.\n * Captures the token name (e.g. `--wpds-color-fg-content-neutral`).\n */\nconst varWithFallbackRegex = /var\\(\\s*(--wpds-[\\w-]+)\\s*,/g;\n\nconst messages = ruleMessages( ruleName, {\n\trejected: ( tokenName ) =>\n\t\t`Do not add a fallback value for Design System token '${ tokenName }'. Fallbacks are injected automatically at build time.`,\n} );\n\n/** @type {import('stylelint').Rule} */\nconst ruleFunction = ( primary ) => {\n\treturn ( root, result ) => {\n\t\tconst validOptions = validateOptions( result, ruleName, {\n\t\t\tactual: primary,\n\t\t\tpossible: [ true ],\n\t\t} );\n\n\t\tif ( ! validOptions ) {\n\t\t\treturn;\n\t\t}\n\n\t\troot.walkDecls( ( ruleNode ) => {\n\t\t\tconst { value } = ruleNode;\n\n\t\t\tlet match;\n\t\t\tvarWithFallbackRegex.lastIndex = 0;\n\t\t\twhile ( ( match = varWithFallbackRegex.exec( value ) ) !== null ) {\n\t\t\t\treport( {\n\t\t\t\t\tmessage: messages.rejected( match[ 1 ] ),\n\t\t\t\t\tnode: ruleNode,\n\t\t\t\t\tword: match[ 0 ],\n\t\t\t\t\tresult,\n\t\t\t\t\truleName,\n\t\t\t\t} );\n\t\t\t}\n\t\t} );\n\t};\n};\n\nruleFunction.ruleName = ruleName;\nruleFunction.messages = messages;\n\n/** @type {import('stylelint').Plugin} */\nexport default createPlugin( ruleName, ruleFunction );\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,uBAAsB;AAEtB,IAAM;AAAA,EACL;AAAA,EACA,OAAO,EAAE,QAAQ,cAAc,gBAAgB;AAChD,IAAI,iBAAAA;AAEJ,IAAM,WAAW;AAMjB,IAAM,uBAAuB;AAE7B,IAAM,WAAW,aAAc,UAAU;AAAA,EACxC,UAAU,CAAE,cACX,wDAAyD,SAAU;AACrE,CAAE;AAGF,IAAM,eAAe,CAAE,YAAa;AACnC,SAAO,CAAE,MAAM,WAAY;AAC1B,UAAM,eAAe,gBAAiB,QAAQ,UAAU;AAAA,MACvD,QAAQ;AAAA,MACR,UAAU,CAAE,IAAK;AAAA,IAClB,CAAE;AAEF,QAAK,CAAE,cAAe;AACrB;AAAA,IACD;AAEA,SAAK,UAAW,CAAE,aAAc;AAC/B,YAAM,EAAE,MAAM,IAAI;AAElB,UAAI;AACJ,2BAAqB,YAAY;AACjC,cAAU,QAAQ,qBAAqB,KAAM,KAAM,OAAQ,MAAO;AACjE,eAAQ;AAAA,UACP,SAAS,SAAS,SAAU,MAAO,CAAE,CAAE;AAAA,UACvC,MAAM;AAAA,UACN,MAAM,MAAO,CAAE;AAAA,UACf;AAAA,UACA;AAAA,QACD,CAAE;AAAA,MACH;AAAA,IACD,CAAE;AAAA,EACH;AACD;AAEA,aAAa,WAAW;AACxB,aAAa,WAAW;AAGxB,IAAO,mCAAQ,aAAc,UAAU,YAAa;",
+  "names": ["stylelint"]
+}

package/build/vite-plugins/vite-ds-token-fallbacks.cjs

@@ -35,7 +35,10 @@ var plugin = () => ({
     if (!code.includes("--wpds-")) {
       return null;
     }
-    return { code: (0, import_ds_token_fallbacks.addFallbackToVar)(code), map: null };
+    return {
+      code: (0, import_ds_token_fallbacks.addFallbackToVar)(code, { escapeQuotes: true }),
+      map: null
+    };
   }
 });
 var vite_ds_token_fallbacks_default = plugin;

package/build/vite-plugins/vite-ds-token-fallbacks.cjs.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/vite-plugins/vite-ds-token-fallbacks.mjs"],
-  "sourcesContent": ["import { addFallbackToVar } from '../postcss-plugins/ds-token-fallbacks.mjs';\n\n/**\n * Vite plugin that injects design-system token fallbacks into JS/TS files.\n *\n * Replaces bare `var(--wpds-*)` references in string literals with\n * `var(--wpds-*, <fallback>)` so components render correctly without\n * a ThemeProvider.\n */\nconst plugin = () => ( {\n\tname: 'ds-token-fallbacks-js',\n\ttransform( code, id ) {\n\t\tif ( ! /\\.[mc]?[jt]sx?$/.test( id ) ) {\n\t\t\treturn null;\n\t\t}\n\t\tif ( id.includes( 'node_modules' ) ) {\n\t\t\treturn null;\n\t\t}\n\t\tif ( ! code.includes( '--wpds-' ) ) {\n\t\t\treturn null;\n\t\t}\n\t\t// Sourcemap omitted: replacements are small, inline substitutions\n\t\t// that preserve line structure, so the debugging impact is negligible.\n\t\treturn { code: addFallbackToVar( code ), map: null };\n\t},\n} );\n\nexport default plugin;\n"],
-  "mappings": ";;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,gCAAiC;AASjC,IAAM,SAAS,OAAQ;AAAA,EACtB,MAAM;AAAA,EACN,UAAW,MAAM,IAAK;AACrB,QAAK,CAAE,kBAAkB,KAAM,EAAG,GAAI;AACrC,aAAO;AAAA,IACR;AACA,QAAK,GAAG,SAAU,cAAe,GAAI;AACpC,aAAO;AAAA,IACR;AACA,QAAK,CAAE,KAAK,SAAU,SAAU,GAAI;AACnC,aAAO;AAAA,IACR;AAGA,WAAO,EAAE,UAAM,4CAAkB,IAAK,GAAG,KAAK,KAAK;AAAA,EACpD;AACD;AAEA,IAAO,kCAAQ;",
+  "sourcesContent": ["import { addFallbackToVar } from '../postcss-plugins/ds-token-fallbacks.mjs';\n\n/**\n * Vite plugin that injects design-system token fallbacks into JS/TS files.\n *\n * Replaces bare `var(--wpds-*)` references in string literals with\n * `var(--wpds-*, <fallback>)` so components render correctly without\n * a ThemeProvider.\n */\nconst plugin = () => ( {\n\tname: 'ds-token-fallbacks-js',\n\ttransform( code, id ) {\n\t\tif ( ! /\\.[mc]?[jt]sx?$/.test( id ) ) {\n\t\t\treturn null;\n\t\t}\n\t\tif ( id.includes( 'node_modules' ) ) {\n\t\t\treturn null;\n\t\t}\n\t\tif ( ! code.includes( '--wpds-' ) ) {\n\t\t\treturn null;\n\t\t}\n\t\t// Sourcemap omitted: replacements are small, inline substitutions\n\t\t// that preserve line structure, so the debugging impact is negligible.\n\t\treturn {\n\t\t\tcode: addFallbackToVar( code, { escapeQuotes: true } ),\n\t\t\tmap: null,\n\t\t};\n\t},\n} );\n\nexport default plugin;\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,gCAAiC;AASjC,IAAM,SAAS,OAAQ;AAAA,EACtB,MAAM;AAAA,EACN,UAAW,MAAM,IAAK;AACrB,QAAK,CAAE,kBAAkB,KAAM,EAAG,GAAI;AACrC,aAAO;AAAA,IACR;AACA,QAAK,GAAG,SAAU,cAAe,GAAI;AACpC,aAAO;AAAA,IACR;AACA,QAAK,CAAE,KAAK,SAAU,SAAU,GAAI;AACnC,aAAO;AAAA,IACR;AAGA,WAAO;AAAA,MACN,UAAM,4CAAkB,MAAM,EAAE,cAAc,KAAK,CAAE;AAAA,MACrD,KAAK;AAAA,IACN;AAAA,EACD;AACD;AAEA,IAAO,kCAAQ;",
   "names": []
 }

package/build-module/esbuild-plugins/esbuild-ds-token-fallbacks.mjs

@@ -24,7 +24,7 @@ var plugin = {
       }
       const ext = args.path.match(/(\.[^.]+)$/)?.[1] || ".js";
       return {
-        contents: addFallbackToVar(source),
+        contents: addFallbackToVar(source, { escapeQuotes: true }),
         loader: LOADER_MAP[ext] || "jsx"
       };
     });

package/build-module/esbuild-plugins/esbuild-ds-token-fallbacks.mjs.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/esbuild-plugins/esbuild-ds-token-fallbacks.mjs"],
-  "sourcesContent": ["import { readFile } from 'fs/promises';\nimport { addFallbackToVar } from '../postcss-plugins/ds-token-fallbacks.mjs';\n\nconst LOADER_MAP = {\n\t'.js': 'jsx',\n\t'.jsx': 'jsx',\n\t'.ts': 'tsx',\n\t'.tsx': 'tsx',\n\t'.mjs': 'jsx',\n\t'.mts': 'tsx',\n\t'.cjs': 'jsx',\n\t'.cts': 'tsx',\n};\n\n/**\n * esbuild plugin that injects design-system token fallbacks into JS/TS files.\n *\n * Replaces bare `var(--wpds-*)` references in string literals with\n * `var(--wpds-*, <fallback>)` so components render correctly without\n * a ThemeProvider.\n */\nconst plugin = {\n\tname: 'ds-token-fallbacks-js',\n\tsetup( build ) {\n\t\tbuild.onLoad( { filter: /\\.[mc]?[jt]sx?$/ }, async ( args ) => {\n\t\t\t// Skip node_modules.\n\t\t\tif ( args.path.includes( 'node_modules' ) ) {\n\t\t\t\treturn undefined;\n\t\t\t}\n\n\t\t\tconst source = await readFile( args.path, 'utf8' );\n\n\t\t\tif ( ! source.includes( '--wpds-' ) ) {\n\t\t\t\treturn undefined;\n\t\t\t}\n\n\t\t\tconst ext = args.path.match( /(\\.[^.]+)$/ )?.[ 1 ] || '.js';\n\n\t\t\treturn {\n\t\t\t\tcontents: addFallbackToVar( source ),\n\t\t\t\tloader: LOADER_MAP[ ext ] || 'jsx',\n\t\t\t};\n\t\t} );\n\t},\n};\n\nexport default plugin;\n"],
-  "mappings": ";AAAA,SAAS,gBAAgB;AACzB,SAAS,wBAAwB;AAEjC,IAAM,aAAa;AAAA,EAClB,OAAO;AAAA,EACP,QAAQ;AAAA,EACR,OAAO;AAAA,EACP,QAAQ;AAAA,EACR,QAAQ;AAAA,EACR,QAAQ;AAAA,EACR,QAAQ;AAAA,EACR,QAAQ;AACT;AASA,IAAM,SAAS;AAAA,EACd,MAAM;AAAA,EACN,MAAO,OAAQ;AACd,UAAM,OAAQ,EAAE,QAAQ,kBAAkB,GAAG,OAAQ,SAAU;AAE9D,UAAK,KAAK,KAAK,SAAU,cAAe,GAAI;AAC3C,eAAO;AAAA,MACR;AAEA,YAAM,SAAS,MAAM,SAAU,KAAK,MAAM,MAAO;AAEjD,UAAK,CAAE,OAAO,SAAU,SAAU,GAAI;AACrC,eAAO;AAAA,MACR;AAEA,YAAM,MAAM,KAAK,KAAK,MAAO,YAAa,IAAK,CAAE,KAAK;AAEtD,aAAO;AAAA,QACN,UAAU,iBAAkB,MAAO;AAAA,QACnC,QAAQ,WAAY,GAAI,KAAK;AAAA,MAC9B;AAAA,IACD,CAAE;AAAA,EACH;AACD;AAEA,IAAO,qCAAQ;",
+  "sourcesContent": ["import { readFile } from 'fs/promises';\nimport { addFallbackToVar } from '../postcss-plugins/ds-token-fallbacks.mjs';\n\nconst LOADER_MAP = {\n\t'.js': 'jsx',\n\t'.jsx': 'jsx',\n\t'.ts': 'tsx',\n\t'.tsx': 'tsx',\n\t'.mjs': 'jsx',\n\t'.mts': 'tsx',\n\t'.cjs': 'jsx',\n\t'.cts': 'tsx',\n};\n\n/**\n * esbuild plugin that injects design-system token fallbacks into JS/TS files.\n *\n * Replaces bare `var(--wpds-*)` references in string literals with\n * `var(--wpds-*, <fallback>)` so components render correctly without\n * a ThemeProvider.\n */\nconst plugin = {\n\tname: 'ds-token-fallbacks-js',\n\tsetup( build ) {\n\t\tbuild.onLoad( { filter: /\\.[mc]?[jt]sx?$/ }, async ( args ) => {\n\t\t\t// Skip node_modules.\n\t\t\tif ( args.path.includes( 'node_modules' ) ) {\n\t\t\t\treturn undefined;\n\t\t\t}\n\n\t\t\tconst source = await readFile( args.path, 'utf8' );\n\n\t\t\tif ( ! source.includes( '--wpds-' ) ) {\n\t\t\t\treturn undefined;\n\t\t\t}\n\n\t\t\tconst ext = args.path.match( /(\\.[^.]+)$/ )?.[ 1 ] || '.js';\n\n\t\t\treturn {\n\t\t\t\tcontents: addFallbackToVar( source, { escapeQuotes: true } ),\n\t\t\t\tloader: LOADER_MAP[ ext ] || 'jsx',\n\t\t\t};\n\t\t} );\n\t},\n};\n\nexport default plugin;\n"],
+  "mappings": ";AAAA,SAAS,gBAAgB;AACzB,SAAS,wBAAwB;AAEjC,IAAM,aAAa;AAAA,EAClB,OAAO;AAAA,EACP,QAAQ;AAAA,EACR,OAAO;AAAA,EACP,QAAQ;AAAA,EACR,QAAQ;AAAA,EACR,QAAQ;AAAA,EACR,QAAQ;AAAA,EACR,QAAQ;AACT;AASA,IAAM,SAAS;AAAA,EACd,MAAM;AAAA,EACN,MAAO,OAAQ;AACd,UAAM,OAAQ,EAAE,QAAQ,kBAAkB,GAAG,OAAQ,SAAU;AAE9D,UAAK,KAAK,KAAK,SAAU,cAAe,GAAI;AAC3C,eAAO;AAAA,MACR;AAEA,YAAM,SAAS,MAAM,SAAU,KAAK,MAAM,MAAO;AAEjD,UAAK,CAAE,OAAO,SAAU,SAAU,GAAI;AACrC,eAAO;AAAA,MACR;AAEA,YAAM,MAAM,KAAK,KAAK,MAAO,YAAa,IAAK,CAAE,KAAK;AAEtD,aAAO;AAAA,QACN,UAAU,iBAAkB,QAAQ,EAAE,cAAc,KAAK,CAAE;AAAA,QAC3D,QAAQ,WAAY,GAAI,KAAK;AAAA,MAC9B;AAAA,IACD,CAAE;AAAA,EACH;AACD;AAEA,IAAO,qCAAQ;",
   "names": []
 }

package/build-module/postcss-plugins/add-fallback-to-var.mjs

@@ -1,10 +1,16 @@
 // packages/theme/src/postcss-plugins/add-fallback-to-var.ts
-function addFallbackToVar(cssValue, tokenFallbacks) {
+function addFallbackToVar(cssValue, tokenFallbacks, { escapeQuotes = false } = {}) {
   return cssValue.replace(
     /var\(\s*(--wpds-[\w-]+)\s*\)/g,
     (match, tokenName) => {
-      const fallback = tokenFallbacks[tokenName];
-      return fallback !== void 0 ? `var(${tokenName}, ${fallback})` : match;
+      let fallback = tokenFallbacks[tokenName];
+      if (fallback === void 0) {
+        return match;
+      }
+      if (escapeQuotes) {
+        fallback = fallback.replaceAll('"', '\\"').replaceAll("'", "\\'");
+      }
+      return `var(${tokenName}, ${fallback})`;
     }
   );
 }

package/build-module/postcss-plugins/add-fallback-to-var.mjs.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/postcss-plugins/add-fallback-to-var.ts"],
-  "sourcesContent": ["/**\n * Replace bare `var(--wpds-*)` references in a CSS value string with\n * `var(--wpds-*, <fallback>)` using the provided token fallback map.\n *\n * Existing fallbacks (i.e. `var()` calls that already contain a comma)\n * are left untouched, making the function safe to run multiple times\n * (idempotent).\n *\n * NOTE: The regex and replacement logic here is mirrored in\n * `ds-token-fallbacks.mjs`. If you update one, update the other to match.\n *\n * @param cssValue       A CSS declaration value.\n * @param tokenFallbacks Map of CSS variable names to their fallback expressions.\n * @return The value with fallbacks injected.\n */\nexport function addFallbackToVar(\n\tcssValue: string,\n\ttokenFallbacks: Record< string, string >\n): string {\n\treturn cssValue.replace(\n\t\t/var\\(\\s*(--wpds-[\\w-]+)\\s*\\)/g,\n\t\t( match, tokenName: string ) => {\n\t\t\tconst fallback = tokenFallbacks[ tokenName ];\n\t\t\treturn fallback !== undefined\n\t\t\t\t? `var(${ tokenName }, ${ fallback })`\n\t\t\t\t: match;\n\t\t}\n\t);\n}\n"],
-  "mappings": ";AAeO,SAAS,iBACf,UACA,gBACS;AACT,SAAO,SAAS;AAAA,IACf;AAAA,IACA,CAAE,OAAO,cAAuB;AAC/B,YAAM,WAAW,eAAgB,SAAU;AAC3C,aAAO,aAAa,SACjB,OAAQ,SAAU,KAAM,QAAS,MACjC;AAAA,IACJ;AAAA,EACD;AACD;",
+  "sourcesContent": ["/**\n * Replace bare `var(--wpds-*)` references in a CSS value string with\n * `var(--wpds-*, <fallback>)` using the provided token fallback map.\n *\n * Existing fallbacks (i.e. `var()` calls that already contain a comma)\n * are left untouched, making the function safe to run multiple times\n * (idempotent).\n *\n * NOTE: The regex and replacement logic here is mirrored in\n * `ds-token-fallbacks.mjs`. If you update one, update the other to match.\n *\n * @param cssValue             A CSS declaration value.\n * @param tokenFallbacks       Map of CSS variable names to their fallback expressions.\n * @param options              Options.\n * @param options.escapeQuotes When true, escape `\"` and `'` in fallback values.\n *                             Use this when the input is JS/TS source so that\n *                             injected quotes don't break string literals.\n * @return                     The value with fallbacks injected.\n */\nexport function addFallbackToVar(\n\tcssValue: string,\n\ttokenFallbacks: Record< string, string >,\n\t{ escapeQuotes = false }: { escapeQuotes?: boolean } = {}\n): string {\n\treturn cssValue.replace(\n\t\t/var\\(\\s*(--wpds-[\\w-]+)\\s*\\)/g,\n\t\t( match, tokenName: string ) => {\n\t\t\tlet fallback = tokenFallbacks[ tokenName ];\n\t\t\tif ( fallback === undefined ) {\n\t\t\t\treturn match;\n\t\t\t}\n\t\t\tif ( escapeQuotes ) {\n\t\t\t\tfallback = fallback\n\t\t\t\t\t.replaceAll( '\"', '\\\\\"' )\n\t\t\t\t\t.replaceAll( \"'\", \"\\\\'\" );\n\t\t\t}\n\t\t\treturn `var(${ tokenName }, ${ fallback })`;\n\t\t}\n\t);\n}\n"],
+  "mappings": ";AAmBO,SAAS,iBACf,UACA,gBACA,EAAE,eAAe,MAAM,IAAgC,CAAC,GAC/C;AACT,SAAO,SAAS;AAAA,IACf;AAAA,IACA,CAAE,OAAO,cAAuB;AAC/B,UAAI,WAAW,eAAgB,SAAU;AACzC,UAAK,aAAa,QAAY;AAC7B,eAAO;AAAA,MACR;AACA,UAAK,cAAe;AACnB,mBAAW,SACT,WAAY,KAAK,KAAM,EACvB,WAAY,KAAK,KAAM;AAAA,MAC1B;AACA,aAAO,OAAQ,SAAU,KAAM,QAAS;AAAA,IACzC;AAAA,EACD;AACD;",
   "names": []
 }

package/build-module/postcss-plugins/ds-token-fallbacks.mjs

@@ -1,12 +1,18 @@
 // packages/theme/src/postcss-plugins/ds-token-fallbacks.mjs
 import _tokenFallbacks from "../prebuilt/js/design-token-fallbacks.mjs";
 var tokenFallbacks = _tokenFallbacks;
-function addFallbackToVar(cssValue) {
+function addFallbackToVar(cssValue, { escapeQuotes = false } = {}) {
   return cssValue.replace(
     /var\(\s*(--wpds-[\w-]+)\s*\)/g,
     (match, tokenName) => {
-      const fallback = tokenFallbacks[tokenName];
-      return fallback !== void 0 ? `var(${tokenName}, ${fallback})` : match;
+      let fallback = tokenFallbacks[tokenName];
+      if (fallback === void 0) {
+        return match;
+      }
+      if (escapeQuotes) {
+        fallback = fallback.replaceAll('"', '\\"').replaceAll("'", "\\'");
+      }
+      return `var(${tokenName}, ${fallback})`;
     }
   );
 }

package/build-module/postcss-plugins/ds-token-fallbacks.mjs.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/postcss-plugins/ds-token-fallbacks.mjs"],
-  "sourcesContent": ["import _tokenFallbacks from '../prebuilt/js/design-token-fallbacks.mjs';\n\n/** @type {Record<string, string>} */\nconst tokenFallbacks = _tokenFallbacks;\n\n/**\n * Replace bare `var(--wpds-*)` references in a CSS value string with\n * `var(--wpds-*, <fallback>)` using the generated token fallback map.\n *\n * Existing fallbacks (i.e. var() calls that already contain a comma) are\n * left untouched, making the function safe to run multiple times.\n *\n * NOTE: The regex and replacement logic here mirrors `add-fallback-to-var.ts`.\n * If you update one, update the other to match.\n *\n * @param {string} cssValue A CSS declaration value.\n * @return {string} The value with fallbacks injected.\n */\nexport function addFallbackToVar( cssValue ) {\n\treturn cssValue.replace(\n\t\t/var\\(\\s*(--wpds-[\\w-]+)\\s*\\)/g,\n\t\t( match, tokenName ) => {\n\t\t\tconst fallback = tokenFallbacks[ tokenName ];\n\t\t\treturn fallback !== undefined\n\t\t\t\t? `var(${ tokenName }, ${ fallback })`\n\t\t\t\t: match;\n\t\t}\n\t);\n}\n"],
-  "mappings": ";AAAA,OAAO,qBAAqB;AAG5B,IAAM,iBAAiB;AAehB,SAAS,iBAAkB,UAAW;AAC5C,SAAO,SAAS;AAAA,IACf;AAAA,IACA,CAAE,OAAO,cAAe;AACvB,YAAM,WAAW,eAAgB,SAAU;AAC3C,aAAO,aAAa,SACjB,OAAQ,SAAU,KAAM,QAAS,MACjC;AAAA,IACJ;AAAA,EACD;AACD;",
+  "sourcesContent": ["import _tokenFallbacks from '../prebuilt/js/design-token-fallbacks.mjs';\n\n/** @type {Record<string, string>} */\nconst tokenFallbacks = _tokenFallbacks;\n\n/**\n * Replace bare `var(--wpds-*)` references in a CSS value string with\n * `var(--wpds-*, <fallback>)` using the generated token fallback map.\n *\n * Existing fallbacks (i.e. var() calls that already contain a comma) are\n * left untouched, making the function safe to run multiple times.\n *\n * NOTE: The regex and replacement logic here mirrors `add-fallback-to-var.ts`.\n * If you update one, update the other to match.\n *\n * @param {string}  cssValue               A CSS declaration value.\n * @param {Object}  [options]              Options.\n * @param {boolean} [options.escapeQuotes] When true, escape `\"` and `'` in\n *                                         fallback values. Use this when the\n *                                         input is JS/TS source so that\n *                                         injected quotes don't break string\n *                                         literals. JS will unescape them at\n *                                         parse time, so the browser's CSS\n *                                         engine still sees the correct value.\n * @return {string}                        The value with fallbacks injected.\n */\nexport function addFallbackToVar( cssValue, { escapeQuotes = false } = {} ) {\n\treturn cssValue.replace(\n\t\t/var\\(\\s*(--wpds-[\\w-]+)\\s*\\)/g,\n\t\t( match, tokenName ) => {\n\t\t\tlet fallback = tokenFallbacks[ tokenName ];\n\t\t\tif ( fallback === undefined ) {\n\t\t\t\treturn match;\n\t\t\t}\n\t\t\tif ( escapeQuotes ) {\n\t\t\t\tfallback = fallback\n\t\t\t\t\t.replaceAll( '\"', '\\\\\"' )\n\t\t\t\t\t.replaceAll( \"'\", \"\\\\'\" );\n\t\t\t}\n\t\t\treturn `var(${ tokenName }, ${ fallback })`;\n\t\t}\n\t);\n}\n"],
+  "mappings": ";AAAA,OAAO,qBAAqB;AAG5B,IAAM,iBAAiB;AAuBhB,SAAS,iBAAkB,UAAU,EAAE,eAAe,MAAM,IAAI,CAAC,GAAI;AAC3E,SAAO,SAAS;AAAA,IACf;AAAA,IACA,CAAE,OAAO,cAAe;AACvB,UAAI,WAAW,eAAgB,SAAU;AACzC,UAAK,aAAa,QAAY;AAC7B,eAAO;AAAA,MACR;AACA,UAAK,cAAe;AACnB,mBAAW,SACT,WAAY,KAAK,KAAM,EACvB,WAAY,KAAK,KAAM;AAAA,MAC1B;AACA,aAAO,OAAQ,SAAU,KAAM,QAAS;AAAA,IACzC;AAAA,EACD;AACD;",
   "names": []
 }

package/build-module/stylelint-plugins/no-token-fallback-values.mjs

@@ -0,0 +1,43 @@
+// packages/theme/src/stylelint-plugins/no-token-fallback-values.mjs
+import stylelint from "stylelint";
+var {
+  createPlugin,
+  utils: { report, ruleMessages, validateOptions }
+} = stylelint;
+var ruleName = "plugin-wpds/no-token-fallback-values";
+var varWithFallbackRegex = /var\(\s*(--wpds-[\w-]+)\s*,/g;
+var messages = ruleMessages(ruleName, {
+  rejected: (tokenName) => `Do not add a fallback value for Design System token '${tokenName}'. Fallbacks are injected automatically at build time.`
+});
+var ruleFunction = (primary) => {
+  return (root, result) => {
+    const validOptions = validateOptions(result, ruleName, {
+      actual: primary,
+      possible: [true]
+    });
+    if (!validOptions) {
+      return;
+    }
+    root.walkDecls((ruleNode) => {
+      const { value } = ruleNode;
+      let match;
+      varWithFallbackRegex.lastIndex = 0;
+      while ((match = varWithFallbackRegex.exec(value)) !== null) {
+        report({
+          message: messages.rejected(match[1]),
+          node: ruleNode,
+          word: match[0],
+          result,
+          ruleName
+        });
+      }
+    });
+  };
+};
+ruleFunction.ruleName = ruleName;
+ruleFunction.messages = messages;
+var no_token_fallback_values_default = createPlugin(ruleName, ruleFunction);
+export {
+  no_token_fallback_values_default as default
+};
+//# sourceMappingURL=no-token-fallback-values.mjs.map

package/build-module/stylelint-plugins/no-token-fallback-values.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/stylelint-plugins/no-token-fallback-values.mjs"],
+  "sourcesContent": ["import stylelint from 'stylelint';\n\nconst {\n\tcreatePlugin,\n\tutils: { report, ruleMessages, validateOptions },\n} = stylelint;\n\nconst ruleName = 'plugin-wpds/no-token-fallback-values';\n\n/**\n * Matches `var(--wpds-<name>,` \u2014 the comma signals a fallback value.\n * Captures the token name (e.g. `--wpds-color-fg-content-neutral`).\n */\nconst varWithFallbackRegex = /var\\(\\s*(--wpds-[\\w-]+)\\s*,/g;\n\nconst messages = ruleMessages( ruleName, {\n\trejected: ( tokenName ) =>\n\t\t`Do not add a fallback value for Design System token '${ tokenName }'. Fallbacks are injected automatically at build time.`,\n} );\n\n/** @type {import('stylelint').Rule} */\nconst ruleFunction = ( primary ) => {\n\treturn ( root, result ) => {\n\t\tconst validOptions = validateOptions( result, ruleName, {\n\t\t\tactual: primary,\n\t\t\tpossible: [ true ],\n\t\t} );\n\n\t\tif ( ! validOptions ) {\n\t\t\treturn;\n\t\t}\n\n\t\troot.walkDecls( ( ruleNode ) => {\n\t\t\tconst { value } = ruleNode;\n\n\t\t\tlet match;\n\t\t\tvarWithFallbackRegex.lastIndex = 0;\n\t\t\twhile ( ( match = varWithFallbackRegex.exec( value ) ) !== null ) {\n\t\t\t\treport( {\n\t\t\t\t\tmessage: messages.rejected( match[ 1 ] ),\n\t\t\t\t\tnode: ruleNode,\n\t\t\t\t\tword: match[ 0 ],\n\t\t\t\t\tresult,\n\t\t\t\t\truleName,\n\t\t\t\t} );\n\t\t\t}\n\t\t} );\n\t};\n};\n\nruleFunction.ruleName = ruleName;\nruleFunction.messages = messages;\n\n/** @type {import('stylelint').Plugin} */\nexport default createPlugin( ruleName, ruleFunction );\n"],
+  "mappings": ";AAAA,OAAO,eAAe;AAEtB,IAAM;AAAA,EACL;AAAA,EACA,OAAO,EAAE,QAAQ,cAAc,gBAAgB;AAChD,IAAI;AAEJ,IAAM,WAAW;AAMjB,IAAM,uBAAuB;AAE7B,IAAM,WAAW,aAAc,UAAU;AAAA,EACxC,UAAU,CAAE,cACX,wDAAyD,SAAU;AACrE,CAAE;AAGF,IAAM,eAAe,CAAE,YAAa;AACnC,SAAO,CAAE,MAAM,WAAY;AAC1B,UAAM,eAAe,gBAAiB,QAAQ,UAAU;AAAA,MACvD,QAAQ;AAAA,MACR,UAAU,CAAE,IAAK;AAAA,IAClB,CAAE;AAEF,QAAK,CAAE,cAAe;AACrB;AAAA,IACD;AAEA,SAAK,UAAW,CAAE,aAAc;AAC/B,YAAM,EAAE,MAAM,IAAI;AAElB,UAAI;AACJ,2BAAqB,YAAY;AACjC,cAAU,QAAQ,qBAAqB,KAAM,KAAM,OAAQ,MAAO;AACjE,eAAQ;AAAA,UACP,SAAS,SAAS,SAAU,MAAO,CAAE,CAAE;AAAA,UACvC,MAAM;AAAA,UACN,MAAM,MAAO,CAAE;AAAA,UACf;AAAA,UACA;AAAA,QACD,CAAE;AAAA,MACH;AAAA,IACD,CAAE;AAAA,EACH;AACD;AAEA,aAAa,WAAW;AACxB,aAAa,WAAW;AAGxB,IAAO,mCAAQ,aAAc,UAAU,YAAa;",
+  "names": []
+}

package/build-module/vite-plugins/vite-ds-token-fallbacks.mjs

@@ -12,7 +12,10 @@ var plugin = () => ({
     if (!code.includes("--wpds-")) {
       return null;
     }
-    return { code: addFallbackToVar(code), map: null };
+    return {
+      code: addFallbackToVar(code, { escapeQuotes: true }),
+      map: null
+    };
   }
 });
 var vite_ds_token_fallbacks_default = plugin;

package/build-module/vite-plugins/vite-ds-token-fallbacks.mjs.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/vite-plugins/vite-ds-token-fallbacks.mjs"],
-  "sourcesContent": ["import { addFallbackToVar } from '../postcss-plugins/ds-token-fallbacks.mjs';\n\n/**\n * Vite plugin that injects design-system token fallbacks into JS/TS files.\n *\n * Replaces bare `var(--wpds-*)` references in string literals with\n * `var(--wpds-*, <fallback>)` so components render correctly without\n * a ThemeProvider.\n */\nconst plugin = () => ( {\n\tname: 'ds-token-fallbacks-js',\n\ttransform( code, id ) {\n\t\tif ( ! /\\.[mc]?[jt]sx?$/.test( id ) ) {\n\t\t\treturn null;\n\t\t}\n\t\tif ( id.includes( 'node_modules' ) ) {\n\t\t\treturn null;\n\t\t}\n\t\tif ( ! code.includes( '--wpds-' ) ) {\n\t\t\treturn null;\n\t\t}\n\t\t// Sourcemap omitted: replacements are small, inline substitutions\n\t\t// that preserve line structure, so the debugging impact is negligible.\n\t\treturn { code: addFallbackToVar( code ), map: null };\n\t},\n} );\n\nexport default plugin;\n"],
-  "mappings": ";AAAA,SAAS,wBAAwB;AASjC,IAAM,SAAS,OAAQ;AAAA,EACtB,MAAM;AAAA,EACN,UAAW,MAAM,IAAK;AACrB,QAAK,CAAE,kBAAkB,KAAM,EAAG,GAAI;AACrC,aAAO;AAAA,IACR;AACA,QAAK,GAAG,SAAU,cAAe,GAAI;AACpC,aAAO;AAAA,IACR;AACA,QAAK,CAAE,KAAK,SAAU,SAAU,GAAI;AACnC,aAAO;AAAA,IACR;AAGA,WAAO,EAAE,MAAM,iBAAkB,IAAK,GAAG,KAAK,KAAK;AAAA,EACpD;AACD;AAEA,IAAO,kCAAQ;",
+  "sourcesContent": ["import { addFallbackToVar } from '../postcss-plugins/ds-token-fallbacks.mjs';\n\n/**\n * Vite plugin that injects design-system token fallbacks into JS/TS files.\n *\n * Replaces bare `var(--wpds-*)` references in string literals with\n * `var(--wpds-*, <fallback>)` so components render correctly without\n * a ThemeProvider.\n */\nconst plugin = () => ( {\n\tname: 'ds-token-fallbacks-js',\n\ttransform( code, id ) {\n\t\tif ( ! /\\.[mc]?[jt]sx?$/.test( id ) ) {\n\t\t\treturn null;\n\t\t}\n\t\tif ( id.includes( 'node_modules' ) ) {\n\t\t\treturn null;\n\t\t}\n\t\tif ( ! code.includes( '--wpds-' ) ) {\n\t\t\treturn null;\n\t\t}\n\t\t// Sourcemap omitted: replacements are small, inline substitutions\n\t\t// that preserve line structure, so the debugging impact is negligible.\n\t\treturn {\n\t\t\tcode: addFallbackToVar( code, { escapeQuotes: true } ),\n\t\t\tmap: null,\n\t\t};\n\t},\n} );\n\nexport default plugin;\n"],
+  "mappings": ";AAAA,SAAS,wBAAwB;AASjC,IAAM,SAAS,OAAQ;AAAA,EACtB,MAAM;AAAA,EACN,UAAW,MAAM,IAAK;AACrB,QAAK,CAAE,kBAAkB,KAAM,EAAG,GAAI;AACrC,aAAO;AAAA,IACR;AACA,QAAK,GAAG,SAAU,cAAe,GAAI;AACpC,aAAO;AAAA,IACR;AACA,QAAK,CAAE,KAAK,SAAU,SAAU,GAAI;AACnC,aAAO;AAAA,IACR;AAGA,WAAO;AAAA,MACN,MAAM,iBAAkB,MAAM,EAAE,cAAc,KAAK,CAAE;AAAA,MACrD,KAAK;AAAA,IACN;AAAA,EACD;AACD;AAEA,IAAO,kCAAQ;",
   "names": []
 }

package/build-types/color-ramps/stories/index.story.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.story.d.ts","sourceRoot":"","sources":["../../../src/color-ramps/stories/index.story.tsx"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAS5D,QAAA,MAAM,QAAQ,GAAK,OAAO;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC1B,gCAEA,CAAC;AAEF,QAAA,MAAM,IAAI,EAAE,IAAI,CAAE,OAAO,QAAQ,CAmBhC,CAAC;AACF,eAAe,IAAI,CAAC;AAEpB,eAAO,MAAM,OAAO,EAAE,QAAQ,CAAE,OAAO,QAAQ,CA+H9C,CAAC;AAEF,eAAO,MAAM,kBAAkB,EAAE,QAAQ,CAAE,OAAO,QAAQ,CA4FzD,CAAC"}
+{"version":3,"file":"index.story.d.ts","sourceRoot":"","sources":["../../../src/color-ramps/stories/index.story.tsx"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAS5D,QAAA,MAAM,QAAQ,GAAK,OAAO;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC1B,gCAEA,CAAC;AAEF,QAAA,MAAM,IAAI,EAAE,IAAI,CAAE,OAAO,QAAQ,CAkBhC,CAAC;AACF,eAAe,IAAI,CAAC;AAEpB,eAAO,MAAM,OAAO,EAAE,QAAQ,CAAE,OAAO,QAAQ,CA+H9C,CAAC;AAEF,eAAO,MAAM,kBAAkB,EAAE,QAAQ,CAAE,OAAO,QAAQ,CA4FzD,CAAC"}

package/build-types/postcss-plugins/add-fallback-to-var.d.ts

@@ -9,9 +9,15 @@
  * NOTE: The regex and replacement logic here is mirrored in
  * `ds-token-fallbacks.mjs`. If you update one, update the other to match.
  *
- * @param cssValue       A CSS declaration value.
- * @param tokenFallbacks Map of CSS variable names to their fallback expressions.
- * @return The value with fallbacks injected.
+ * @param cssValue             A CSS declaration value.
+ * @param tokenFallbacks       Map of CSS variable names to their fallback expressions.
+ * @param options              Options.
+ * @param options.escapeQuotes When true, escape `"` and `'` in fallback values.
+ *                             Use this when the input is JS/TS source so that
+ *                             injected quotes don't break string literals.
+ * @return                     The value with fallbacks injected.
  */
-export declare function addFallbackToVar(cssValue: string, tokenFallbacks: Record<string, string>): string;
+export declare function addFallbackToVar(cssValue: string, tokenFallbacks: Record<string, string>, { escapeQuotes }?: {
+    escapeQuotes?: boolean;
+}): string;
 //# sourceMappingURL=add-fallback-to-var.d.ts.map

package/build-types/postcss-plugins/add-fallback-to-var.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"add-fallback-to-var.d.ts","sourceRoot":"","sources":["../../src/postcss-plugins/add-fallback-to-var.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAC/B,QAAQ,EAAE,MAAM,EAChB,cAAc,EAAE,MAAM,CAAE,MAAM,EAAE,MAAM,CAAE,GACtC,MAAM,CAUR"}
+{"version":3,"file":"add-fallback-to-var.d.ts","sourceRoot":"","sources":["../../src/postcss-plugins/add-fallback-to-var.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,gBAAgB,CAC/B,QAAQ,EAAE,MAAM,EAChB,cAAc,EAAE,MAAM,CAAE,MAAM,EAAE,MAAM,CAAE,EACxC,EAAE,YAAoB,EAAE,GAAE;IAAE,YAAY,CAAC,EAAE,OAAO,CAAA;CAAO,GACvD,MAAM,CAgBR"}

package/build-types/postcss-plugins/ds-token-fallbacks.d.mts

@@ -8,8 +8,18 @@
  * NOTE: The regex and replacement logic here mirrors `add-fallback-to-var.ts`.
  * If you update one, update the other to match.
  *
- * @param {string} cssValue A CSS declaration value.
- * @return {string} The value with fallbacks injected.
+ * @param {string}  cssValue               A CSS declaration value.
+ * @param {Object}  [options]              Options.
+ * @param {boolean} [options.escapeQuotes] When true, escape `"` and `'` in
+ *                                         fallback values. Use this when the
+ *                                         input is JS/TS source so that
+ *                                         injected quotes don't break string
+ *                                         literals. JS will unescape them at
+ *                                         parse time, so the browser's CSS
+ *                                         engine still sees the correct value.
+ * @return {string}                        The value with fallbacks injected.
  */
-export function addFallbackToVar(cssValue: string): string;
+export function addFallbackToVar(cssValue: string, { escapeQuotes }?: {
+    escapeQuotes?: boolean | undefined;
+}): string;
 //# sourceMappingURL=ds-token-fallbacks.d.mts.map

package/build-types/postcss-plugins/ds-token-fallbacks.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"ds-token-fallbacks.d.mts","sourceRoot":"","sources":["../../src/postcss-plugins/ds-token-fallbacks.mjs"],"names":[],"mappings":"AAKA;;;;;;;;;;;;GAYG;AACH,2CAHW,MAAM,GACL,MAAM,CAYjB"}
+{"version":3,"file":"ds-token-fallbacks.d.mts","sourceRoot":"","sources":["../../src/postcss-plugins/ds-token-fallbacks.mjs"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,2CAXW,MAAM,qBAEd;IAA0B,YAAY;CAOtC,GAAS,MAAM,CAkBjB"}

package/build-types/stylelint-plugins/no-token-fallback-values.d.mts

@@ -0,0 +1,4 @@
+declare const _default: stylelint.Plugin;
+export default _default;
+import stylelint from 'stylelint';
+//# sourceMappingURL=no-token-fallback-values.d.mts.map

package/build-types/stylelint-plugins/no-token-fallback-values.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"no-token-fallback-values.d.mts","sourceRoot":"","sources":["../../src/stylelint-plugins/no-token-fallback-values.mjs"],"names":[],"mappings":";;sBAAsB,WAAW"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@wordpress/theme",
-	"version": "0.8.1-next.v.202603161435.0+ab4981c4f",
+	"version": "0.9.0",
 	"description": "Theme and context provider for the WordPress Design System.",
 	"author": "The WordPress Contributors",
 	"license": "GPL-2.0-or-later",
@@ -68,6 +68,11 @@
 			"import": "./src/stylelint-plugins/no-setting-wpds-custom-properties.mjs",
 			"default": "./build/stylelint-plugins/no-setting-wpds-custom-properties.cjs"
 		},
+		"./stylelint-plugins/no-token-fallback-values": {
+			"types": "./build-types/stylelint-plugins/no-token-fallback-values.d.ts",
+			"import": "./src/stylelint-plugins/no-token-fallback-values.mjs",
+			"default": "./build/stylelint-plugins/no-token-fallback-values.cjs"
+		},
 		"./package.json": "./package.json"
 	},
 	"react-native": "src/index",
@@ -79,13 +84,13 @@
 		"build-module/color-ramps/lib/register-color-spaces.mjs"
 	],
 	"dependencies": {
-		"@wordpress/element": "^6.41.1-next.v.202603161435.0+ab4981c4f",
-		"@wordpress/private-apis": "^1.41.1-next.v.202603161435.0+ab4981c4f",
+		"@wordpress/element": "^6.42.0",
+		"@wordpress/private-apis": "^1.42.0",
 		"colorjs.io": "^0.6.0",
 		"memize": "^2.1.0"
 	},
 	"devDependencies": {
-		"@storybook/react-vite": "^10.1.11",
+		"@storybook/react-vite": "^10.2.8",
 		"@terrazzo/cli": "^0.10.2",
 		"@terrazzo/plugin-css": "^0.10.2",
 		"@terrazzo/token-tools": "^0.10.2",
@@ -94,7 +99,7 @@
 		"@types/node": "^20.17.10",
 		"esbuild": "^0.27.2",
 		"esbuild-esm-loader": "^0.3.3",
-		"storybook": "^10.1.11"
+		"storybook": "^10.2.8"
 	},
 	"peerDependencies": {
 		"react": "^18.0.0",
@@ -116,5 +121,5 @@
 		"build": "npm run build:tokens && npm run build:default-ramps && npm run prelint:js",
 		"postbuild": "prettier --write tokens/color.json tokens/modes src/prebuilt src/color-ramps/lib/default-ramps.ts docs"
 	},
-	"gitHead": "748f4e4564fcc0e6ae90200d90bb993a3cef5828"
+	"gitHead": "c20787b1778ae64c2db65643b1c236309d68e6ba"
 }

package/src/color-ramps/stories/index.story.tsx

@@ -36,7 +36,6 @@ const meta: Meta< typeof ColorGen > = {
 		controls: { expanded: true },
 		docs: { canvas: { sourceState: 'shown' } },
 	},
-	tags: [ 'status-experimental' ],
 };
 export default meta;
 

package/src/esbuild-plugins/esbuild-ds-token-fallbacks.mjs

@@ -37,7 +37,7 @@ const plugin = {
 			const ext = args.path.match( /(\.[^.]+)$/ )?.[ 1 ] || '.js';
 
 			return {
-				contents: addFallbackToVar( source ),
+				contents: addFallbackToVar( source, { escapeQuotes: true } ),
 				loader: LOADER_MAP[ ext ] || 'jsx',
 			};
 		} );

package/src/postcss-plugins/add-fallback-to-var.ts

@@ -9,21 +9,32 @@
  * NOTE: The regex and replacement logic here is mirrored in
  * `ds-token-fallbacks.mjs`. If you update one, update the other to match.
  *
- * @param cssValue       A CSS declaration value.
- * @param tokenFallbacks Map of CSS variable names to their fallback expressions.
- * @return The value with fallbacks injected.
+ * @param cssValue             A CSS declaration value.
+ * @param tokenFallbacks       Map of CSS variable names to their fallback expressions.
+ * @param options              Options.
+ * @param options.escapeQuotes When true, escape `"` and `'` in fallback values.
+ *                             Use this when the input is JS/TS source so that
+ *                             injected quotes don't break string literals.
+ * @return                     The value with fallbacks injected.
  */
 export function addFallbackToVar(
 	cssValue: string,
-	tokenFallbacks: Record< string, string >
+	tokenFallbacks: Record< string, string >,
+	{ escapeQuotes = false }: { escapeQuotes?: boolean } = {}
 ): string {
 	return cssValue.replace(
 		/var\(\s*(--wpds-[\w-]+)\s*\)/g,
 		( match, tokenName: string ) => {
-			const fallback = tokenFallbacks[ tokenName ];
-			return fallback !== undefined
-				? `var(${ tokenName }, ${ fallback })`
-				: match;
+			let fallback = tokenFallbacks[ tokenName ];
+			if ( fallback === undefined ) {
+				return match;
+			}
+			if ( escapeQuotes ) {
+				fallback = fallback
+					.replaceAll( '"', '\\"' )
+					.replaceAll( "'", "\\'" );
+			}
+			return `var(${ tokenName }, ${ fallback })`;
 		}
 	);
 }

package/src/postcss-plugins/ds-token-fallbacks.mjs

@@ -13,17 +13,31 @@ const tokenFallbacks = _tokenFallbacks;
  * NOTE: The regex and replacement logic here mirrors `add-fallback-to-var.ts`.
  * If you update one, update the other to match.
  *
- * @param {string} cssValue A CSS declaration value.
- * @return {string} The value with fallbacks injected.
+ * @param {string}  cssValue               A CSS declaration value.
+ * @param {Object}  [options]              Options.
+ * @param {boolean} [options.escapeQuotes] When true, escape `"` and `'` in
+ *                                         fallback values. Use this when the
+ *                                         input is JS/TS source so that
+ *                                         injected quotes don't break string
+ *                                         literals. JS will unescape them at
+ *                                         parse time, so the browser's CSS
+ *                                         engine still sees the correct value.
+ * @return {string}                        The value with fallbacks injected.
  */
-export function addFallbackToVar( cssValue ) {
+export function addFallbackToVar( cssValue, { escapeQuotes = false } = {} ) {
 	return cssValue.replace(
 		/var\(\s*(--wpds-[\w-]+)\s*\)/g,
 		( match, tokenName ) => {
-			const fallback = tokenFallbacks[ tokenName ];
-			return fallback !== undefined
-				? `var(${ tokenName }, ${ fallback })`
-				: match;
+			let fallback = tokenFallbacks[ tokenName ];
+			if ( fallback === undefined ) {
+				return match;
+			}
+			if ( escapeQuotes ) {
+				fallback = fallback
+					.replaceAll( '"', '\\"' )
+					.replaceAll( "'", "\\'" );
+			}
+			return `var(${ tokenName }, ${ fallback })`;
 		}
 	);
 }

package/src/postcss-plugins/test/add-fallback-to-var.test.ts

@@ -8,6 +8,9 @@ const mockFallbacks: Record< string, string > = {
 		'var(--wp-admin-theme-color, #3858e9)',
 	'--wpds-color-bg-interactive-brand-strong-active':
 		'color-mix(in oklch, var(--wp-admin-theme-color, #3858e9) 92%, black)',
+	'--wpds-font-family-body':
+		'-apple-system, system-ui, "Segoe UI", "Roboto", "Oxygen-Sans", "Ubuntu", "Cantarell", "Helvetica Neue", sans-serif',
+	'--wpds-font-family-mono': '"Menlo", "Consolas", monaco, monospace',
 };
 
 describe( 'addFallbackToVar', () => {
@@ -88,4 +91,53 @@ describe( 'addFallbackToVar', () => {
 		const second = addFallbackToVar( first, mockFallbacks );
 		expect( second ).toBe( first );
 	} );
+
+	describe( 'escapeQuotes', () => {
+		it( 'does not escape quotes by default', () => {
+			expect(
+				addFallbackToVar(
+					'var(--wpds-font-family-body)',
+					mockFallbacks
+				)
+			).toBe(
+				'var(--wpds-font-family-body, -apple-system, system-ui, "Segoe UI", "Roboto", "Oxygen-Sans", "Ubuntu", "Cantarell", "Helvetica Neue", sans-serif)'
+			);
+		} );
+
+		it( 'escapes double quotes when enabled', () => {
+			expect(
+				addFallbackToVar(
+					'var(--wpds-font-family-mono)',
+					mockFallbacks,
+					{ escapeQuotes: true }
+				)
+			).toBe(
+				'var(--wpds-font-family-mono, \\"Menlo\\", \\"Consolas\\", monaco, monospace)'
+			);
+		} );
+
+		it( 'escapes both double and single quotes in the same value', () => {
+			const fallbacks: Record< string, string > = {
+				'--wpds-test-token': `"double" and 'single'`,
+			};
+			const result = addFallbackToVar(
+				'var(--wpds-test-token)',
+				fallbacks,
+				{ escapeQuotes: true }
+			);
+			expect( result ).toBe(
+				`var(--wpds-test-token, \\"double\\" and \\'single\\')`
+			);
+		} );
+
+		it( 'leaves values without quotes unchanged when enabled', () => {
+			expect(
+				addFallbackToVar(
+					'var(--wpds-border-radius-sm)',
+					mockFallbacks,
+					{ escapeQuotes: true }
+				)
+			).toBe( 'var(--wpds-border-radius-sm, 2px)' );
+		} );
+	} );
 } );

package/src/stories/index.story.tsx

@@ -34,7 +34,7 @@ const meta: Meta< typeof ThemeProvider > = {
 		controls: { expanded: true },
 		docs: { canvas: { sourceState: 'shown' } },
 	},
-	tags: [ 'status-experimental' ],
+	tags: [ 'status-private' ],
 };
 export default meta;
 

package/src/stylelint-plugins/no-token-fallback-values.mjs

@@ -0,0 +1,55 @@
+import stylelint from 'stylelint';
+
+const {
+	createPlugin,
+	utils: { report, ruleMessages, validateOptions },
+} = stylelint;
+
+const ruleName = 'plugin-wpds/no-token-fallback-values';
+
+/**
+ * Matches `var(--wpds-<name>,` — the comma signals a fallback value.
+ * Captures the token name (e.g. `--wpds-color-fg-content-neutral`).
+ */
+const varWithFallbackRegex = /var\(\s*(--wpds-[\w-]+)\s*,/g;
+
+const messages = ruleMessages( ruleName, {
+	rejected: ( tokenName ) =>
+		`Do not add a fallback value for Design System token '${ tokenName }'. Fallbacks are injected automatically at build time.`,
+} );
+
+/** @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;
+
+			let match;
+			varWithFallbackRegex.lastIndex = 0;
+			while ( ( match = varWithFallbackRegex.exec( value ) ) !== null ) {
+				report( {
+					message: messages.rejected( match[ 1 ] ),
+					node: ruleNode,
+					word: match[ 0 ],
+					result,
+					ruleName,
+				} );
+			}
+		} );
+	};
+};
+
+ruleFunction.ruleName = ruleName;
+ruleFunction.messages = messages;
+
+/** @type {import('stylelint').Plugin} */
+export default createPlugin( ruleName, ruleFunction );

package/src/stylelint-plugins/test/.stylelintrc.no-setting-wpds-custom-properties.json

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

package/src/stylelint-plugins/test/.stylelintrc.no-token-fallback-values.json

@@ -0,0 +1,6 @@
+{
+	"plugins": [ "../no-token-fallback-values.mjs" ],
+	"rules": {
+		"plugin-wpds/no-token-fallback-values": true
+	}
+}

package/src/stylelint-plugins/test/.stylelintrc.no-unknown-ds-tokens.json

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

package/src/stylelint-plugins/test/__snapshots__/no-token-fallback-values.test.ts.snap

@@ -0,0 +1,60 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`flags warnings with invalid css (wpds fallbacks) snapshot matches warnings 1`] = `
+[
+  {
+    "column": 9,
+    "endColumn": 45,
+    "endLine": 3,
+    "line": 3,
+    "rule": "plugin-wpds/no-token-fallback-values",
+    "severity": "error",
+    "text": "Do not add a fallback value for Design System token '--wpds-color-fg-content-neutral'. Fallbacks are injected automatically at build time. (plugin-wpds/no-token-fallback-values)",
+  },
+  {
+    "column": 20,
+    "endColumn": 61,
+    "endLine": 4,
+    "line": 4,
+    "rule": "plugin-wpds/no-token-fallback-values",
+    "severity": "error",
+    "text": "Do not add a fallback value for Design System token '--wpds-color-bg-surface-neutral-weak'. Fallbacks are injected automatically at build time. (plugin-wpds/no-token-fallback-values)",
+  },
+  {
+    "column": 17,
+    "endColumn": 45,
+    "endLine": 5,
+    "line": 5,
+    "rule": "plugin-wpds/no-token-fallback-values",
+    "severity": "error",
+    "text": "Do not add a fallback value for Design System token '--wpds-border-radius-sm'. Fallbacks are injected automatically at build time. (plugin-wpds/no-token-fallback-values)",
+  },
+  {
+    "column": 11,
+    "endColumn": 41,
+    "endLine": 10,
+    "line": 10,
+    "rule": "plugin-wpds/no-token-fallback-values",
+    "severity": "error",
+    "text": "Do not add a fallback value for Design System token '--wpds-border-width-focus'. Fallbacks are injected automatically at build time. (plugin-wpds/no-token-fallback-values)",
+  },
+  {
+    "column": 53,
+    "endColumn": 89,
+    "endLine": 10,
+    "line": 10,
+    "rule": "plugin-wpds/no-token-fallback-values",
+    "severity": "error",
+    "text": "Do not add a fallback value for Design System token '--wpds-color-stroke-focus-brand'. Fallbacks are injected automatically at build time. (plugin-wpds/no-token-fallback-values)",
+  },
+  {
+    "column": 32,
+    "endColumn": 68,
+    "endLine": 15,
+    "line": 15,
+    "rule": "plugin-wpds/no-token-fallback-values",
+    "severity": "error",
+    "text": "Do not add a fallback value for Design System token '--wpds-color-fg-content-neutral'. Fallbacks are injected automatically at build time. (plugin-wpds/no-token-fallback-values)",
+  },
+]
+`;

package/src/stylelint-plugins/test/fixtures/no-token-fallback-values-invalid.css

@@ -0,0 +1,16 @@
+/* Invalid: Using wpds tokens with fallbacks */
+.with-fallback {
+	color: var(--wpds-color-fg-content-neutral, #1e1e1e);
+	background-color: var(--wpds-color-bg-surface-neutral-weak, #f0f0f0);
+	border-radius: var(--wpds-border-radius-sm, 2px);
+}
+
+/* Invalid: Fallbacks in complex values */
+.complex {
+	outline: var(--wpds-border-width-focus, 2px) solid var(--wpds-color-stroke-focus-brand, #0073aa);
+}
+
+/* Invalid: A wpds token with a fallback, even when nested inside another var() */
+.nested-with-fallback {
+	color: var(--my-custom-color, var(--wpds-color-fg-content-neutral, #1e1e1e));
+}

package/src/stylelint-plugins/test/fixtures/no-token-fallback-values-valid.css

@@ -0,0 +1,18 @@
+/* Valid: Using wpds tokens without fallbacks */
+.example {
+	color: var(--wpds-color-fg-content-neutral);
+	background-color: var(--wpds-color-bg-surface-neutral);
+	border-radius: var(--wpds-border-radius-sm);
+	padding: var(--wpds-dimension-padding-md);
+}
+
+/* Valid: Non-wpds custom properties with fallbacks are fine */
+.other-vars {
+	color: var(--my-custom-color, red);
+	background: var(--some-other-var, #fff);
+}
+
+/* Valid: A wpds token used as a fallback of a non-wpds var, with no comma after the wpds token */
+.nested-no-fallback {
+	color: var(--my-custom-color, var(--wpds-color-fg-content-neutral));
+}

package/src/stylelint-plugins/test/no-setting-wpds-custom-properties.test.ts

@@ -1,11 +1,14 @@
 import { getStylelintResult } from './utils';
 
+const CONFIG = './.stylelintrc.no-setting-wpds-custom-properties.json';
+
 describe( 'flags no warnings with valid wpds custom properties css', () => {
 	let result: ReturnType< typeof getStylelintResult >;
 
 	beforeEach( () => {
 		result = getStylelintResult(
-			'./fixtures/no-setting-wpds-custom-properties-valid.css'
+			'./fixtures/no-setting-wpds-custom-properties-valid.css',
+			CONFIG
 		);
 	} );
 
@@ -25,7 +28,8 @@ describe( 'flags warnings with invalid wpds custom properties css', () => {
 
 	beforeEach( () => {
 		result = getStylelintResult(
-			'./fixtures/no-setting-wpds-custom-properties-invalid.css'
+			'./fixtures/no-setting-wpds-custom-properties-invalid.css',
+			CONFIG
 		);
 	} );
 

package/src/stylelint-plugins/test/no-token-fallback-values.test.ts

@@ -0,0 +1,51 @@
+import { getStylelintResult } from './utils';
+
+const CONFIG = './.stylelintrc.no-token-fallback-values.json';
+
+describe( 'flags no warnings with valid css (no wpds fallbacks)', () => {
+	let result: ReturnType< typeof getStylelintResult >;
+
+	beforeEach( () => {
+		result = getStylelintResult(
+			'./fixtures/no-token-fallback-values-valid.css',
+			CONFIG
+		);
+	} );
+
+	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 css (wpds fallbacks)', () => {
+	let result: ReturnType< typeof getStylelintResult >;
+
+	beforeEach( () => {
+		result = getStylelintResult(
+			'./fixtures/no-token-fallback-values-invalid.css',
+			CONFIG
+		);
+	} );
+
+	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( 6 )
+		);
+	} );
+
+	it( 'snapshot matches warnings', () => {
+		return result.then( ( data ) =>
+			expect( data.results[ 0 ].warnings ).toMatchSnapshot()
+		);
+	} );
+} );

package/src/stylelint-plugins/test/no-unknown-ds-tokens.test.ts

@@ -1,11 +1,14 @@
 import { getStylelintResult } from './utils';
 
+const CONFIG = './.stylelintrc.no-unknown-ds-tokens.json';
+
 describe( 'flags no warnings with valid wpds tokens css', () => {
 	let result: ReturnType< typeof getStylelintResult >;
 
 	beforeEach( () => {
 		result = getStylelintResult(
-			'./fixtures/no-unknown-ds-tokens-valid.css'
+			'./fixtures/no-unknown-ds-tokens-valid.css',
+			CONFIG
 		);
 	} );
 
@@ -25,7 +28,8 @@ describe( 'flags warnings with invalid wpds tokens css', () => {
 
 	beforeEach( () => {
 		result = getStylelintResult(
-			'./fixtures/no-unknown-ds-tokens-invalid.css'
+			'./fixtures/no-unknown-ds-tokens-invalid.css',
+			CONFIG
 		);
 	} );
 

package/src/stylelint-plugins/test/utils/index.ts

@@ -4,17 +4,20 @@ import childProcess from 'node:child_process';
 
 const execute = util.promisify( childProcess.exec );
 
-const generateStylelintCommand = ( filename: string ): string =>
+const generateStylelintCommand = (
+	filename: string,
+	configFile: string
+): string =>
 	'npx stylelint ' +
 	path.resolve( __dirname, '../', filename ) +
 	' -c ' +
-	path.resolve( __dirname, '../', './.stylelintrc.json' ) +
+	path.resolve( __dirname, '../', configFile ) +
 	' --formatter json' +
 	' --ignore-path ' +
 	path.resolve( __dirname, '../', './.stylelintignore' );
 
-export const getStylelintResult = ( filename: string ) =>
-	execute( generateStylelintCommand( filename ) )
+export const getStylelintResult = ( filename: string, configFile: string ) =>
+	execute( generateStylelintCommand( filename, configFile ) )
 		.then( ( { stderr } ) => {
 			return {
 				errored: false,

package/src/vite-plugins/vite-ds-token-fallbacks.mjs

@@ -21,7 +21,10 @@ const plugin = () => ( {
 		}
 		// Sourcemap omitted: replacements are small, inline substitutions
 		// that preserve line structure, so the debugging impact is negligible.
-		return { code: addFallbackToVar( code ), map: null };
+		return {
+			code: addFallbackToVar( code, { escapeQuotes: true } ),
+			map: null,
+		};
 	},
 } );
 

package/src/stylelint-plugins/test/.stylelintrc.json

@@ -1,10 +0,0 @@
-{
-	"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
-	}
-}