diff --git a/packages/eslint-plugin/docs/rules/no-deprecated-bui-tokens.md b/packages/eslint-plugin/docs/rules/no-deprecated-bui-tokens.md
new file mode 100644
index 0000000000..5159ab3a5c
--- /dev/null
+++ b/packages/eslint-plugin/docs/rules/no-deprecated-bui-tokens.md
@@ -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`               |