From 657aad6cf032cbc26849f25cd8a906247cef0fde Mon Sep 17 00:00:00 2001 From: Charles de Dreuille Date: Wed, 27 May 2026 13:11:38 +0200 Subject: [PATCH] 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 --- .changeset/ui-semantic-color-tokens.md | 12 +++---- .../docs/rules/no-deprecated-bui-tokens.md | 12 +++---- .../rules/no-deprecated-bui-tokens.js | 4 --- .../src/no-deprecated-bui-tokens.test.ts | 12 +++---- packages/ui/src/css/colors.stories.tsx | 12 +++---- packages/ui/src/css/tokens.css | 32 +++++++------------ 6 files changed, 31 insertions(+), 53 deletions(-) diff --git a/.changeset/ui-semantic-color-tokens.md b/.changeset/ui-semantic-color-tokens.md index 1fe3ad77a3..41dc2de160 100644 --- a/.changeset/ui-semantic-color-tokens.md +++ b/.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** 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 5d676344d6..c31617c333 100644 --- a/packages/eslint-plugin/docs/rules/no-deprecated-bui-tokens.md +++ b/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 diff --git a/packages/eslint-plugin/rules/no-deprecated-bui-tokens.js b/packages/eslint-plugin/rules/no-deprecated-bui-tokens.js index 597909eec1..eb38707c5c 100644 --- a/packages/eslint-plugin/rules/no-deprecated-bui-tokens.js +++ b/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', diff --git a/packages/eslint-plugin/src/no-deprecated-bui-tokens.test.ts b/packages/eslint-plugin/src/no-deprecated-bui-tokens.test.ts index 62a8dfd7e9..5e7dbe57ea 100644 --- a/packages/eslint-plugin/src/no-deprecated-bui-tokens.test.ts +++ b/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: [ diff --git a/packages/ui/src/css/colors.stories.tsx b/packages/ui/src/css/colors.stories.tsx index 83425cc85a..7f46d922a6 100644 --- a/packages/ui/src/css/colors.stories.tsx +++ b/packages/ui/src/css/colors.stories.tsx @@ -122,13 +122,13 @@ export const All = meta.story({ />
diff --git a/packages/ui/src/css/tokens.css b/packages/ui/src/css/tokens.css index c149474d27..d149523ecd 100644 --- a/packages/ui/src/css/tokens.css +++ b/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%);