docs(eslint-plugin): add docs page for no-deprecated-bui-tokens rule

Adds the missing documentation page at the URL referenced in the rule meta, consistent with all other rules in the plugin. Includes incorrect/ correct code examples and a migration table mapping each deprecated token to its semantic replacement. Signed-off-by: Charles de Dreuille <charles.dedreuille@gmail.com>
2026-05-26 15:49:06 +02:00
parent ad1936ee31
commit d80062d18e
1 changed files with 64 additions and 0 deletions
@@ -0,0 +1,64 @@
+# 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:
+
+| Deprecated token          | 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`      |
+| `--bui-bg-danger`         | `--bui-negative-bg-subdued`     |
+| `--bui-bg-warning`        | `--bui-warning-bg-subdued`      |
+| `--bui-bg-success`        | `--bui-positive-bg-subdued`     |
+| `--bui-bg-info`           | `--bui-announcement-bg-subdued` |
+| `--bui-fg-danger`         | `--bui-negative-fg-subdued`     |
+| `--bui-fg-success`        | `--bui-positive-fg-subdued`     |
+| `--bui-fg-info`           | `--bui-announcement-fg-subdued` |
+| `--bui-fg-danger-on-bg`   | `--bui-negative-fg-subdued`     |
+| `--bui-fg-warning-on-bg`  | `--bui-warning-fg-subdued`      |
+| `--bui-fg-success-on-bg`  | `--bui-positive-fg-subdued`     |
+| `--bui-fg-info-on-bg`     | `--bui-announcement-fg-subdued` |
+| `--bui-border-danger`     | `--bui-negative-border`         |
+| `--bui-border-warning`    | `--bui-warning-border`          |
+| `--bui-border-success`    | `--bui-positive-border`         |
+| `--bui-border-info`       | `--bui-announcement-border`     |
+| `--bui-bg-neutral-1`      | `--bui-surface-1`               |
+| `--bui-bg-app`            | `--bui-surface-1`               |