From 53388ccb5eaa6630b954f49fe1f0d27ba3dc79b0 Mon Sep 17 00:00:00 2001
From: Charles de Dreuille <charles.dedreuille@gmail.com>
Date: Tue, 26 May 2026 21:43:50 +0200
Subject: [PATCH] docs(eslint-plugin): fix migration table in
 no-deprecated-bui-tokens docs

Group migrations by family (Surfaces, Foreground, Accent, Positive,
Negative, Warning, Announcement) and correct the surface token mappings
to match the full --bui-surface-1 through --bui-surface-5 scale.

Signed-off-by: Charles de Dreuille <charles.dedreuille@gmail.com>
---
 .../docs/rules/no-deprecated-bui-tokens.md    | 85 +++++++++++++------
 1 file changed, 60 insertions(+), 25 deletions(-)

diff --git a/packages/eslint-plugin/docs/rules/no-deprecated-bui-tokens.md b/packages/eslint-plugin/docs/rules/no-deprecated-bui-tokens.md
index 5159ab3a5c..39713b4c70 100644
--- a/packages/eslint-plugin/docs/rules/no-deprecated-bui-tokens.md
+++ b/packages/eslint-plugin/docs/rules/no-deprecated-bui-tokens.md
@@ -36,29 +36,64 @@ const style = { borderColor: 'var(--bui-positive-border)' };
 
 ## Migration Guide
 
-Replace deprecated tokens with their equivalents from the new semantic families:
+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`               |
+**Surfaces**
+
+| Deprecated           | Replacement       |
+| -------------------- | ----------------- |
+| `--bui-bg-app`       | `--bui-surface-1` |
+| `--bui-bg-neutral-1` | `--bui-surface-2` |
+| `--bui-bg-neutral-2` | `--bui-surface-3` |
+| `--bui-bg-neutral-3` | `--bui-surface-4` |
+| `--bui-bg-neutral-4` | `--bui-surface-5` |
+
+**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`     |