diff --git a/docs-ui/src/app/snippets.ts b/docs-ui/src/app/snippets.ts
index e16463a085..4a93c31831 100644
--- a/docs-ui/src/app/snippets.ts
+++ b/docs-ui/src/app/snippets.ts
@@ -1,19 +1,19 @@
export const surfacesSnippet = `
-
+
-
+
`;
-export const adaptiveSnippet = `
+export const adaptiveSnippet = `
{/* automatically set background to neutral-2 */}
`;
-export const customCardSnippet = `
+export const customCardSnippet = `
Hello World
`;
diff --git a/packages/ui/report.api.md b/packages/ui/report.api.md
index 3ca30cd73c..1a015747a8 100644
--- a/packages/ui/report.api.md
+++ b/packages/ui/report.api.md
@@ -1012,14 +1012,7 @@ export const FlexDefinition: {
'direction',
];
readonly dataAttributes: {
- readonly bg: readonly [
- 'neutral-1',
- 'neutral-2',
- 'neutral-3',
- 'danger',
- 'warning',
- 'success',
- ];
+ readonly bg: readonly ['neutral', 'danger', 'warning', 'success'];
};
};
@@ -1096,14 +1089,7 @@ export const GridDefinition: {
'py',
];
readonly dataAttributes: {
- readonly bg: readonly [
- 'neutral-1',
- 'neutral-2',
- 'neutral-3',
- 'danger',
- 'warning',
- 'success',
- ];
+ readonly bg: readonly ['neutral', 'danger', 'warning', 'success'];
};
};
@@ -1114,14 +1100,7 @@ export const GridItemDefinition: {
};
readonly utilityProps: ['colSpan', 'colEnd', 'colStart', 'rowSpan'];
readonly dataAttributes: {
- readonly bg: readonly [
- 'neutral-1',
- 'neutral-2',
- 'neutral-3',
- 'danger',
- 'warning',
- 'success',
- ];
+ readonly bg: readonly ['neutral', 'danger', 'warning', 'success'];
};
};
diff --git a/packages/ui/src/components/Flex/definition.ts b/packages/ui/src/components/Flex/definition.ts
index d0452d6b2c..2701ce5e10 100644
--- a/packages/ui/src/components/Flex/definition.ts
+++ b/packages/ui/src/components/Flex/definition.ts
@@ -45,13 +45,6 @@ export const FlexDefinition = {
'direction',
],
dataAttributes: {
- bg: [
- 'neutral-1',
- 'neutral-2',
- 'neutral-3',
- 'danger',
- 'warning',
- 'success',
- ] as const,
+ bg: ['neutral', 'danger', 'warning', 'success'] as const,
},
} as const satisfies ComponentDefinition;
diff --git a/packages/ui/src/components/Grid/definition.ts b/packages/ui/src/components/Grid/definition.ts
index c3acb59274..2f417ab34b 100644
--- a/packages/ui/src/components/Grid/definition.ts
+++ b/packages/ui/src/components/Grid/definition.ts
@@ -43,14 +43,7 @@ export const GridDefinition = {
'py',
],
dataAttributes: {
- bg: [
- 'neutral-1',
- 'neutral-2',
- 'neutral-3',
- 'danger',
- 'warning',
- 'success',
- ] as const,
+ bg: ['neutral', 'danger', 'warning', 'success'] as const,
},
} as const satisfies ComponentDefinition;
@@ -64,13 +57,6 @@ export const GridItemDefinition = {
},
utilityProps: ['colSpan', 'colEnd', 'colStart', 'rowSpan'],
dataAttributes: {
- bg: [
- 'neutral-1',
- 'neutral-2',
- 'neutral-3',
- 'danger',
- 'warning',
- 'success',
- ] as const,
+ bg: ['neutral', 'danger', 'warning', 'success'] as const,
},
} as const satisfies ComponentDefinition;
diff --git a/packages/ui/src/hooks/useBg.tsx b/packages/ui/src/hooks/useBg.tsx
index e67c47da49..2284e5f337 100644
--- a/packages/ui/src/hooks/useBg.tsx
+++ b/packages/ui/src/hooks/useBg.tsx
@@ -108,10 +108,14 @@ export function useBgConsumer(): BgContextValue {
*
* - `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 `'neutral'` -- increments the neutral level from the parent context,
- * capping at `neutral-3`. The increment is always relative to the parent; it is
- * not possible to pin a container to an explicit neutral level.
- * - `bg` is `'danger'` | `'warning'` | `'success'` -- used as-is.
+ * - `bg` is `'neutral'` -- when the parent bg is neutral, increments the neutral
+ * level from the parent context, capping at `neutral-3`. When the parent bg is
+ * an intent (`'danger'` | `'warning'` | `'success'`), the intent passes through
+ * unchanged (i.e. `bg: 'neutral'` does not override the parent intent). The
+ * increment is always relative to the parent; it is not possible to pin a
+ * container to an explicit neutral level.
+ * - `bg` is `'danger'` | `'warning'` | `'success'` -- sets the bg to that intent
+ * explicitly, regardless of the parent value.
*
* **Capping:**
*