refactor(ui): rename surface tokens to neutral background tokens

Replace --bui-surface-1..5 with --bui-bg-neutral-1..5 for both light
and dark themes. --bui-bg-neutral-1 replaces the deprecated --bui-bg-app,
and --bui-bg-neutral-2..5 extend the scale. The old bare --bui-bg-neutral-1..4
entries are removed from the deprecated section since their names are now
reused; the hover/pressed/disabled variants remain deprecated.

Updates colors.stories.tsx, the ESLint rule and tests, and all migration
documentation and the PR description accordingly.

Signed-off-by: Charles de Dreuille <charles.dedreuille@gmail.com>

.changeset/ui-semantic-color-tokens.md

@@ -8,15 +8,11 @@ The previous tokens remain in place for backward compatibility but are now depre
 
 **Migration:**
 
-**Surfaces**
+**Neutral backgrounds**
 
-| 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` |
+| Deprecated     | Replacement          |
+| -------------- | -------------------- |
+| `--bui-bg-app` | `--bui-bg-neutral-1` |
 
 **Foreground**
 

packages/eslint-plugin/docs/rules/no-deprecated-bui-tokens.md

@@ -38,15 +38,11 @@ const style = { borderColor: 'var(--bui-positive-border)' };
 
 Replace deprecated tokens with their equivalents from the new semantic families.
 
-### Surfaces
+### Neutral backgrounds
 
-| 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` |
+| Deprecated     | Replacement          |
+| -------------- | -------------------- |
+| `--bui-bg-app` | `--bui-bg-neutral-1` |
 
 ### Foreground
 

packages/eslint-plugin/rules/no-deprecated-bui-tokens.js

@@ -23,19 +23,15 @@ const DEPRECATED_TOKENS = [
   '--bui-bg-solid-pressed',
   '--bui-bg-solid-disabled',
   '--bui-bg-app',
-  '--bui-bg-neutral-1',
   '--bui-bg-neutral-1-hover',
   '--bui-bg-neutral-1-pressed',
   '--bui-bg-neutral-1-disabled',
-  '--bui-bg-neutral-2',
   '--bui-bg-neutral-2-hover',
   '--bui-bg-neutral-2-pressed',
   '--bui-bg-neutral-2-disabled',
-  '--bui-bg-neutral-3',
   '--bui-bg-neutral-3-hover',
   '--bui-bg-neutral-3-pressed',
   '--bui-bg-neutral-3-disabled',
-  '--bui-bg-neutral-4',
   '--bui-bg-neutral-4-hover',
   '--bui-bg-neutral-4-pressed',
   '--bui-bg-neutral-4-disabled',

packages/eslint-plugin/src/no-deprecated-bui-tokens.test.ts

@@ -46,7 +46,11 @@ ruleTester.run('no-deprecated-bui-tokens', rule, {
     { 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-surface-1)'` },
+    { 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)'` },
+    { code: `const s = 'var(--bui-bg-neutral-5)'` },
     // Unrelated strings — should not warn
     { code: `const s = 'some-other-string'` },
     { code: `const n = 42` },
@@ -83,12 +87,6 @@ ruleTester.run('no-deprecated-bui-tokens', rule, {
       code: `const s = 'var(--bui-bg-app)'`,
       errors: [{ messageId: 'deprecated', data: { token: '--bui-bg-app' } }],
     },
-    {
-      code: `const s = 'var(--bui-bg-neutral-1)'`,
-      errors: [
-        { messageId: 'deprecated', data: { token: '--bui-bg-neutral-1' } },
-      ],
-    },
     {
       code: `const s = 'var(--bui-bg-neutral-2-hover)'`,
       errors: [

packages/ui/src/css/colors.stories.tsx

@@ -122,13 +122,13 @@ export const All = meta.story({
       />
 
       <Section
-        title="Surfaces"
+        title="Neutral Backgrounds"
         tokens={[
-          { label: 'Surface 1', token: '--bui-surface-1' },
-          { label: 'Surface 2', token: '--bui-surface-2' },
-          { label: 'Surface 3', token: '--bui-surface-3' },
-          { label: 'Surface 4', token: '--bui-surface-4' },
-          { label: 'Surface 5', token: '--bui-surface-5' },
+          { label: 'Neutral 1', token: '--bui-bg-neutral-1' },
+          { label: 'Neutral 2', token: '--bui-bg-neutral-2' },
+          { label: 'Neutral 3', token: '--bui-bg-neutral-3' },
+          { label: 'Neutral 4', token: '--bui-bg-neutral-4' },
+          { label: 'Neutral 5', token: '--bui-bg-neutral-5' },
         ]}
       />
 

packages/ui/src/css/tokens.css

@@ -90,12 +90,12 @@
     --bui-gray-10: #171717;
     --bui-gray-11: #0a0a0a;
 
-    /* Surface colors */
-    --bui-surface-1: #f5f5f5;
-    --bui-surface-2: var(--bui-white);
-    --bui-surface-3: #f7f7f7;
-    --bui-surface-4: var(--bui-white);
-    --bui-surface-5: #f7f7f7;
+    /* Neutral background colors */
+    --bui-bg-neutral-1: #f5f5f5;
+    --bui-bg-neutral-2: var(--bui-white);
+    --bui-bg-neutral-3: #f7f7f7;
+    --bui-bg-neutral-4: var(--bui-white);
+    --bui-bg-neutral-5: #f7f7f7;
 
     /* Foreground colors */
     --bui-fg-primary: var(--bui-black);
@@ -175,19 +175,15 @@
     --bui-bg-solid-pressed: #0f2b4e;
     --bui-bg-solid-disabled: #163a66;
     --bui-bg-app: #f8f8f8;
-    --bui-bg-neutral-1: #fff;
     --bui-bg-neutral-1-hover: oklch(0% 0 0 / 6%);
     --bui-bg-neutral-1-pressed: oklch(0% 0 0 / 12%);
     --bui-bg-neutral-1-disabled: oklch(0% 0 0 / 6%);
-    --bui-bg-neutral-2: oklch(0% 0 0 / 6%);
     --bui-bg-neutral-2-hover: oklch(0% 0 0 / 12%);
     --bui-bg-neutral-2-pressed: oklch(0% 0 0 / 16%);
     --bui-bg-neutral-2-disabled: oklch(0% 0 0 / 6%);
-    --bui-bg-neutral-3: oklch(0% 0 0 / 6%);
     --bui-bg-neutral-3-hover: oklch(0% 0 0 / 12%);
     --bui-bg-neutral-3-pressed: oklch(0% 0 0 / 16%);
     --bui-bg-neutral-3-disabled: oklch(0% 0 0 / 6%);
-    --bui-bg-neutral-4: oklch(0% 0 0 / 6%);
     --bui-bg-neutral-4-hover: oklch(0% 0 0 / 12%);
     --bui-bg-neutral-4-pressed: oklch(0% 0 0 / 16%);
     --bui-bg-neutral-4-disabled: oklch(0% 0 0 / 6%);
@@ -219,12 +215,12 @@
     --bui-scrollbar: #3636363a;
     --bui-scrollbar-thumb: #575757;
 
-    /* Surface colors */
-    --bui-surface-1: #333333;
-    --bui-surface-2: #1a1a1a;
-    --bui-surface-3: #282828;
-    --bui-surface-4: #393939;
-    --bui-surface-5: #474747;
+    /* Neutral background colors */
+    --bui-bg-neutral-1: #333333;
+    --bui-bg-neutral-2: #1a1a1a;
+    --bui-bg-neutral-3: #282828;
+    --bui-bg-neutral-4: #393939;
+    --bui-bg-neutral-5: #474747;
 
     /* Foreground colors */
     --bui-fg-primary: var(--bui-white);
@@ -304,19 +300,15 @@
     --bui-bg-solid-pressed: #83b9fd;
     --bui-bg-solid-disabled: #1b3d68;
     --bui-bg-app: #333333;
-    --bui-bg-neutral-1: oklch(100% 0 0 / 10%);
     --bui-bg-neutral-1-hover: oklch(100% 0 0 / 14%);
     --bui-bg-neutral-1-pressed: oklch(100% 0 0 / 20%);
     --bui-bg-neutral-1-disabled: oklch(100% 0 0 / 10%);
-    --bui-bg-neutral-2: oklch(100% 0 0 / 6%);
     --bui-bg-neutral-2-hover: oklch(100% 0 0 / 10%);
     --bui-bg-neutral-2-pressed: oklch(100% 0 0 / 16%);
     --bui-bg-neutral-2-disabled: oklch(100% 0 0 / 6%);
-    --bui-bg-neutral-3: oklch(100% 0 0 / 8%);
     --bui-bg-neutral-3-hover: oklch(100% 0 0 / 12%);
     --bui-bg-neutral-3-pressed: oklch(100% 0 0 / 20%);
     --bui-bg-neutral-3-disabled: oklch(100% 0 0 / 8%);
-    --bui-bg-neutral-4: oklch(100% 0 0 / 8%);
     --bui-bg-neutral-4-hover: oklch(100% 0 0 / 12%);
     --bui-bg-neutral-4-pressed: oklch(100% 0 0 / 20%);
     --bui-bg-neutral-4-disabled: oklch(100% 0 0 / 8%);