Fluent design tokens pipeline

.github/renovate.json

@@ -123,6 +123,14 @@
             "matchPackageNames": [
                 "*"
             ]
+        },
+        {
+            "matchPackageNames": [
+                "@devexpress/design-tokens-internal"
+            ],
+            "automerge": false,
+            "dependencyDashboardApproval": true,
+            "minimumReleaseAge": null
         }
     ],
     "lockFileMaintenance": {

packages/devextreme-scss/.stylelintrc.json

@@ -12,6 +12,10 @@
         "color-function-notation": "legacy",
         "declaration-block-no-redundant-longhand-properties": null,
         "declaration-no-important": true,
+        "declaration-property-value-disallowed-list": [
+            { "/.*/": ["/var\\(\\s*--dxds-/"] },
+            { "message": "Read a design token through the ds bridge (ds.$name), not var(--dxds-…): the bridge fails the build on an unknown name, a raw custom property compiles and degrades silently." }
+        ],
         "font-family-name-quotes": "always-unless-keyword",
         "@stylistic/indentation": [2, { "ignore": ["inside-parens"] }],
         "keyframes-name-pattern": "dx-[a-z0-9-]+",
@@ -69,6 +73,30 @@
             "rules": {
                 "scss/dollar-variable-pattern": "^[a-z][a-z0-9]*(-[a-z0-9]+)*$"
             }
+        },
+        {
+            "comment": "A file that emits rules consumes the widget's own variables, so the token a value comes from is stated once, next to the other variables of that widget. Declaration files are exempted by the override below. `@use … with ()` arguments are at-rule parameters and stay invisible to stylelint; fluent-next-naming.test.ts covers that form.",
+            "files": ["scss/widgets/fluent-next/**/*.scss"],
+            "rules": {
+                "declaration-property-value-disallowed-list": [
+                    { "/.*/": ["/var\\(\\s*--dxds-/", "/var\\(\\s*--dx-/", "/\\bds\\.\\$/"] },
+                    { "message": "Use the widget's own variable here: resolve the design token in _colors.scss or _sizes.scss. A custom property compiles even when its name is wrong." }
+                ]
+            }
+        },
+        {
+            "comment": "Turning a token into a widget variable is what these files are for, so only the raw custom-property form stays banned here.",
+            "files": [
+                "scss/widgets/fluent-next/**/_colors.scss",
+                "scss/widgets/fluent-next/**/_sizes.scss",
+                "scss/widgets/fluent-next/**/_variables.scss"
+            ],
+            "rules": {
+                "declaration-property-value-disallowed-list": [
+                    { "/.*/": ["/var\\(\\s*--dxds-/", "/var\\(\\s*--dx-/"] },
+                    { "message": "Read a design token through the ds bridge (ds.$name), not as a custom property: the bridge fails the build on an unknown name, a custom property compiles and degrades silently." }
+                ]
+            }
         }
     ]
 }

packages/devextreme-scss/build/tokens/build-tokens.mjs

@@ -4,6 +4,11 @@ import { createRequire } from 'node:module';
 import { readdir, readFile, rm } from 'node:fs/promises';
 import StyleDictionary from 'style-dictionary';
 import { registerTransforms } from './transforms.mjs';
+import {
+  buildAvailableNames,
+  collectCustomPropertyReferences,
+  collectTokenReferences,
+} from './consumed-tokens.ts';
 
 // Suppress ONE known noisy sd-transforms warning about unresolvable
 // {font-weight…} references inside math expressions. Scoped to console.warn
@@ -123,6 +128,9 @@ const tokensDir = path.dirname(require.resolve('@devexpress/design-tokens-intern
 const buildPath = `${path.resolve(dirname, '../../scss/_design-system')}/`;
 
 const THEME_NAME = 'fluent';
+const THEME_FOLDER = 'fluent-next';
+
+const themePath = path.resolve(dirname, `../../scss/widgets/${THEME_FOLDER}`);
 
 const FLUENT_PALETTES = [
   'blue',
@@ -173,10 +181,10 @@ const getModeFiles = (mode) => [
   `semantic/colors/${THEME_NAME}/${mode}`,
 ];
 
-const getComponentThemeFiles = () => [
-  ...getModeFiles('light'),
-  `components/core/theme/${THEME_NAME}`,
-];
+// Source files behind the SCSS bridge. The component tier is absent on purpose: its tokens only
+// alias the semantic roles the theme already reads, so emitting them added unreferenced custom
+// properties. Absent from the bridge, `ds.$button-color-bg-rest` is now a Sass error.
+const getBridgeFiles = () => getModeFiles('light');
 
 StyleDictionary.registerFormat({
   name: 'scssToCss',
@@ -291,21 +299,10 @@ const createModeConfig = (mode) => createConfig(mode, getModeFiles(mode), [
   },
 ]);
 
-const createComponentThemeConfig = () => createConfig('components-theme', getComponentThemeFiles(), [
-  {
-    destination: `${THEME_NAME}/components/theme.scss`,
-    format: 'css/variables',
-    filter: (token) => normalizeFilePath(token).includes(`components/core/theme/${THEME_NAME}.json`),
-    options: FILE_OPTIONS,
-  },
-]);
-
-// All token names for the SCSS bridge file: the common + light-mode + component
-// *theme* (color) set. Component *size* tokens are intentionally excluded — fluent-next
-// maps sizes onto the base scales (spacing/font-size/border-radius/…), so no widget
-// references the component `*-layout-*` tokens and they are not emitted (see
-// widgets/fluent-next/_design-system.scss).
-const createDsConfig = () => createConfig('ds', getComponentThemeFiles(), [
+// Component *size* tokens are excluded for the same reason as the component theme: fluent-next
+// maps sizes onto the base scales (spacing/font-size/border-radius/…), so no widget would read the
+// `*-layout-*` names (see widgets/fluent-next/_design-system.scss).
+const createDsConfig = () => createConfig('ds', getBridgeFiles(), [
   {
     destination: 'variables/_ds.scss',
     format: 'scssToCss',
@@ -315,7 +312,6 @@ const createDsConfig = () => createConfig('ds', getComponentThemeFiles(), [
 const configs = [
   ...FLUENT_PALETTES.map(createPaletteConfig),
   ...FLUENT_MODES.map(createModeConfig),
-  createComponentThemeConfig(),
   createDsConfig(),
 ];
 
@@ -359,6 +355,58 @@ async function validateReferences() {
   return files.length;
 }
 
+async function collectThemeStyleSheets() {
+  const entries = await readdir(themePath, { withFileTypes: true, recursive: true });
+
+  return entries
+    .filter((entry) => entry.isFile() && entry.name.endsWith('.scss'))
+    .map((entry) => path.join(entry.parentPath, entry.name));
+}
+
+// Every token a widget reads must still exist in the package. Without this a deleted token surfaces
+// much later as a Sass "Undefined variable", one name per rebuild, with no hint that a bump caused
+// it. Read from the flat index, not the bridge: it carries the version for the message.
+async function validateConsumedTokens() {
+  const { version, tokens } = JSON.parse(
+    await readFile(path.join(tokensDir, 'tokens.flat.json'), 'utf-8'),
+  );
+  const availableNames = buildAvailableNames(
+    Object.keys(tokens),
+    new Set(getBridgeFiles()),
+  );
+
+  const referenced = new Map();
+
+  for (const file of await collectThemeStyleSheets()) {
+    const content = await readFile(file, 'utf-8');
+    const source = path.relative(themePath, file);
+    const found = [
+      ...collectTokenReferences(content, source).map((name) => [name, `ds.$${name}`]),
+      ...collectCustomPropertyReferences(content, source).map((name) => [name, `var(--dxds-${name})`]),
+    ];
+
+    for (const [name, reference] of found) {
+      if (!referenced.has(name)) {
+        referenced.set(name, { file, reference });
+      }
+    }
+  }
+
+  const missing = [...referenced].filter(([name]) => !availableNames.has(name));
+
+  if (missing.length > 0) {
+    const details = missing
+      .map(([, { file, reference }]) => `  ${reference} (first used in ${path.relative(themePath, file)})`)
+      .join('\n');
+
+    throw new Error(
+      `Tokens used by ${THEME_FOLDER} but absent from @devexpress/design-tokens-internal ${version}:\n${details}`,
+    );
+  }
+
+  return referenced.size;
+}
+
 async function build() {
   await rm(buildPath, { recursive: true, force: true });
 
@@ -372,8 +420,10 @@ async function build() {
   }
 
   const fileCount = await validateReferences();
+  const consumedCount = await validateConsumedTokens();
 
   console.log(`Design tokens generated: ${fileCount} files in ${buildPath}`);
+  console.log(`Design tokens consumed by ${THEME_FOLDER}: ${consumedCount} verified against the package`);
 }
 
 await build();

packages/devextreme-scss/build/tokens/consumed-tokens.ts

@@ -0,0 +1,41 @@
+// Pure half of the consumed-token check in build-tokens.mjs, so the tests can run it without a build.
+
+// A commented-out declaration still names a token, and a dead reference must not fail the build.
+// Throws on an unpaired delimiter: it would shift the alternation and hide the rest of the file.
+export const stripScssComments = (content: string, source: string): string => {
+  const delimiters = content.replace(/\/\/[^\n\r]*/g, '').match(/\/\*|\*\//g) ?? [];
+  const paired = delimiters.length % 2 === 0
+    && delimiters.every((delimiter, index) => delimiter === (index % 2 === 0 ? '/*' : '*/'));
+
+  if (!paired) {
+    throw new Error(`Unpaired block comment delimiter in ${source}: code cannot be told from comment`);
+  }
+
+  return content
+    .replace(/\/\/[^\n\r]*/g, '')
+    .split(/\/\*|\*\//)
+    .filter((_, index) => index % 2 === 0)
+    .join('');
+};
+
+// Wider than kebab-case on purpose: `[a-z0-9-]` would truncate `ds.$spacing-40_typo` to a valid name.
+export const collectTokenReferences = (content: string, source: string): string[] => [
+  ...stripScssComments(content, source).matchAll(/\bds\.\$([\w-]+)/g),
+].map(([, name]) => name);
+
+// Bypassing the bridge compiles silently, so the raw form is collected too. Unused today.
+export const collectCustomPropertyReferences = (content: string, source: string): string[] => [
+  ...stripScssComments(content, source).matchAll(/var\(\s*--dxds-([\w-]+)/g),
+].map(([, name]) => name);
+
+// The index spans every design system and names repeat across them, so it is narrowed to the
+// source files the bridge is generated from.
+export const buildAvailableNames = (
+  flatTokenKeys: Iterable<string>,
+  consumedSourceFiles: ReadonlySet<string>,
+): Set<string> => new Set(
+  [...flatTokenKeys]
+    .map((key) => key.split(':'))
+    .filter(([sourceFile]) => consumedSourceFiles.has(sourceFile))
+    .map(([, tokenPath]) => tokenPath.replace(/\//g, '-')),
+);

packages/devextreme-scss/package.json

@@ -29,6 +29,7 @@
     "naming:residue": "node tools/naming/rename.mjs --residue",
     "review:evidence": "node tools/review/evidence.mjs",
     "test": "jest --no-coverage --runInBand --config=./tests/jest.config.json",
+    "typecheck": "tsc -p tsconfig.json",
     "watch": "pnpm --workspace-root nx run devextreme-scss --target=watch"
   },
   "version": "26.2.0"

packages/devextreme-scss/project.json

@@ -41,6 +41,7 @@
       },
       "inputs": [
         "{projectRoot}/build/tokens/**/*",
+        "{projectRoot}/scss/widgets/fluent-next/**/*",
         "{workspaceRoot}/pnpm-lock.yaml"
       ],
       "outputs": [
@@ -72,7 +73,9 @@
       "options": {
         "mode": "all"
       },
-      "dependsOn": ["build:tokens"],
+      "dependsOn": [
+        "build:tokens"
+      ],
       "inputs": [
         "{projectRoot}/build/**/*",
         "{projectRoot}/fonts/**/*",
@@ -94,7 +97,9 @@
       "options": {
         "mode": "ci"
       },
-      "dependsOn": ["build:tokens"],
+      "dependsOn": [
+        "build:tokens"
+      ],
       "inputs": [
         "{projectRoot}/build/**/*",
         "{projectRoot}/fonts/**/*",
@@ -173,7 +178,9 @@
         "mode": "all",
         "watch": true
       },
-      "dependsOn": ["build:tokens"],
+      "dependsOn": [
+        "build:tokens"
+      ],
       "inputs": [
         "{projectRoot}/build/**/*",
         "{projectRoot}/fonts/**/*",
@@ -198,10 +205,25 @@
       "options": {
         "script": "test"
       },
-      "dependsOn": ["build:tokens"],
+      "dependsOn": [
+        "build:tokens",
+        "typecheck"
+      ],
       "inputs": [
         "{projectRoot}/**/*"
       ]
+    },
+    "typecheck": {
+      "executor": "nx:run-script",
+      "options": {
+        "script": "typecheck"
+      },
+      "inputs": [
+        "{projectRoot}/build/tokens/**/*.ts",
+        "{projectRoot}/tests/**/*.ts",
+        "{projectRoot}/tsconfig.json"
+      ],
+      "cache": true
     }
   },
   "tags": []

packages/devextreme-scss/scss/widgets/fluent-next/_design-system.scss

@@ -4,16 +4,17 @@
 $accent: colors.$color;
 
 /*
- * Tier order mirrors the design-tokens package: base scales and palettes, then semantic roles,
- * then components. The component size tokens (fluent components sizes) are intentionally NOT
- * emitted: fluent-next maps sizes onto the base scales (spacing, font-size, border-radius,
- * border-width), so the component layout custom properties would never be referenced by any
- * widget. Only the component color theme is consumed.
+ * Tier order mirrors the design-tokens package: base scales and palettes, then semantic roles.
+ *
+ * The component tier is not emitted at all. Its tokens are aliases onto the semantic roles, the
+ * theme reads those roles directly, and emitting the tier only added unreferenced custom properties
+ * to every stylesheet. Component size tokens are absent for the same reason plus one more:
+ * fluent-next maps sizes onto the base scales (spacing, font-size, border-radius, border-width),
+ * so no widget would read the layout names either.
  */
 @include meta.load-css("../../_design-system/base");
 @include meta.load-css("../../_design-system/fluent/base");
 @include meta.load-css("../../_design-system/fluent/accents/#{$accent}");
 @include meta.load-css("../../_design-system/fluent/semantic/typography");
 @include meta.load-css("../../_design-system/fluent/semantic/box-shadow");
 @include meta.load-css("../../_design-system/fluent/semantic/colors/#{colors.$mode}");
-@include meta.load-css("../../_design-system/fluent/components/theme");

packages/devextreme-scss/scss/widgets/fluent-next/common/_colors.scss

@@ -22,6 +22,7 @@ $palette-border: ds.$color-border-neutral-default-rest !default;
 
 // Non-color theme-level values (opacity/font family) — kept referencing the theme layer.
 $global-font-family: ds.$font-family-sans-serif !default;
+$invalid-badge-bg-rest: ds.$color-content-danger-compound-rest !default;
 $invalid-badge-content-rest: ds.$color-content-neutral-default-static-dark-rest !default;
 $valid-badge-content-rest: ds.$color-surface-success-default-rest !default;
 $palette-text: ds.$color-content-neutral-default-rest !default;

packages/devextreme-scss/scss/widgets/fluent-next/common/_mixins.scss

@@ -3,15 +3,13 @@
 @use "sizes" as *;
 @use "../sizes" as *;
 @use "../../base/mixins" as *;
-@use "../../../_design-system/variables/ds" as ds;
+@use "../validation/sizes" as validationSizes;
 @use "../../base/validation" as baseValidation with (
-  $validation-summary-margin-top: ds.$spacing-200,
-  $validation-message-content-padding: ds.$spacing-100,
+  $validation-summary-margin-top: validationSizes.$validation-summary-margin-block-start,
+  $validation-message-content-padding: validationSizes.$validation-message-content-padding,
 );
 @use "../list/sizes" as listSizes;
 
-$invalid-badge-bg-rest: ds.$color-content-danger-compound-rest !default;
-
 @mixin dx-base-typography() {
   @include dx-base-typography-mixin(
       $global-content-rest,

packages/devextreme-scss/scss/widgets/fluent-next/dataGrid/_index.scss

@@ -1,5 +1,4 @@
 @use "../colors" as *;
-@use "../../../_design-system/variables/ds" as ds;
 @use "sass:color";
 @use "colors" as *;
 @use "sizes" as *;
@@ -32,7 +31,7 @@
   $datagrid-focused-border-color: gridBaseColors.$grid-border-focused,
   $header-filter-color: gridBaseColors.$grid-header-filter-icon-rest,
   $header-filter-color-empty: gridBaseColors.$grid-header-filter-empty-icon-rest,
-  $base-focus-color: ds.$color-content-neutral-default-inverted-rest,
+  $base-focus-color: gridBaseColors.$grid-content-focused,
   $datagrid-text-stub-background-image-path: gridBaseColors.$grid-text-stub-bg-rest,
   $datagrid-group-row-border: $data-grid-group-row-border,
   $datagrid-sticky-column-border: $data-grid-sticky-column-border,

packages/devextreme-scss/scss/widgets/fluent-next/gantt/_colors.scss

@@ -46,3 +46,5 @@ $gantt-ti-bg-rest: ds.$color-surface-primary-alpha-hovered !default;
  * variables (NAMING.md, O7).
  */
 $gantt-successor-background-color: ds.$color-surface-neutral-default-static-light-rest;
+
+$gantt-selection-bg-rest: ds.$color-surface-primary-deep-rest !default;