paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 31 Packages Projects Releases Wiki Activity

Cleanup

Browse Source 
Signed-off-by: Charles de Dreuille <charles.dedreuille@gmail.com>
This commit is contained in:
Charles de Dreuille
2026-02-11 10:36:32 +00:00
parent 0fe7bf12be
commit 048d9c47d4
2 changed files with 23 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.changeset/clean-bags-occur.md
+9 -6
View File
@@ -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
packages/ui/src/hooks/useBg.tsx
+14 -3
View File
@@ -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.