commerce-components-follow-up

.changeset/storefront-wrapper-backgrounds.md

@@ -0,0 +1,5 @@
+---
+'@godaddy/gd-commerce-storefront': patch
+---
+
+Keep storefront component wrappers transparent when setting the commerce surface palette. Preserve opaque themed backgrounds for controls and the cart drawer. Applications that need a catalog or product section background should set it on their own layout elements.

packages/commerce-storefront/README.md

@@ -84,7 +84,7 @@ A connection failure leaves the surrounding application and its state mounted. C
 
 The stylesheet includes all required utilities and scopes them to the package's surfaces. The build removes CSS layer wrappers in their declared order, so the exported CSS can pass through a host Tailwind v3 PostCSS pipeline without `@tailwind` directives. Import it directly; consumers do not need to copy or rewrite the CSS. It does not add a global reset or require dependency scanning by a host Tailwind build. The `theme` prop reaches the drawer even though it is portalled into `document.body`.
 
-By default, `.commerce-storefront` wrappers have transparent backgrounds and inherit the host's text color. Set `--commerce-surface` and `--commerce-text` to explicitly color those wrappers. Controls, muted text, borders, and the drawer retain their neutral palette defaults; set both variables to adapt them to a dark theme. Descendants inherit the surface text and body font instead of global heading styles. Keep text, controls and focus indicators accessible when changing colors. Utility class names and internal markup are not a customization API.
+By default, `.commerce-storefront` wrappers do not paint a background and inherit the host's text color. Set page and section backgrounds on the host application's layout elements. `--commerce-surface` colors controls and the opaque cart drawer, and supplies the base for muted colors; it does not color component wrappers. Set `--commerce-surface` and `--commerce-text` together to adapt controls and the drawer to a dark theme. Avoid setting wrapper backgrounds through CSS or the `theme` prop's `background`, `backgroundColor`, or `backgroundImage` properties, which can still override the transparent default. Descendants inherit the surface text and body font instead of global heading styles. Keep text, controls and focus indicators accessible when changing colors. Utility class names and internal markup are not a customization API.
 
 The first release uses English UI text and `en-US` currency formatting. Catalog title and description are configurable. Full localization and arbitrary component slots are outside this initial API.
 

packages/commerce-storefront/src/artifacts.test.ts

@@ -38,7 +38,7 @@ it('ships a client package with framework peers external and no server dependenc
   expect(pkg.exports['./styles.css']).toBe('./dist/styles.css');
 });
 
-it('defaults to host text and transparent surfaces before applying utilities', async () => {
+it('inherits host text without painting wrappers while retaining opaque themed controls', async () => {
   const css = postcss.parse(await readFile(new URL('../dist/styles.css', import.meta.url), 'utf8'));
   const declarations: Record<string, string> = {};
   css.walkRules('.commerce-storefront', (rule) => {
@@ -47,7 +47,15 @@ it('defaults to host text and transparent surfaces before applying utilities', a
     });
   });
   expect(declarations.color).toBe('var(--commerce-text, inherit)');
-  expect(declarations['background-color']).toBe('var(--commerce-surface, transparent)');
+  expect(declarations['background-color']).toBeUndefined();
+  expect(declarations.background).toBeUndefined();
+  const controlDeclarations: Record<string, string> = {};
+  css.walkRules('.commerce-storefront .bg-white', (rule) => {
+    rule.walkDecls((declaration) => {
+      controlDeclarations[declaration.prop] = declaration.value;
+    });
+  });
+  expect(controlDeclarations['background-color']).toBe('var(--commerce-surface, #fff)');
   const resets: Record<string, string> = {};
   css.walkRules('.commerce-storefront :where(*)', (rule) => {
     rule.walkDecls((declaration) => {

packages/commerce-storefront/src/styles.css

@@ -19,7 +19,7 @@
 }
 
 @layer base {
-  .commerce-storefront { color: var(--commerce-text, inherit); background-color: var(--commerce-surface, transparent); font-family: inherit; line-height: 1.5; }
+  .commerce-storefront { color: var(--commerce-text, inherit); font-family: inherit; line-height: 1.5; }
   .commerce-storefront :where(*) { color: inherit; font-family: inherit; }
   .commerce-storefront *, .commerce-storefront *::before, .commerce-storefront *::after {
     box-sizing: border-box; border-width: 0; border-style: solid;
@@ -31,6 +31,6 @@
   .commerce-storefront :where(a) { color: inherit; text-decoration: inherit; }
   .commerce-storefront :where(img) { display: block; max-width: 100%; }
   .commerce-storefront :where(ul) { list-style: none; }
-  .commerce-inline { display: inline-block; background-color: transparent; }
+  .commerce-inline { display: inline-block; }
   .commerce-sr-only { position: absolute; width: 1px; height: 1px; padding: 0; margin: -1px; overflow: hidden; clip-path: inset(50%); white-space: nowrap; border-width: 0; }
 }