Fix storefront wrapper theme inheritance

.changeset/transparent-storefront-surfaces.md

@@ -0,0 +1,5 @@
+---
+'@godaddy/gd-commerce-storefront': patch
+---
+
+Default storefront wrappers to transparent backgrounds and inherited text colors so they blend into the host theme, while preserving explicit commerce theme overrides.

packages/commerce-storefront/README.md

@@ -54,7 +54,7 @@ Use the providers your application already has; do not create another router or
 | `catalogPath` | `/shop` | Same-origin catalog route |
 | `productPath` | `/products` | Same-origin prefix for product links; register `${productPath}/:productId` |
 | `checkoutSuccessPath` | unset | Same-origin return route; enables checkout UI only when supplied |
-| `theme` | neutral palette | CSS custom properties applied to storefront surfaces and the portalled drawer |
+| `theme` | inherited text and transparent wrappers; neutral control palette | CSS custom properties applied to storefront surfaces and the portalled drawer |
 
 Provide root-relative paths without a trailing slash. Enable `checkoutSuccessPath` only after your server supports checkout and validates merchant readiness. Mount a corresponding return page. A redirect back from checkout is **not proof of payment**; that page must obtain authoritative payment status from your server. This package does not provide a payment receipt page or merchant onboarding.
 
@@ -82,7 +82,9 @@ A connection failure leaves the surrounding application and its state mounted. C
 </CommerceStorefront>
 ```
 
-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`. Surfaces pair `--commerce-surface` with `--commerce-text`; muted text and borders adapt to that pair. 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 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.
 
 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,16 +38,16 @@ it('ships a client package with framework peers external and no server dependenc
   expect(pkg.exports['./styles.css']).toBe('./dist/styles.css');
 });
 
-it('pairs surface colors and resets host descendant typography before applying utilities', async () => {
+it('defaults to host text and transparent surfaces before applying utilities', 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) => {
     rule.walkDecls((declaration) => {
       declarations[declaration.prop] = declaration.value;
     });
   });
-  expect(declarations.color).toBe('var(--commerce-text, #171717)');
-  expect(declarations['background-color']).toBe('var(--commerce-surface, #fff)');
+  expect(declarations.color).toBe('var(--commerce-text, inherit)');
+  expect(declarations['background-color']).toBe('var(--commerce-surface, transparent)');
   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, #171717); background-color: var(--commerce-surface, #fff); font-family: inherit; line-height: 1.5; }
+  .commerce-storefront { color: var(--commerce-text, inherit); background-color: var(--commerce-surface, transparent); 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;