From 7898df0aa08d81a8e40616efbef45bae4bea7848 Mon Sep 17 00:00:00 2001
From: Charles de Dreuille <charles.dedreuille@gmail.com>
Date: Sat, 7 Feb 2026 08:30:44 +0000
Subject: [PATCH] Add changeset

Signed-off-by: Charles de Dreuille <charles.dedreuille@gmail.com>
---
 .changeset/clean-bags-occur.md | 69 ++++++++++++++++++++++++++++++++++
 1 file changed, 69 insertions(+)
 create mode 100644 .changeset/clean-bags-occur.md

diff --git a/.changeset/clean-bags-occur.md b/.changeset/clean-bags-occur.md
new file mode 100644
index 0000000000..bf376e2300
--- /dev/null
+++ b/.changeset/clean-bags-occur.md
@@ -0,0 +1,69 @@
+---
+'@backstage/ui': minor
+---
+
+**BREAKING**: Replaced `Surface` / `onSurface` system with new `Bg` background system
+
+The old `Surface` type (`'0'`–`'3'`, `'auto'`) and its associated props (`surface`, `onSurface`) have been replaced by a new `Bg` type with semantic neutral levels (`'neutral-1'` through `'neutral-4'`) and intents (`'danger'`, `'warning'`, `'success'`). Leaf components like Button no longer need an explicit prop — backgrounds auto-increment from parent context.
+
+New `useBg` hook and `BgProvider` replace the deleted `useSurface` hook and `SurfaceProvider`.
+
+**Migration:**
+
+Rename the `surface` prop to `bg` on container components and update values:
+
+```diff
+- <Box surface="1">
++ <Box bg="neutral-1">
+
+- <Card surface="2">
++ <Card bg="neutral-2">
+
+- <Flex surface="0">
++ <Flex bg="neutral-1">
+
+- <Grid.Root surface="1">
++ <Grid.Root bg="neutral-1">
+```
+
+Remove `onSurface` from leaf components — it is now fully automatic:
+
+```diff
+- <Button onSurface="1" variant="secondary">
++ <Button variant="secondary">
+
+- <ButtonIcon onSurface="2" variant="secondary" />
++ <ButtonIcon variant="secondary" />
+
+- <ToggleButton onSurface="1">
++ <ToggleButton>
+```
+
+Alert no longer accepts a `surface` prop (its background is driven by `status`):
+
+```diff
+- <Alert surface="1" status="info" />
++ <Alert status="info" />
+```
+
+Update type imports:
+
+```diff
+- import type { Surface, LeafSurfaceProps, ContainerSurfaceProps } from '@backstage/ui';
++ import type { Bg } from '@backstage/ui';
+```
+
+Replace hook usage in custom components:
+
+```diff
+- import { useSurface, SurfaceProvider } from '@backstage/ui';
++ import { useBg, BgProvider } from '@backstage/ui';
+
+- const { surface } = useSurface({ surface: props.surface });
++ const { bg } = useBg({ bg: props.bg });
+
+- const { surface } = useSurface({ onSurface: props.onSurface });
++ const { bg } = useBg({ leaf: true });
+```
+
+**Affected components:** box, button, button-icon, button-link, toggle-button, card, alert, flex, grid