@backstage/eslint-plugin 0.3.0 → 0.3.1-next.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @backstage/eslint-plugin
 
+## 0.3.1-next.0
+
+### Patch Changes
+
+- 5d80f77: Adds a new `@backstage/no-deprecated-bui-tokens` lint rule that warns when a deprecated `@backstage/ui` CSS token is referenced in a JavaScript or TypeScript file (including CSS-in-JS patterns and template literals). The rule is included in the `recommended` config, so plugin authors using `plugin:@backstage/recommended` will receive warnings automatically when using tokens that have been superseded by the new semantic color families. Note that plain CSS and CSS module files are outside ESLint's scope and are not covered by this rule.
+
 ## 0.3.0
 
 ### Minor Changes

package/docs/rules/no-deprecated-bui-tokens.md

@@ -0,0 +1,108 @@
+# no-deprecated-bui-tokens
+
+Warns when a deprecated `@backstage/ui` CSS token is referenced inside a JS/TS string or template literal.
+
+The `@backstage/ui` design token system has been updated with a new set of semantic color families. The old tokens still work for backward compatibility, but they are scheduled for removal in a future major version.
+
+## Rule Details
+
+This rule reports a warning for any string value that contains a reference to a deprecated BUI CSS custom property, such as `var(--bui-bg-solid)` or `var(--bui-fg-danger)`.
+
+Examples of **incorrect** code for this rule:
+
+```js
+// Deprecated background token
+const style = { background: 'var(--bui-bg-solid)' };
+
+// Deprecated foreground token
+const style = { color: 'var(--bui-fg-danger)' };
+
+// Deprecated token in a template literal
+const css = `border: 1px solid var(--bui-border-danger)`;
+```
+
+Examples of **correct** code for this rule:
+
+```js
+// New accent family
+const style = { background: 'var(--bui-accent-bg)' };
+
+// New semantic negative family
+const style = { color: 'var(--bui-negative-fg-subdued)' };
+
+// New semantic positive family
+const style = { borderColor: 'var(--bui-positive-border)' };
+```
+
+## Migration Guide
+
+Replace deprecated tokens with their equivalents from the new semantic families.
+
+### Neutral backgrounds
+
+The neutral background tokens (`--bui-bg-app`, `--bui-bg-neutral-1..4`) are now the active semantic tokens with updated solid-color values. The `-hover`, `-pressed`, and `-disabled` interaction variants remain deprecated:
+
+| Deprecated                    | Replacement           |
+| ----------------------------- | --------------------- |
+| `--bui-bg-neutral-1-hover`    | _(remove or restyle)_ |
+| `--bui-bg-neutral-1-pressed`  | _(remove or restyle)_ |
+| `--bui-bg-neutral-1-disabled` | _(remove or restyle)_ |
+| `--bui-bg-neutral-2-hover`    | _(remove or restyle)_ |
+| `--bui-bg-neutral-2-pressed`  | _(remove or restyle)_ |
+| `--bui-bg-neutral-2-disabled` | _(remove or restyle)_ |
+| `--bui-bg-neutral-3-hover`    | _(remove or restyle)_ |
+| `--bui-bg-neutral-3-pressed`  | _(remove or restyle)_ |
+| `--bui-bg-neutral-3-disabled` | _(remove or restyle)_ |
+| `--bui-bg-neutral-4-hover`    | _(remove or restyle)_ |
+| `--bui-bg-neutral-4-pressed`  | _(remove or restyle)_ |
+| `--bui-bg-neutral-4-disabled` | _(remove or restyle)_ |
+
+### Foreground
+
+| Deprecated         | Replacement             |
+| ------------------ | ----------------------- |
+| `--bui-fg-danger`  | `--bui-fg-negative`     |
+| `--bui-fg-success` | `--bui-fg-positive`     |
+| `--bui-fg-info`    | `--bui-fg-announcement` |
+
+### Accent
+
+| Deprecated                | Replacement                |
+| ------------------------- | -------------------------- |
+| `--bui-bg-solid`          | `--bui-accent-bg`          |
+| `--bui-bg-solid-hover`    | `--bui-accent-bg-hover`    |
+| `--bui-bg-solid-disabled` | `--bui-accent-bg-disabled` |
+| `--bui-fg-solid`          | `--bui-accent-fg`          |
+| `--bui-fg-solid-disabled` | `--bui-accent-fg-disabled` |
+
+### Positive
+
+| Deprecated               | Replacement                 |
+| ------------------------ | --------------------------- |
+| `--bui-bg-success`       | `--bui-positive-bg-subdued` |
+| `--bui-fg-success-on-bg` | `--bui-positive-fg-subdued` |
+| `--bui-border-success`   | `--bui-positive-border`     |
+
+### Negative
+
+| Deprecated              | Replacement                 |
+| ----------------------- | --------------------------- |
+| `--bui-bg-danger`       | `--bui-negative-bg-subdued` |
+| `--bui-fg-danger-on-bg` | `--bui-negative-fg-subdued` |
+| `--bui-border-danger`   | `--bui-negative-border`     |
+
+### Warning
+
+| Deprecated               | Replacement                |
+| ------------------------ | -------------------------- |
+| `--bui-bg-warning`       | `--bui-warning-bg-subdued` |
+| `--bui-fg-warning-on-bg` | `--bui-warning-fg-subdued` |
+| `--bui-border-warning`   | `--bui-warning-border`     |
+
+### Announcement
+
+| Deprecated            | Replacement                     |
+| --------------------- | ------------------------------- |
+| `--bui-bg-info`       | `--bui-announcement-bg-subdued` |
+| `--bui-fg-info-on-bg` | `--bui-announcement-fg-subdued` |
+| `--bui-border-info`   | `--bui-announcement-border`     |

package/index.js

@@ -25,6 +25,7 @@ module.exports = {
         '@backstage/no-mixed-plugin-imports': 'warn',
         '@backstage/no-ui-css-imports-in-non-frontend': 'error',
         '@backstage/no-self-package-imports': 'error',
+        '@backstage/no-deprecated-bui-tokens': 'warn',
       },
     },
   },
@@ -36,5 +37,6 @@ module.exports = {
     'no-mixed-plugin-imports': require('./rules/no-mixed-plugin-imports'),
     'no-ui-css-imports-in-non-frontend': require('./rules/no-ui-css-imports-in-non-frontend'),
     'no-self-package-imports': require('./rules/no-self-package-imports'),
+    'no-deprecated-bui-tokens': require('./rules/no-deprecated-bui-tokens'),
   },
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backstage/eslint-plugin",
-  "version": "0.3.0",
+  "version": "0.3.1-next.0",
   "description": "Backstage ESLint plugin",
   "publishConfig": {
     "access": "public"
@@ -22,7 +22,7 @@
     "minimatch": "^10.2.1"
   },
   "devDependencies": {
-    "@backstage/cli": "^0.36.2",
+    "@backstage/cli": "0.36.3-next.1",
     "@types/estree": "^1.0.5",
     "eslint": "^8.33.0"
   }

package/rules/no-deprecated-bui-tokens.js

@@ -0,0 +1,117 @@
+/*
+ * Copyright 2025 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+// @ts-check
+
+/** @type {string[]} */
+const DEPRECATED_TOKENS = [
+  '--bui-bg-solid',
+  '--bui-bg-solid-hover',
+  '--bui-bg-solid-pressed',
+  '--bui-bg-solid-disabled',
+  '--bui-bg-neutral-1-hover',
+  '--bui-bg-neutral-1-pressed',
+  '--bui-bg-neutral-1-disabled',
+  '--bui-bg-neutral-2-hover',
+  '--bui-bg-neutral-2-pressed',
+  '--bui-bg-neutral-2-disabled',
+  '--bui-bg-neutral-3-hover',
+  '--bui-bg-neutral-3-pressed',
+  '--bui-bg-neutral-3-disabled',
+  '--bui-bg-neutral-4-hover',
+  '--bui-bg-neutral-4-pressed',
+  '--bui-bg-neutral-4-disabled',
+  '--bui-bg-danger',
+  '--bui-bg-warning',
+  '--bui-bg-success',
+  '--bui-bg-info',
+  '--bui-fg-solid',
+  '--bui-fg-solid-disabled',
+  '--bui-fg-danger-on-bg',
+  '--bui-fg-warning-on-bg',
+  '--bui-fg-success-on-bg',
+  '--bui-fg-info-on-bg',
+  '--bui-fg-danger',
+  '--bui-fg-success',
+  '--bui-fg-info',
+  '--bui-border-info',
+  '--bui-border-danger',
+  '--bui-border-warning',
+  '--bui-border-success',
+  '--bui-shadow',
+];
+
+const DEPRECATED_SET = new Set(DEPRECATED_TOKENS);
+
+/**
+ * Extracts all CSS custom property names referenced inside a string value,
+ * e.g. "var(--bui-bg-solid)" → ["--bui-bg-solid"]
+ * @param {string} value
+ * @returns {string[]}
+ */
+function extractTokenNames(value) {
+  const matches = value.match(/--bui-[\w-]+/g);
+  return matches ?? [];
+}
+
+/** @type {import('eslint').Rule.RuleModule} */
+module.exports = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description:
+        'Warn when deprecated Backstage UI CSS tokens are referenced in JS/TS string literals.',
+      url: 'https://github.com/backstage/backstage/blob/master/packages/eslint-plugin/docs/rules/no-deprecated-bui-tokens.md',
+    },
+    messages: {
+      deprecated:
+        "'{{token}}' is a deprecated BUI token. Replace it with the appropriate current BUI token for its usage (for example, a semantic intent, surface/background, or shadow token); see this rule's migration guide for the correct mapping.",
+    },
+    schema: [],
+  },
+
+  create(context) {
+    /**
+     * @param {import('estree').Node} node
+     * @param {string} value
+     */
+    function checkValue(node, value) {
+      for (const token of extractTokenNames(value)) {
+        if (DEPRECATED_SET.has(token)) {
+          context.report({
+            node,
+            messageId: 'deprecated',
+            data: { token },
+          });
+        }
+      }
+    }
+
+    return {
+      Literal(node) {
+        if (typeof node.value === 'string') {
+          checkValue(node, node.value);
+        }
+      },
+
+      TemplateElement(node) {
+        if (node.value?.cooked) {
+          checkValue(node, node.value.cooked);
+        }
+      },
+    };
+  },
+};

package/src/no-deprecated-bui-tokens.test.ts

@@ -0,0 +1,257 @@
+/*
+ * Copyright 2025 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { RuleTester } from 'eslint';
+import rule from '../rules/no-deprecated-bui-tokens';
+
+const ruleTester = new RuleTester({
+  parserOptions: {
+    sourceType: 'module',
+    ecmaVersion: 2021,
+  },
+});
+
+ruleTester.run('no-deprecated-bui-tokens', rule, {
+  valid: [
+    // Non-deprecated tokens — should not warn
+    { code: `const s = 'var(--bui-fg-primary)'` },
+    { code: `const s = 'var(--bui-fg-secondary)'` },
+    { code: `const s = 'var(--bui-fg-disabled)'` },
+    { code: `const s = 'var(--bui-fg-warning)'` },
+    { code: `const s = 'var(--bui-fg-positive)'` },
+    { code: `const s = 'var(--bui-fg-negative)'` },
+    { code: `const s = 'var(--bui-fg-announcement)'` },
+    { code: `const s = 'var(--bui-border-1)'` },
+    { code: `const s = 'var(--bui-border-2)'` },
+    { code: `const s = 'var(--bui-accent-bg)'` },
+    { code: `const s = 'var(--bui-accent-bg-hover)'` },
+    { code: `const s = 'var(--bui-accent-bg-disabled)'` },
+    { code: `const s = 'var(--bui-accent-fg)'` },
+    { code: `const s = 'var(--bui-accent-fg-disabled)'` },
+    { code: `const s = 'var(--bui-negative-bg)'` },
+    { code: `const s = 'var(--bui-positive-bg)'` },
+    { code: `const s = 'var(--bui-warning-bg)'` },
+    { code: `const s = 'var(--bui-announcement-bg)'` },
+    { code: `const s = 'var(--bui-gray-1)'` },
+    { code: `const s = 'var(--bui-bg-app)'` },
+    { code: `const s = 'var(--bui-bg-neutral-1)'` },
+    { code: `const s = 'var(--bui-bg-neutral-2)'` },
+    { code: `const s = 'var(--bui-bg-neutral-3)'` },
+    { code: `const s = 'var(--bui-bg-neutral-4)'` },
+    // Unrelated strings — should not warn
+    { code: `const s = 'some-other-string'` },
+    { code: `const n = 42` },
+  ],
+
+  invalid: [
+    // Plain string literals
+    {
+      code: `const s = 'var(--bui-bg-solid)'`,
+      errors: [{ messageId: 'deprecated', data: { token: '--bui-bg-solid' } }],
+    },
+    {
+      code: `const s = 'var(--bui-bg-solid-hover)'`,
+      errors: [
+        { messageId: 'deprecated', data: { token: '--bui-bg-solid-hover' } },
+      ],
+    },
+    {
+      code: `const s = 'var(--bui-bg-solid-pressed)'`,
+      errors: [
+        { messageId: 'deprecated', data: { token: '--bui-bg-solid-pressed' } },
+      ],
+    },
+    {
+      code: `const s = 'var(--bui-bg-solid-disabled)'`,
+      errors: [
+        {
+          messageId: 'deprecated',
+          data: { token: '--bui-bg-solid-disabled' },
+        },
+      ],
+    },
+    {
+      code: `const s = 'var(--bui-bg-neutral-2-hover)'`,
+      errors: [
+        {
+          messageId: 'deprecated',
+          data: { token: '--bui-bg-neutral-2-hover' },
+        },
+      ],
+    },
+    {
+      code: `const s = 'var(--bui-bg-neutral-3-pressed)'`,
+      errors: [
+        {
+          messageId: 'deprecated',
+          data: { token: '--bui-bg-neutral-3-pressed' },
+        },
+      ],
+    },
+    {
+      code: `const s = 'var(--bui-bg-neutral-4-disabled)'`,
+      errors: [
+        {
+          messageId: 'deprecated',
+          data: { token: '--bui-bg-neutral-4-disabled' },
+        },
+      ],
+    },
+    {
+      code: `const s = 'var(--bui-bg-danger)'`,
+      errors: [{ messageId: 'deprecated', data: { token: '--bui-bg-danger' } }],
+    },
+    {
+      code: `const s = 'var(--bui-bg-warning)'`,
+      errors: [
+        { messageId: 'deprecated', data: { token: '--bui-bg-warning' } },
+      ],
+    },
+    {
+      code: `const s = 'var(--bui-bg-success)'`,
+      errors: [
+        { messageId: 'deprecated', data: { token: '--bui-bg-success' } },
+      ],
+    },
+    {
+      code: `const s = 'var(--bui-bg-info)'`,
+      errors: [{ messageId: 'deprecated', data: { token: '--bui-bg-info' } }],
+    },
+    {
+      code: `const s = 'var(--bui-fg-solid)'`,
+      errors: [{ messageId: 'deprecated', data: { token: '--bui-fg-solid' } }],
+    },
+    {
+      code: `const s = 'var(--bui-fg-solid-disabled)'`,
+      errors: [
+        { messageId: 'deprecated', data: { token: '--bui-fg-solid-disabled' } },
+      ],
+    },
+    {
+      code: `const s = 'var(--bui-fg-danger-on-bg)'`,
+      errors: [
+        { messageId: 'deprecated', data: { token: '--bui-fg-danger-on-bg' } },
+      ],
+    },
+    {
+      code: `const s = 'var(--bui-fg-warning-on-bg)'`,
+      errors: [
+        { messageId: 'deprecated', data: { token: '--bui-fg-warning-on-bg' } },
+      ],
+    },
+    {
+      code: `const s = 'var(--bui-fg-success-on-bg)'`,
+      errors: [
+        { messageId: 'deprecated', data: { token: '--bui-fg-success-on-bg' } },
+      ],
+    },
+    {
+      code: `const s = 'var(--bui-fg-info-on-bg)'`,
+      errors: [
+        { messageId: 'deprecated', data: { token: '--bui-fg-info-on-bg' } },
+      ],
+    },
+    {
+      code: `const s = 'var(--bui-fg-danger)'`,
+      errors: [{ messageId: 'deprecated', data: { token: '--bui-fg-danger' } }],
+    },
+    {
+      code: `const s = 'var(--bui-fg-success)'`,
+      errors: [
+        { messageId: 'deprecated', data: { token: '--bui-fg-success' } },
+      ],
+    },
+    {
+      code: `const s = 'var(--bui-fg-info)'`,
+      errors: [{ messageId: 'deprecated', data: { token: '--bui-fg-info' } }],
+    },
+    {
+      code: `const s = 'var(--bui-border-info)'`,
+      errors: [
+        { messageId: 'deprecated', data: { token: '--bui-border-info' } },
+      ],
+    },
+    {
+      code: `const s = 'var(--bui-border-danger)'`,
+      errors: [
+        { messageId: 'deprecated', data: { token: '--bui-border-danger' } },
+      ],
+    },
+    {
+      code: `const s = 'var(--bui-border-warning)'`,
+      errors: [
+        { messageId: 'deprecated', data: { token: '--bui-border-warning' } },
+      ],
+    },
+    {
+      code: `const s = 'var(--bui-border-success)'`,
+      errors: [
+        { messageId: 'deprecated', data: { token: '--bui-border-success' } },
+      ],
+    },
+    {
+      code: `const s = 'var(--bui-shadow)'`,
+      errors: [{ messageId: 'deprecated', data: { token: '--bui-shadow' } }],
+    },
+
+    // Template literals
+    {
+      code: 'const s = `var(--bui-bg-solid)`',
+      errors: [{ messageId: 'deprecated', data: { token: '--bui-bg-solid' } }],
+    },
+    {
+      code: 'const s = `var(--bui-fg-danger)`',
+      errors: [{ messageId: 'deprecated', data: { token: '--bui-fg-danger' } }],
+    },
+    {
+      code: 'const s = `border: 1px solid var(--bui-border-danger)`',
+      errors: [
+        { messageId: 'deprecated', data: { token: '--bui-border-danger' } },
+      ],
+    },
+
+    // Multiple deprecated tokens in one string — one error per token
+    {
+      code: `const s = 'background: var(--bui-bg-solid); color: var(--bui-fg-solid)'`,
+      errors: [
+        { messageId: 'deprecated', data: { token: '--bui-bg-solid' } },
+        { messageId: 'deprecated', data: { token: '--bui-fg-solid' } },
+      ],
+    },
+
+    // Inline style usage patterns (JSX)
+    {
+      code: `const el = <div style={{ background: 'var(--bui-bg-danger)' }} />`,
+      parserOptions: {
+        sourceType: 'module',
+        ecmaVersion: 2021,
+        ecmaFeatures: { jsx: true },
+      },
+      errors: [{ messageId: 'deprecated', data: { token: '--bui-bg-danger' } }],
+    },
+    {
+      code: `const el = <div style={{ color: 'var(--bui-fg-success)' }} />`,
+      parserOptions: {
+        sourceType: 'module',
+        ecmaVersion: 2021,
+        ecmaFeatures: { jsx: true },
+      },
+      errors: [
+        { messageId: 'deprecated', data: { token: '--bui-fg-success' } },
+      ],
+    },
+  ],
+});