From 048d9c47d49bcb1173b161fb1b597547507e77bb Mon Sep 17 00:00:00 2001
From: Charles de Dreuille <charles.dedreuille@gmail.com>
Date: Wed, 11 Feb 2026 10:36:32 +0000
Subject: [PATCH] Cleanup

Signed-off-by: Charles de Dreuille <charles.dedreuille@gmail.com>
---
 .changeset/clean-bags-occur.md  | 15 +++++++++------
 packages/ui/src/hooks/useBg.tsx | 17 ++++++++++++++---
 2 files changed, 23 insertions(+), 9 deletions(-)

diff --git a/.changeset/clean-bags-occur.md b/.changeset/clean-bags-occur.md
index 27986eee24..ea4ae25aa6 100644
--- a/.changeset/clean-bags-occur.md
+++ b/.changeset/clean-bags-occur.md
@@ -11,19 +11,22 @@ The old `Surface` type (`'0'`–`'3'`, `'auto'`) and its associated props (`surf
 - `ContainerBg` — `'neutral-1'` | `'neutral-2'` | `'neutral-3'` | `'danger'` | `'warning'` | `'success'`
 - `ProviderBg` — `ContainerBg | 'neutral-auto'`
 
-There is no `neutral-4` prop value; containers are capped at `neutral-3`. Consumer components (e.g. Button) inherit the parent's `bg` via `data-on-bg`, and CSS handles the visual step-up.
+Consumer components (e.g. Button) inherit the parent's `bg` via `data-on-bg`, and CSS handles the visual step-up. See "Neutral level capping" below for details on how levels are bounded.
 
 **Hooks:**
 
 - `useBgProvider(bg?)` — for provider components. Returns `{ bg: undefined }` when no `bg` is given (transparent). Supports `'neutral-auto'` to auto-increment from the parent context.
 - `useBgConsumer()` — for consumer components. Returns the parent container's `bg` unchanged.
-- The old `useBg` hook and `UseBgOptions` interface have been removed.
 
 **Component roles:**
 
-- **Provider-only** (Box, Flex, Grid): set `data-bg`, wrap children in `BgProvider`. Transparent by default.
-- **Consumer-only** (Button, ButtonIcon, ButtonLink): set `data-on-bg`, inherit from parent.
-- **Provider + Consumer** (Card): sets both `data-bg` and `data-on-bg`, wraps children. Defaults to `neutral-auto`.
+- **Provider-only** (Box, Flex, Grid): set `data-bg`, wrap children in `BgProvider`. **Transparent by default** — they do _not_ auto-increment; pass `bg="neutral-auto"` explicitly if you want automatic neutral stepping.
+- **Consumer-only** (Button, ButtonIcon, ButtonLink): set `data-on-bg`, inherit the parent container's `bg` unchanged.
+- **Provider + Consumer** (Card): sets both `data-bg` and `data-on-bg`, wraps children. Card passes `bg="neutral-auto"` to its inner Box, so it auto-increments from the parent context.
+
+**Neutral level capping:**
+
+Provider components cap at `neutral-3`. There is no `neutral-4` prop value. The `neutral-4` level exists only in consumer component CSS — for example, a Button sitting on a `neutral-3` surface uses `neutral-4` tokens internally via `data-on-bg`.
 
 **Migration:**
 
@@ -86,6 +89,6 @@ Update CSS selectors targeting surface data attributes:
 + [data-on-bg='neutral-1'] { ... }
 ```
 
-Note: Provider components use `data-bg` (values: `neutral-1` through `neutral-3`, plus intents). Consumer components use `data-on-bg`, which reflects the parent container's `bg` directly.
+Note: Provider components use `data-bg` (values: `neutral-1` through `neutral-3`, plus intent values). Consumer components use `data-on-bg`, which reflects the parent container's `bg` directly. The `neutral-4` level never appears as a prop or `data-bg` value — it is used only in consumer CSS.
 
 **Affected components:** Box, Button, ButtonIcon, ButtonLink, ToggleButton, Card, Flex, Grid
diff --git a/packages/ui/src/hooks/useBg.tsx b/packages/ui/src/hooks/useBg.tsx
index 0b999ee097..6e298fedf9 100644
--- a/packages/ui/src/hooks/useBg.tsx
+++ b/packages/ui/src/hooks/useBg.tsx
@@ -86,9 +86,20 @@ export function useBgConsumer(): BgContextValue {
 /**
  * Hook for provider components (e.g. Box, Card) to resolve and provide bg context.
  *
- * - `bg` is `undefined` -- transparent, no context change, returns `{ bg: undefined }`
- * - `bg` is a `ContainerBg` value -- uses that value directly
- * - `bg` is `'neutral-auto'` -- increments from the parent context, capping at `neutral-3`
+ * **Resolution rules:**
+ *
+ * - `bg` is `undefined` -- transparent, no context change, returns `{ bg: undefined }`.
+ *   This is the default for Box, Flex, and Grid (they do **not** auto-increment).
+ * - `bg` is a `ContainerBg` value -- uses that value directly (e.g. `'neutral-1'`).
+ * - `bg` is `'neutral-auto'` -- increments the neutral level from the parent context,
+ *   capping at `neutral-3`. Only components that explicitly pass `'neutral-auto'`
+ *   (e.g. Card) will auto-increment; it is never implicit.
+ *
+ * **Capping:**
+ *
+ * Provider components cap at `neutral-3`. The `neutral-4` level is **not** a valid
+ * prop value -- it exists only in consumer component CSS (e.g. a Button on a
+ * `neutral-3` surface renders with `neutral-4` tokens via `data-on-bg`).
  *
  * The caller is responsible for wrapping children with `BgProvider` when the
  * resolved bg is defined.