@base44/app-plugin-commerce 0.4.0 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44/app-plugin-commerce",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Base44 Commerce plugin — entities, backend functions, shared commerce engine, admin UI and the commerce skill, shipped as copyable source",
   "keywords": [
     "base44",

package/skills/commerce/SKILL.md

@@ -112,6 +112,7 @@ Open a file when its work starts — not while planning.
 | [`references/catalog-rendering.md`](./references/catalog-rendering.md) | field shapes each catalog call returns, variant edge cases | 16K |
 | [`references/shipping-and-tax.md`](./references/shipping-and-tax.md) | zones beyond 03's recipe, taxes, day-2 edits | 8K |
 | [`references/online-payments.md`](./references/online-payments.md) | enabling card payments, or wiring the provider — at install or any time later | 8K |
+| [`references/storefront-styling.md`](./references/storefront-styling.md) | writing the CSS for the cart/checkout parts (selectors, geometry vars) | 5K |
 | [`references/storefront-custom.md`](./references/storefront-custom.md) | a custom cart row / checkout section on the raw hooks | 8K |
 | [`references/storefront-verification.md`](./references/storefront-verification.md) | driving the storefront from a browser script | 3K |
 | [`references/reviews.md`](./references/reviews.md) | review policies (login-gated, verified buyers), moderation | 5K |

package/skills/commerce/install/02-storefront.md

@@ -10,7 +10,7 @@ carry_forward:
   - "Branch custom hook-built UI on `status`, never on `isEmpty`/nullable data; every hook goes above its status guards."
   - "Variant options that aren't buyable render disabled, never hidden; one control per axis, never a list of variations."
   - "No copy ships: every word the parts render comes from the store's copy file (labels); a ⟨copy: …⟩ placeholder on screen is unfinished work."
-  - "Identity is encoded once — design classes in index.css (parts styled via [data-part] selectors) plus one or two signature moments per page."
+  - "Identity is encoded once — design classes in index.css (parts styled via [data-part] selectors, controls always among them) plus one or two signature moments per page."
 ---
 
 # 02 — Storefront
@@ -62,7 +62,7 @@ The cost driver of a generated storefront is not wiring — it is decoration rep
 
 A part renders one section's correct semantic markup — every branch, guard and aria attribute — and nothing else. Your markup arranges the parts (grid, order, sticky aside, accordion steps — a hidden part loses no state; the place-order gate still counts every blocker). Three inputs carry the identity:
 
-- **Styling.** Every element carries `data-part` + state attributes. Style in `index.css` — `[data-part="option"][data-state="selected"]`, `[data-part="row"][data-pending]` — and/or pass `className` (part root) and `classes` (keyed by the **same inner `data-part` names**: `classes={{ row: "bag-row", "line-total": "price" }}`). No part ships a class: browser-default means unfinished.
+- **Styling.** The parts ship **layout geometry only** — field grids, labels above full-width controls, square thumbnails, label-left/value-right totals, the drawer as a right-hand panel — and **no** color, border, radius, shadow or font, so an unstyled store reads as unfinished, never broken. The look is yours: every element carries `data-part` + state attributes (`[data-part="option"][data-state="selected"]`, `[data-part="row"][data-pending]`), each shipped rule sits at **specificity 0** (`:where()`), so a plain selector of yours always wins, and `className`/`classes` take the same names (`classes={{ row: "bag-row", "line-total": "price" }}`). ⚑ **Style the controls at minimum** — `[data-part="control"]`/`[data-part="input"]` need `border`, `background`, `color: inherit`, `font: inherit`, `padding` and a focus ring, or the store ships browser-default white boxes. Space *between* sections is your containers' `gap`; the parts add no outer margins. Selector inventory, the geometry's custom properties (`--commerce-gap`, `--commerce-media-size`, `--commerce-field-columns`, …) and what else repays styling: [`../references/storefront-styling.md`](../references/storefront-styling.md).
 - **Words.** The copy file below, passed once on `StorefrontProvider labels`; override per Root or part with the same shape. A missing key renders a visible `⟨copy: path⟩` and warns — never silent, never English.
 - **Navigation — never rendered, never assumed.** A gate renders *your* element when the state calls for it (function children hand you the data); `OrderReceived.PaymentLink` hands `{ url }` to your element; `Checkout.Root` requires `orderReceivedPath`. Nothing assumes a route, or even an anchor.
 
@@ -111,20 +111,6 @@ export const STORE_COPY = {
 
 Blocker lines are what a disabled place-order button says — one per code, naming the thing the customer can fix (`cart_loading`/`shipping_recalculating` are quiet transients, not errors); `shipping.*`/`payment.*` are the pickers' dead-ends, with the server's own message rendered instead where one exists. The key tree is frozen in code as `REQUIRED_LABEL_KEYS`.
 
-### `data-part` inventory
-
-| Part root | Inner `data-part`s | State attributes |
-|---|---|---|
-| `address-fields`; `ship-to-different` | field · label · required · control · error | `data-which`, `data-key`, `data-span`, `data-invalid` |
-| `shipping-methods` `payment-methods` | hint · option · option-input · option-label · option-cost / option-description · chosen | `data-state="selected"`, `data-syncing`, `data-severity` |
-| `lines` `items`; `notices` | row · media · name · attributes · quantity · line-total · error; notice; `lines` adds stepper · increase · decrease · remove | `data-pending`, `data-empty`, `data-code` |
-| `totals`; `payment-instructions` | row · label · value; description · account | `data-key`, `data-emphasis` |
-| `coupon-field` | input · apply · error · applied · code · remove | `data-busy` |
-| `place-order` · `order-error` · `blockers` | blocker | `data-state="placing"`, `data-code` |
-| `trigger` · `drawer` | overlay · panel; `close` | `data-state="open\|closed"` |
-
-Tailwind-first styling reaches inner parts with arbitrary variants (`[&_[data-part=option]]:flex …`) or `@apply` inside the design classes.
-
 ## What each hook resolves to
 
 Everything below is already unwrapped — no `.data`, no envelope; `formatMoney` is `useFormatMoney()`. This table serves the catalog surfaces and row/option overrides; the custom-section shapes (`useCartLine`, `useCartUI`, `useCheckoutContext`, `useOrderReturn`, `cartTotalsLines`/`orderTotalsLines`) live in [`../references/storefront-custom.md`](../references/storefront-custom.md).
@@ -345,7 +331,7 @@ import { OrderReceived } from "@/commerce/storefront";
 
 - [ ] Catalog UI in whatever form fits the store; cart (and/or drawer), checkout and `/order-received` built from the parts — all five receipt gates present, `PaymentInstructions` placed on unpaid.
 - [ ] One copy file passed via `<StorefrontProvider labels={…}>`, **every value rewritten in the store's voice** — no `⟨copy: …⟩` on any page, no reference-example sentence shipped verbatim; the buy button reads for all four `buy.state` values.
-- [ ] `index.css` defines the design classes; parts styled via `[data-part]`/`classes` — nothing left browser-default; pages carry class names, not repeated utility runs.
+- [ ] `index.css` defines the design classes; parts styled via `[data-part]`/`classes` — **controls carry border/background/font/padding + a focus ring**, option rows show their selected state, the drawer panel has a surface, nothing left browser-default; pages carry class names, not repeated utility runs.
 - [ ] **One** `<StorefrontProvider>` above every storefront route (layout-route pattern); no hand-rolled `cart_token`; imports from each section's import line.
 - [ ] Custom hook-built sections branch on `status` and never re-implement part/hook logic; gateways/currency/countries from `useStoreInfo()`/`useCountries()` only.
 - [ ] Coupon field placed if the store has coupons; a paging control whenever `hasNext`; ribbons in both the grid and the product page.

package/skills/commerce/references/storefront-styling.md

@@ -0,0 +1,99 @@
+---
+read_when: "You are writing the CSS for the cart, drawer, checkout or receipt — the parts' look."
+---
+
+# Styling the parts
+
+The parts ship **layout geometry and nothing else** (`src/commerce/storefront/parts/parts.css`,
+loaded automatically by `@/commerce/storefront`): field grids, labels above
+full-width controls, media as a fixed square, rows as media + content +
+controls with the money pushed right, totals as label-left/value-right, the
+drawer as a right-hand panel over a full-viewport overlay. Nothing in it
+carries color, background, border, radius, shadow, font or text decoration — a
+release check enforces that — so an unstyled store reads as *unfinished*, never
+as broken, and the look is entirely yours.
+
+**Every rule is wrapped in `:where()`, so its specificity is 0.** A plain
+`[data-part="row"] { display: grid }` in your stylesheet wins — no `!important`,
+no cascade fights, no need to know what the sheet did.
+
+## Two ways in, one vocabulary
+
+```css
+/* index.css — selectors, next to the store's design classes */
+[data-part="control"] { … }
+[data-part="option"][data-state="selected"] { … }
+[data-part="row"][data-pending] { opacity: .55; }
+```
+
+```jsx
+{/* or classes, keyed by the same data-part names */}
+<Cart.Lines className="bag" classes={{ row: "bag-row", media: "bag-thumb", "line-total": "price" }} />
+```
+
+Tailwind reaches inner parts with arbitrary variants
+(`className="[&_[data-part=option]]:choice-row"`) or `@apply` inside a design
+class. Either way the names are the ones below.
+
+## The minimum that makes a store look designed
+
+⚑ **Style the controls.** Browser-default inputs are a white box in a system
+font — on a dark or branded storefront that alone reads as unfinished:
+
+```css
+[data-part="control"], [data-part="input"] {
+  border: …; background: …; color: inherit; font: inherit; padding: …;
+}
+[data-part="control"]:focus-visible { outline: …; }      /* keep a visible focus ring */
+[data-part="field"][data-invalid] [data-part="control"] { border-color: …; }
+```
+
+Then, in the store's own values: the labels (`[data-part="label"]` — size,
+tracking, case), the option rows (`[data-part="option"]` — padding, border,
+and the `[data-state="selected"]` treatment, which is the one control customers
+look for), the totals (`[data-part="value"]`, `[data-emphasis]` for the total
+line), the buttons (`[data-part="place-order"]`, `apply`, `remove`,
+`increase`/`decrease`), the notices (`[data-part="error"]`, `blocker`, `hint` —
+`[data-severity="error"]` marks the loud ones), and the drawer surface
+(`[data-part="panel"]` needs a background of its own, `[data-part="overlay"]` a
+scrim).
+
+**The parts add no outer margins** — space *between* sections comes from the
+containers you wrap them in (`gap` on your checkout grid, your aside, your
+drawer panel's column).
+
+## Tuning the built-in geometry
+
+Set these anywhere — `:root`, a page, one part — instead of rewriting the rules:
+
+| Custom property | Default | Controls |
+|---|---|---|
+| `--commerce-gap` | `1rem` | fields, rows, options, panel sections |
+| `--commerce-gap-tight` | `0.4rem` | label→control, name→attributes, stepper |
+| `--commerce-field-columns` | `2` | address-form columns (set `1` in a narrow aside or a media query) |
+| `--commerce-media-size` | `4rem` | cart/summary thumbnail edge |
+| `--commerce-drawer-width` | `28rem` | drawer panel width |
+| `--commerce-drawer-z` | `50` | drawer stacking order (raise above a sticky header) |
+
+## `data-part` inventory
+
+| Part root | Inner `data-part`s | State attributes |
+|---|---|---|
+| `address-fields`; `ship-to-different` | field · label · required · control · error | `data-which`, `data-key`, `data-span`, `data-invalid` |
+| `shipping-methods` `payment-methods` | hint · option · option-input · option-label · option-cost / option-description · chosen | `data-state="selected"`, `data-syncing`, `data-severity` |
+| `lines` `items`; `notices` | row · media · content · name · attributes · controls · stepper · increase · decrease · quantity · remove · line-total · error; notice | `data-pending`, `data-empty`, `data-code` |
+| `totals`; `payment-instructions` | row · label · value; description · account | `data-key`, `data-emphasis` |
+| `coupon-field` | input · apply · error · applied · code · remove | `data-busy` |
+| `place-order` · `order-error` · `blockers` | blocker | `data-state="placing"`, `data-code` |
+| `trigger` · `drawer` | overlay · panel; `close` | `data-state="open\|closed"` |
+
+`media` is an `<img>` when the line has an image and an empty `<div
+data-part="media" data-empty>` when it doesn't — same box either way, so style
+the placeholder (`[data-empty]`) rather than letting it render as a hole.
+
+## When CSS isn't enough
+
+A control that needs different markup takes the part's render override
+(`inputRender`, `optionRender`, `lineRender`, `itemRender`, `fieldRender`) —
+your element, the part's wiring. A whole section that needs different structure
+drops to its hook: [`./storefront-custom.md`](./storefront-custom.md).

package/src/commerce/storefront/index.js

@@ -64,15 +64,19 @@
  * **Parts** — for the four commodity surfaces only (cart, drawer, checkout,
  * order-received), `Checkout.*` / `Cart.*` / `CartDrawer.*` /
  * `OrderReceived.*` render each section's correct semantic markup with zero
- * CSS, zero copy and zero navigation: you place them in YOUR layout, style
- * them via `data-part`/`data-state` selectors or `className`/`classes`, and
- * supply every word through `labels` (chain: part prop → page Root →
- * `<StorefrontProvider labels={…}>`; a missing key renders a visible
- * `⟨copy: …⟩` placeholder). Contract tables, the copy example and the
- * `data-part` inventory: the commerce skill's install/02-storefront.md — use
- * the parts from there, not from these files. They compose the hooks above,
- * so dropping one section down to its hook is normal; they are also the
- * app's own source, editable when a requirement outgrows their props.
+ * copy and zero navigation: you place them in YOUR layout, and supply every
+ * word through `labels` (chain: part prop → page Root → `<StorefrontProvider
+ * labels={…}>`; a missing key renders a visible `⟨copy: …⟩` placeholder).
+ * They carry **layout geometry and nothing else** (`parts/parts.css`: field
+ * grids, row and thumbnail sizing, totals rows, the drawer panel — no color,
+ * type or border, every rule at zero specificity), so an unstyled store looks
+ * unfinished but never broken; the look arrives as your CSS on
+ * `data-part`/`data-state`, or via `className`/`classes`. Contract tables, the
+ * copy example and the `data-part` inventory: the commerce skill's
+ * install/02-storefront.md — use the parts from there, not from these files.
+ * They compose the hooks above, so dropping one section down to its hook is
+ * normal; they are also the app's own source, editable when a requirement
+ * outgrows their props.
  */
 export {
   StorefrontProvider,
@@ -95,6 +99,11 @@ export {
 } from "./address";
 
 // ── parts: guided sections for the commodity surfaces ──────────────────────
+// The parts' layout geometry (field grids, row/media sizing, totals rows, the
+// drawer panel) — structure only, no look, every rule at zero specificity so
+// the store's CSS wins. See parts/parts.css for the custom properties.
+import "./parts/parts.css";
+
 export { Checkout } from "./parts/checkout";
 export { Cart } from "./parts/cart";
 export { CartDrawer } from "./parts/drawer";

package/src/commerce/storefront/parts/cart.jsx

@@ -61,45 +61,49 @@ function Lines({ lineRender, className, classes, labels: partLabels }) {
                 ) : (
                   <div data-part="media" data-empty="" className={classes?.media} />
                 )}
-                <span data-part="name" className={classes?.name}>{item.name}</span>
-                {attributesLabel(item.attributes) ? (
-                  <span data-part="attributes" className={classes?.attributes}>
-                    {attributesLabel(item.attributes)}
+                <span data-part="content" className={classes?.content}>
+                  <span data-part="name" className={classes?.name}>{item.name}</span>
+                  {attributesLabel(item.attributes) ? (
+                    <span data-part="attributes" className={classes?.attributes}>
+                      {attributesLabel(item.attributes)}
+                    </span>
+                  ) : null}
+                </span>
+                <span data-part="controls" className={classes?.controls}>
+                  <span data-part="stepper" className={classes?.stepper}>
+                    <button
+                      type="button"
+                      data-part="decrease"
+                      className={classes?.decrease}
+                      onClick={l.decrease}
+                      disabled={!l.canDecrease || l.pending}
+                      aria-label={nameLabel(L, "aria.decrease", item.name)}
+                    >
+                      −
+                    </button>
+                    <span data-part="quantity" className={classes?.quantity}>{l.quantity}</span>
+                    <button
+                      type="button"
+                      data-part="increase"
+                      className={classes?.increase}
+                      onClick={l.increase}
+                      disabled={!l.canIncrease || l.pending}
+                      aria-label={nameLabel(L, "aria.increase", item.name)}
+                    >
+                      +
+                    </button>
                   </span>
-                ) : null}
-                <span data-part="stepper" className={classes?.stepper}>
-                  <button
-                    type="button"
-                    data-part="decrease"
-                    className={classes?.decrease}
-                    onClick={l.decrease}
-                    disabled={!l.canDecrease || l.pending}
-                    aria-label={nameLabel(L, "aria.decrease", item.name)}
-                  >
-                    −
-                  </button>
-                  <span data-part="quantity" className={classes?.quantity}>{l.quantity}</span>
                   <button
                     type="button"
-                    data-part="increase"
-                    className={classes?.increase}
-                    onClick={l.increase}
-                    disabled={!l.canIncrease || l.pending}
-                    aria-label={nameLabel(L, "aria.increase", item.name)}
+                    data-part="remove"
+                    className={classes?.remove}
+                    onClick={l.remove}
+                    disabled={l.pending}
+                    aria-label={nameLabel(L, "aria.remove", item.name)}
                   >
-                    +
+                    ×
                   </button>
                 </span>
-                <button
-                  type="button"
-                  data-part="remove"
-                  className={classes?.remove}
-                  onClick={l.remove}
-                  disabled={l.pending}
-                  aria-label={nameLabel(L, "aria.remove", item.name)}
-                >
-                  ×
-                </button>
                 <span data-part="line-total" className={classes?.["line-total"]}>
                   {formatMoney(item.total)}
                 </span>

package/src/commerce/storefront/parts/checkout.jsx

@@ -1,4 +1,13 @@
-import React, { createContext, useCallback, useContext, useId, useMemo, useState } from "react";
+import React, {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useId,
+  useLayoutEffect,
+  useMemo,
+  useState,
+} from "react";
 import { addressFieldSpec, attributesLabel } from "@/commerce/utils";
 import { CheckoutProvider, useCheckoutContext } from "../useCheckout";
 import { ShippingMethodPicker, PaymentMethodPicker } from "../pickers";
@@ -19,6 +28,9 @@ import { CouponField, Totals } from "./shared";
 
 const CheckoutPartsContext = createContext(null);
 
+/** Layout effect where there is a DOM; plain effect on the server (no warning). */
+const useCommitEffect = typeof window === "undefined" ? useEffect : useLayoutEffect;
+
 /**
  * Mounts `CheckoutProvider`, resolves the page's phase once (`submitted` >
  * `loading` > `empty` > `form` — the ordering that kills the empty-bag flash
@@ -53,7 +65,16 @@ function RootPhase({ onPlaced, children }) {
         : status === "empty"
           ? "empty"
           : "form";
-  const value = useMemo(() => ({ phase, onPlaced }), [phase, onPlaced]);
+  // A page that places <Checkout.Blockers> itself must not ALSO get the copy
+  // `PlaceOrder` renders by default — the same three reasons printed twice is a
+  // real defect an eval caught. Standalone instances register here (before
+  // paint), and the button's own copy stands down while one exists.
+  const [ownBlockers, setOwnBlockers] = useState(0);
+  const registerBlockers = useCallback((delta) => setOwnBlockers((n) => n + delta), []);
+  const value = useMemo(
+    () => ({ phase, onPlaced, hasOwnBlockers: ownBlockers > 0, registerBlockers }),
+    [phase, onPlaced, ownBlockers, registerBlockers],
+  );
   return <CheckoutPartsContext.Provider value={value}>{children}</CheckoutPartsContext.Provider>;
 }
 
@@ -378,13 +399,15 @@ function Items({ itemRender, className, classes }) {
               ) : (
                 <div data-part="media" data-empty="" className={classes?.media} />
               )}
-              <span data-part="name" className={classes?.name}>{item.name}</span>
-              {attributesLabel(item.attributes) ? (
-                <span data-part="attributes" className={classes?.attributes}>
-                  {attributesLabel(item.attributes)}
-                </span>
-              ) : null}
-              <span data-part="quantity" className={classes?.quantity}>{item.quantity}</span>
+              <span data-part="content" className={classes?.content}>
+                <span data-part="name" className={classes?.name}>{item.name}</span>
+                {attributesLabel(item.attributes) ? (
+                  <span data-part="attributes" className={classes?.attributes}>
+                    {attributesLabel(item.attributes)}
+                  </span>
+                ) : null}
+              </span>
+              <span data-part="quantity" className={classes?.quantity}>×{item.quantity}</span>
               <span data-part="line-total" className={classes?.["line-total"]}>
                 {formatMoney(item.total)}
               </span>
@@ -399,12 +422,20 @@ function Items({ itemRender, className, classes }) {
 /**
  * The blocker lines — what still stands between the customer and the order,
  * one line per code in the store's words, gone when the order can be placed.
- * `PlaceOrder` renders these itself; use this part only to place them
- * elsewhere (then pass `showBlockers={false}` to the button).
+ * `PlaceOrder` renders these next to the button by default; placing this part
+ * anywhere under `Checkout.Root` moves them there instead — the button's own
+ * copy stands down automatically, so the reasons are never printed twice.
  */
-function Blockers({ className, classes, labels: partLabels }) {
+function Blockers({ standalone = true, className, classes, labels: partLabels }) {
   const checkout = useCheckoutContext();
+  const { registerBlockers } = usePartsContext("Blockers");
   const L = useResolvedLabels(partLabels);
+  // Registered before paint, so the button's built-in copy never flashes.
+  useCommitEffect(() => {
+    if (!standalone) return undefined;
+    registerBlockers(1);
+    return () => registerBlockers(-1);
+  }, [standalone, registerBlockers]);
   if (checkout.canPlaceOrder) return null;
   return (
     <div data-part="blockers" className={className}>
@@ -425,7 +456,7 @@ function Blockers({ className, classes, labels: partLabels }) {
  */
 function PlaceOrder({ showBlockers = true, className, classes, labels: partLabels }) {
   const checkout = useCheckoutContext();
-  const { onPlaced } = usePartsContext("PlaceOrder");
+  const { onPlaced, hasOwnBlockers } = usePartsContext("PlaceOrder");
   const L = useResolvedLabels(partLabels);
   const place = useCallback(async () => {
     const res = await checkout.placeOrder(); // resolves {ok:false} — never throws
@@ -448,7 +479,9 @@ function PlaceOrder({ showBlockers = true, className, classes, labels: partLabel
           {checkout.orderError.message}
         </p>
       )}
-      {showBlockers && <Blockers className={classes?.blockers} labels={partLabels} />}
+      {showBlockers && !hasOwnBlockers && (
+        <Blockers standalone={false} className={classes?.blockers} labels={partLabels} />
+      )}
     </>
   );
 }

package/src/commerce/storefront/parts/orderReceived.jsx

@@ -80,11 +80,13 @@ function Items({ itemRender, className, classes }) {
               ) : (
                 <div data-part="media" data-empty="" className={classes?.media} />
               )}
-              <span data-part="name" className={classes?.name}>{line.name}</span>
-              {line.attributesLabel ? (
-                <span data-part="attributes" className={classes?.attributes}>{line.attributesLabel}</span>
-              ) : null}
-              <span data-part="quantity" className={classes?.quantity}>{line.quantity}</span>
+              <span data-part="content" className={classes?.content}>
+                <span data-part="name" className={classes?.name}>{line.name}</span>
+                {line.attributesLabel ? (
+                  <span data-part="attributes" className={classes?.attributes}>{line.attributesLabel}</span>
+                ) : null}
+              </span>
+              <span data-part="quantity" className={classes?.quantity}>×{line.quantity}</span>
               <span data-part="line-total" className={classes?.["line-total"]}>{line.totalLabel}</span>
             </>
           )}

package/src/commerce/storefront/parts/parts.css

@@ -0,0 +1,232 @@
+/**
+ * Layout geometry for the commerce parts — **structure only, never a look.**
+ *
+ * The parts render correct markup; this sheet makes that markup *lay out*
+ * correctly: labels above full-width controls in a two-column address grid, a
+ * cart row as media + content + controls, totals as label-left/value-right,
+ * a drawer that is actually a right-hand panel over an overlay. Without it
+ * every store re-derives the same geometry from scratch, and a storefront that
+ * gets it wrong reads as broken (staggered input widths, a product thumbnail
+ * blown up to the column width, "SetColor: Magenta1$89.00" with no gaps).
+ *
+ * What this sheet deliberately does NOT contain — the store's identity, and
+ * the reason an unstyled storefront still looks unfinished rather than
+ * finished-and-generic: no color, no background, no border (beyond zeroing the
+ * ones the browser puts on elements the parts chose, like `fieldset`), no
+ * radius, no shadow, no font, no text decoration. A release check enforces
+ * that list, so this file cannot drift into a theme.
+ *
+ * **Overriding is free.** Every rule is wrapped in `:where()`, so its
+ * specificity is 0 — any selector the store writes wins without `!important`,
+ * including a bare `[data-part="row"] { … }`. Tune the built-in geometry
+ * through the custom properties below (set them on `:root`, a page, or one
+ * part), or replace a rule outright.
+ *
+ *   :root {
+ *     --commerce-gap: 1rem;            gap between fields, rows, options
+ *     --commerce-gap-tight: 0.4rem;    label→control, name→attributes
+ *     --commerce-field-columns: 2;     address-form columns (1 on narrow)
+ *     --commerce-media-size: 4rem;     cart/summary thumbnail edge
+ *     --commerce-drawer-width: 28rem;  drawer panel width
+ *     --commerce-drawer-z: 50;         drawer stacking context
+ *   }
+ *
+ * Loaded automatically: `@/commerce/storefront` imports this file. With a
+ * bundler that does not take CSS imports from JS, delete that import line and
+ * `@import "@/commerce/storefront/parts/parts.css";` from the app's stylesheet
+ * instead.
+ */
+
+:where([data-part]) {
+  box-sizing: border-box;
+}
+
+/* ── address form ─────────────────────────────────────────────────────────── */
+:where([data-part="address-fields"]) {
+  display: grid;
+  grid-template-columns: repeat(var(--commerce-field-columns, 2), minmax(0, 1fr));
+  gap: var(--commerce-gap, 1rem);
+}
+:where([data-part="field"]) {
+  display: grid;
+  align-content: start;
+  gap: var(--commerce-gap-tight, 0.4rem);
+  min-inline-size: 0;
+}
+:where([data-part="field"][data-span="2"]) {
+  grid-column: 1 / -1;
+}
+:where([data-part="label"]) {
+  display: block;
+}
+:where([data-part="control"]) {
+  inline-size: 100%;
+  min-inline-size: 0;
+}
+:where([data-part="ship-to-different"]) {
+  display: flex;
+  align-items: center;
+  gap: var(--commerce-gap-tight, 0.4rem);
+}
+:where([data-part="ship-to-different"] [data-part="control"]) {
+  inline-size: auto;
+  flex: none;
+}
+
+/* ── shipping / payment choices ───────────────────────────────────────────── */
+:where([data-part="shipping-methods"], [data-part="payment-methods"]) {
+  display: grid;
+  gap: var(--commerce-gap-tight, 0.4rem);
+  /* the parts chose <fieldset>; neutralize what the browser draws on it */
+  margin: 0;
+  padding: 0;
+  border: 0;
+  min-inline-size: 0;
+}
+:where([data-part="option"], [data-part="chosen"]) {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--commerce-gap-tight, 0.4rem);
+  margin: 0;
+}
+:where([data-part="option-input"]) {
+  flex: none;
+}
+:where([data-part="option-cost"]) {
+  margin-inline-start: auto;
+}
+:where([data-part="option-description"]) {
+  flex-basis: 100%;
+}
+
+/* ── line rows: cart lines, checkout summary, receipt items ───────────────── */
+:where([data-part="lines"], [data-part="items"], [data-part="notices"]) {
+  display: grid;
+  gap: var(--commerce-gap, 1rem);
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+:where([data-part="row"]) {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--commerce-gap-tight, 0.4rem);
+  min-inline-size: 0;
+}
+:where([data-part="media"]) {
+  flex: none;
+  inline-size: var(--commerce-media-size, 4rem);
+  max-inline-size: 100%;
+  aspect-ratio: 1;
+  object-fit: cover;
+}
+:where(img[data-part="media"]) {
+  display: block;
+  block-size: auto;
+}
+:where([data-part="content"]) {
+  display: grid;
+  align-content: center;
+  gap: calc(var(--commerce-gap-tight, 0.4rem) / 2);
+  flex: 1 1 8rem;
+  min-inline-size: 0;
+}
+:where([data-part="controls"]) {
+  display: flex;
+  align-items: center;
+  gap: var(--commerce-gap-tight, 0.4rem);
+  flex: none;
+}
+:where([data-part="stepper"]) {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--commerce-gap-tight, 0.4rem);
+}
+:where([data-part="line-total"]) {
+  margin-inline-start: auto;
+}
+:where([data-part="row"] [data-part="error"]) {
+  flex-basis: 100%;
+  margin: 0;
+}
+
+/* ── totals, payment instructions (label ↔ value pairs) ───────────────────── */
+:where([data-part="totals"], [data-part="account"]) {
+  display: grid;
+  gap: var(--commerce-gap-tight, 0.4rem);
+  margin: 0;
+}
+:where([data-part="totals"] > *, [data-part="account"] > *) {
+  display: flex;
+  align-items: baseline;
+  gap: var(--commerce-gap-tight, 0.4rem);
+  min-inline-size: 0;
+}
+:where([data-part="value"]) {
+  margin: 0;
+  margin-inline-start: auto;
+}
+
+/* ── coupon field ─────────────────────────────────────────────────────────── */
+:where([data-part="coupon-field"]) {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--commerce-gap-tight, 0.4rem);
+}
+:where([data-part="coupon-field"] [data-part="input"]) {
+  flex: 1 1 10rem;
+  min-inline-size: 0;
+}
+:where([data-part="coupon-field"] [data-part="error"], [data-part="applied"]) {
+  flex-basis: 100%;
+  margin: 0;
+}
+:where([data-part="applied"]) {
+  display: flex;
+  align-items: center;
+  gap: var(--commerce-gap-tight, 0.4rem);
+}
+
+/* ── place order + its reasons ─────────────────────────────────────────────── */
+:where([data-part="blockers"]) {
+  display: grid;
+  gap: calc(var(--commerce-gap-tight, 0.4rem) / 2);
+}
+:where([data-part="blocker"], [data-part="order-error"], [data-part="hint"]) {
+  margin: 0;
+}
+
+/* ── payment instructions ─────────────────────────────────────────────────── */
+:where([data-part="payment-instructions"]) {
+  display: grid;
+  gap: var(--commerce-gap, 1rem);
+}
+:where([data-part="description"]) {
+  margin: 0;
+}
+
+/* ── cart drawer: a panel over an overlay, not a block in the header ───────── */
+:where([data-part="drawer"]) {
+  position: fixed;
+  inset: 0;
+  z-index: var(--commerce-drawer-z, 50);
+  display: flex;
+  justify-content: flex-end;
+}
+:where([data-part="overlay"]) {
+  position: absolute;
+  inset: 0;
+}
+:where([data-part="panel"]) {
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  gap: var(--commerce-gap, 1rem);
+  inline-size: min(var(--commerce-drawer-width, 28rem), 100%);
+  max-inline-size: 100%;
+  block-size: 100%;
+  overflow-y: auto;
+}