@liquidcommerce/elements-sdk 2.6.0-beta.12 → 2.6.0-beta.121

package/docs/v1/getting-started/quick-start.md

@@ -0,0 +1,410 @@
+# Quick Start
+
+Get a product display with add-to-cart functionality working on your page in under 5 minutes.
+
+## What You'll Build
+
+A fully functional product page with:
+- Product images and details
+- Size selection
+- Fulfillment options (shipping/on-demand delivery)
+- Add to cart button
+- Shopping cart drawer
+- Complete checkout flow
+
+## Prerequisites
+
+- A LiquidCommerce API key (contact your LiquidCommerce representative)
+- A product identifier
+- A web page or HTML file
+
+## Step 1: Add the SDK Script
+
+Add the Elements SDK script tag to your HTML `<head>`:
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <title>My Product Page</title>
+  <script
+    defer
+    data-liquid-commerce-elements
+    data-token="YOUR_API_KEY"
+    data-env="production"
+    type="text/javascript"
+    src="https://elements.reservebar-worker.workers.dev/all/elements.js"
+  ></script>
+</head>
+<body>
+  <!-- We'll add the product here -->
+</body>
+</html>
+```
+
+**Replace `YOUR_API_KEY`** with your actual API key.
+
+## Step 2: Add a Product Container
+
+Create a container where the product will be displayed:
+
+```html
+<body>
+  <h1>Our Premium Whiskey</h1>
+  
+  <!-- Product will be injected here -->
+  <div id="product-display"></div>
+</body>
+```
+
+## Step 3: Configure the Product (Declarative)
+
+Add product configuration using HTML data attributes on the script tag:
+
+```html
+<script
+  defer
+  data-liquid-commerce-elements
+  data-token="YOUR_API_KEY"
+  data-env="production"
+  data-container-1="product-display"
+  data-product-1="00619947000020"
+  type="text/javascript"
+  src="https://elements.reservebar-worker.workers.dev/all/elements.js"
+></script>
+```
+
+**New attributes:**
+- `data-container-1="product-display"` - Points to the container ID
+- `data-product-1="00619947000020"` - The product identifier
+
+The numbers (1) connect the container to its product. For multiple products, increment the number:
+- `data-container-2` with `data-product-2`
+- `data-container-3` with `data-product-3`
+- etc.
+
+## Complete Example
+
+Here's the complete HTML for a working product page:
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Premium Whiskey - Buy Online</title>
+  
+  <script
+    defer
+    data-liquid-commerce-elements
+    data-token="YOUR_API_KEY"
+    data-env="production"
+    data-container-1="product-display"
+    data-product-1="00619947000020"
+    type="text/javascript"
+    src="https://elements.reservebar-worker.workers.dev/all/elements.js"
+  ></script>
+  
+  <style>
+    body {
+      font-family: Arial, sans-serif;
+      max-width: 1200px;
+      margin: 0 auto;
+      padding: 20px;
+    }
+    h1 {
+      text-align: center;
+    }
+  </style>
+</head>
+<body>
+  <h1>Our Premium Whiskey</h1>
+  <div id="product-display"></div>
+</body>
+</html>
+```
+
+That's it! Save the file and open it in a browser. You should see:
+1. Product images in a carousel
+2. Product name and description
+3. Size selector
+4. Fulfillment type selector (shipping/delivery)
+5. Retailer selection
+6. Add to cart button
+
+When you click "Add to Cart," a cart drawer slides in from the right with checkout functionality.
+
+## Alternative: Programmatic Setup
+
+If you prefer JavaScript over HTML attributes:
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <title>My Product Page</title>
+  <script
+    defer
+    data-liquid-commerce-elements
+    data-token="YOUR_API_KEY"
+    data-env="production"
+    type="text/javascript"
+    src="https://elements.reservebar-worker.workers.dev/all/elements.js"
+  ></script>
+  
+  <script defer>
+    // Wait for SDK to be ready
+    window.addEventListener('lce:actions.client_ready', async (event) => {
+      const client = window.LiquidCommerce.elements;
+      
+      // Inject the product
+      await client.injectProductElement([
+        {
+          containerId: 'product-display',
+          identifier: '00619947000020'
+        }
+      ]);
+    }, { once: true });
+  </script>
+</head>
+<body>
+  <h1>Our Premium Whiskey</h1>
+  <div id="product-display"></div>
+</body>
+</html>
+```
+
+Or with NPM:
+
+```javascript
+import { Elements } from '@liquidcommerce/elements-sdk';
+
+async function initProduct() {
+  // Elements() resolves to `null` if initialization fails — it never throws.
+  const client = await Elements('YOUR_API_KEY', {
+    env: 'production'
+  });
+
+  if (!client) {
+    return;
+  }
+
+  await client.injectProductElement([
+    {
+      containerId: 'product-display',
+      identifier: '00619947000020'
+    }
+  ]);
+}
+
+initProduct();
+```
+
+## Multiple Products
+
+To display multiple products on one page:
+
+```html
+<script
+  defer
+  data-liquid-commerce-elements
+  
+  data-token="YOUR_API_KEY"
+  data-env="production"
+  
+  data-container-1="product-1"
+  data-product-1="00619947000020"
+  data-container-2="product-2"
+  data-product-2="08504405135"
+  data-container-3="product-3"
+  data-product-3="08068660001"
+  
+  type="text/javascript"
+  src="https://elements.reservebar-worker.workers.dev/all/elements.js"
+></script>
+
+<div id="product-1"></div>
+<div id="product-2"></div>
+<div id="product-3"></div>
+```
+
+Or programmatically:
+
+```javascript
+await client.injectProductElement([
+  { containerId: 'product-1', identifier: '00619947000020' },
+  { containerId: 'product-2', identifier: '08504405135' },
+  { containerId: 'product-3', identifier: '08068660001' }
+]);
+```
+
+## What Happens Automatically
+
+The SDK handles everything for you:
+
+1. **Address Collection** - If needed, prompts for delivery location
+2. **Availability Check** - Shows only available fulfillment options
+3. **Cart Management** - Maintains cart across page refreshes and tabs
+4. **Checkout Flow** - Complete payment and order processing
+5. **Error Handling** - Graceful error messages and recovery
+6. **Mobile Responsiveness** - Works on all screen sizes
+
+## Customization
+
+Want to customize the look, visit the Elements Builder in our [Partner Portal](https://app.liquidcommerce.co/)? Want to manually override your theme, you can pass a `customTheme: IClientCustomThemeConfig` configuration:
+
+```html
+<script>
+window.addEventListener('lce:actions.client_ready', async () => {
+  const client = window.LiquidCommerce.elements;
+  
+  // You can customize after initialization
+  // See Theming Guide for more options
+}, { once: true });
+</script>
+```
+
+Or with NPM:
+
+```javascript
+const client = await Elements('YOUR_API_KEY', {
+  env: 'production',
+  customTheme: {
+    global: {
+      theme: {
+        primaryColor: '#007bff',
+        buttonCornerRadius: '8px',
+        headingFont: {
+          name: 'Poppins',
+          weights: [400, 600]
+        }
+      }
+    }
+  }
+});
+```
+
+## Testing Different Products
+
+To test with different products, simply change the product identifier:
+
+```html
+<!-- Replace with your product UPC -->
+data-product-1="YOUR_PRODUCT_IDENTIFIER"
+```
+
+Contact your LiquidCommerce representative for available product identifiers.
+
+## Troubleshooting
+
+### Product Not Showing
+
+1. **Check the browser console** for errors
+2. **Verify your API key** is correct
+3. **Confirm the product identifier** exists in your catalog
+4. **Check the container ID** matches your HTML
+
+### Styling Issues
+
+The product uses Shadow DOM for style encapsulation. To customize:
+
+- Use the `customTheme` configuration option
+- See [Theming Guide](../guides/theming.md) for detailed customization
+
+### Cart Not Opening
+
+The cart should open automatically after adding a product. If it doesn't:
+
+1. Check browser console for JavaScript errors
+2. Verify no other scripts are conflicting
+3. Try manually opening: `window.LiquidCommerce.elements.actions.cart.openCart()`
+
+## Next Steps
+
+Now that you have a basic product working:
+
+- **[Core Concepts](./concepts.md)** - Understand how the SDK works
+- **[Product Component Guide](../guides/product-component.md)** - Deep dive into product features
+- **[Cart Component Guide](../guides/cart-component.md)** - Learn about cart functionality
+- **[Checkout Component Guide](../guides/checkout-component.md)** - Customize the checkout experience
+- **[Theming Guide](../guides/theming.md)** - Make it match your brand
+- **[Events](../guides/events.md)** - React to user actions
+- **[API Reference](../api/client.md)** - Explore all available methods
+
+## Complete Working Example
+
+Try this complete example with your API key:
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Whiskey Shop</title>
+  
+  <script
+    defer
+    data-liquid-commerce-elements
+    data-token="YOUR_API_KEY"
+    data-env="production"
+    data-container-1="product"
+    data-product-1="00619947000020"
+    type="text/javascript"
+    src="https://elements.reservebar-worker.workers.dev/all/elements.js"
+  ></script>
+  
+  <style>
+    * {
+      margin: 0;
+      padding: 0;
+      box-sizing: border-box;
+    }
+    
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Arial, sans-serif;
+      background: #f5f5f5;
+    }
+    
+    header {
+      background: white;
+      padding: 20px;
+      box-shadow: 0 2px 4px rgba(0,0,0,0.1);
+      margin-bottom: 40px;
+    }
+    
+    .container {
+      max-width: 1200px;
+      margin: 0 auto;
+      padding: 0 20px;
+    }
+    
+    h1 {
+      text-align: center;
+      color: #333;
+    }
+    
+    #product {
+      background: white;
+      border-radius: 8px;
+      padding: 20px;
+      box-shadow: 0 2px 8px rgba(0,0,0,0.1);
+    }
+  </style>
+</head>
+<body>
+  <header>
+    <div class="container">
+      <h1>🥃 Premium Spirits Collection</h1>
+    </div>
+  </header>
+  
+  <div class="container">
+    <div id="product"></div>
+  </div>
+</body>
+</html>
+```
+
+Replace `YOUR_API_KEY` with your actual key and you're ready to go!

package/docs/v1/guides/accessibility.md

@@ -0,0 +1,288 @@
+# Accessibility Guide
+
+What the Elements SDK does for accessibility, what it needs from your page, and how to verify it.
+
+## Overview
+
+Elements target **WCAG 2.1 Level AA**. Every element ships with keyboard support, screen-reader
+announcements and managed focus — there is nothing to switch on. Colour contrast is the exception:
+the SDK renders your theme's colours exactly as given, so that part is yours — see
+[Colour and contrast](#colour-and-contrast).
+
+Accessibility is shared between the SDK and the host page:
+
+| The SDK owns | Your page owns |
+|---|---|
+| Roles, names and states of everything inside an element | Page structure: landmarks, `<html lang>` |
+| Keyboard operation of every control it renders | Contrast of your own content, and the surface you place elements on |
+| Focus movement into and out of its overlays | A theme whose colours meet the WCAG contrast minimums (the SDK renders your colours as given) |
+| Announcing its own content changes | Not hiding or `inert`-ing the element container |
+| Reflow down to a 320px viewport | Layout around the element at 400% zoom |
+
+## Keyboard navigation
+
+Every control is reachable and operable with a keyboard alone. Related controls are grouped into
+a **single tab stop** with arrow keys inside it, so a long list of retailers or sizes is not a
+tab-through slog.
+
+| Widget | Keys |
+|---|---|
+| Size selector (product) | `Tab` to the group, `←` `→` to move, `Enter` / `Space` to choose, `Home` / `End` for the ends |
+| Size dropdown (product list) | `Enter` / `Space` / `↓` opens, `↑` `↓` moves, `Enter` chooses, `Esc` closes |
+| Delivery method tabs (Shipping / Same-Day) | `←` `→` switches method immediately; unavailable methods are skipped, `Home` / `End` for the ends |
+| Retailer / delivery-option lists | `↑` `↓` moves, `Enter` / `Space` chooses, `Home` / `End` for the ends |
+| Retailer carousel | `←` `→` moves, `Enter` / `Space` chooses |
+| Product image thumbnails | `←` `→` moves, `Enter` / `Space` shows the image |
+| Tip amount | `Tab` to the group, `←` `→` to move, `Enter` / `Space` to choose, `Home` / `End` for the ends |
+| Quantity steppers | `Tab` to each button, `Enter` / `Space` to step |
+| Address field | Type to search, `↑` `↓` through suggestions, `Enter` selects, `Esc` dismisses |
+| Cart / checkout drawer, modals | `Tab` cycles inside the panel only, `Esc` closes |
+
+Arrow keys change the selection immediately only where that is cheap and reversible (the delivery
+method tabs). Where choosing has a side effect the user cannot navigate back out of — picking a
+retailer closes the panel — arrow keys move focus and `Enter` commits.
+
+### Focus management
+
+- **Opening an overlay** moves focus onto the first control inside it — the panel's close
+  button, the address field — and remembers the control that opened it. Focus lands on a
+  control rather than on the panel itself so the focus ring shows a sighted keyboard user
+  where they now are; the dialog's role and name are announced either way as focus crosses
+  into it. Views whose point is the text at the top of them (the order confirmation) focus
+  that heading instead.
+- **Closing** returns focus to that control, even when a re-render has replaced it.
+- **While an overlay is open** focus is trapped inside it and the rest of the page is `inert` and
+  `aria-hidden`, so a screen reader cannot wander behind the dialog.
+- **In-place content swaps** (Buy Now → address form, Add to Cart → personalize) re-seat focus on
+  the new view's heading; nothing is left focused on a destroyed node.
+- **After a re-render** focus returns to the control that caused it — the quantity stepper you
+  pressed, the delivery-method tab you switched to.
+- **Nothing hidden is focusable.** Collapsed panels are removed from the tab order and the
+  accessibility tree, and closed overlays have their content torn down.
+
+### Retailer shopping from the cart
+
+The opt-in `cart.layout.showShopRetailerButton` uses a native **Shop {retailer}** button with
+normal Tab, Enter and Space behavior, a 44px minimum target height and a visible focus ring.
+It appears beside the unmet-minimum warning on desktop and below it on mobile. Warning updates
+retain the button node and its focus; if it disappears because the minimum is met or eligibility
+changes, focus moves to the containing fulfillment before its item controls. The host handles
+focus after closing the drawer and navigating in response to `cart_shop_retailer`.
+
+The button text, border and focus ring use `global.theme.primaryColor`; check that color against
+the cart background as part of your theme contrast review.
+
+### Focus indicator
+
+A 2px ring in `--focus-ring-color`, offset 2px from the control. Controls that span their
+container's full width use an inset ring instead, because an outward ring on those is clipped by
+the scrolling panel around them. On primary-coloured fills the ring switches to
+`--selected-text-color`, the token already used for text on that fill — so setting the pair
+`primaryColor` / `selectedTextColor` to a combination that clears 3:1 covers the ring too.
+
+The ring targets `:focus` as well as `:focus-visible`, so browsers without `:focus-visible`
+support still show it.
+
+## Screen reader support
+
+Elements are Web Components inside a shadow root, which is fully visible to assistive technology.
+
+### Announcements
+
+Content that appears or changes without navigation is announced through a shared live region
+(`role="status"`, `aria-live="polite"`; `role="alert"` for errors) that lives at the end of
+`document.body` and survives re-renders.
+
+| What happened | What is announced |
+|---|---|
+| Buy Now pressed | "Enter delivery address" |
+| Address saved | "Delivery address updated. Now delivering to …" |
+| Delivery option chosen | "Delivery option updated. Shipping from …, $…, Ships in 2-3 days, delivery $…" |
+| Delivery method switched | "Shipping selected. 5 options available. Shipping from …, $…, Ships in 2-3 days, delivery $…" |
+| Size chosen | "Size 750 ML selected" |
+| Quantity stepped | "Tito's Handmade Vodka, quantity 4" |
+| Personalization saved / removed | "Personalization saved" / "Personalization removed" |
+| Cart or checkout opened / closed | "Shopping cart opened" / "Shopping cart closed" |
+| Panel closed (product) | "Closed. Back to product options." |
+| Item added / removed, promo applied, totals changed | The new state, e.g. "Promo code SPRING applied, $5.00 off" |
+| Express checkout payment failed | "Express checkout failed. …" |
+| Product list filtered or searched | "12 products found, showing 12" |
+| Validation failed | The field name and the error, interrupting (assertive) |
+| Carousel image changed | "Image 2 of 4" |
+
+Live regions are never written into a component template: components replace their whole subtree
+on render, and a live region recreated with its text already in place is not announced. Use
+`this.announcer.announce(message)` from a component instead.
+
+### Names, roles and states
+
+- Dialogs carry `role="dialog"`, an accessible name, and `aria-modal` when they cover the page.
+- Single-select groups are `listbox` / `radiogroup` with `option` / `radio` children carrying
+  `aria-selected` / `aria-checked` — not toggle buttons with `aria-pressed`, which would describe
+  each choice as an independent on/off switch. Product sizes are a `listbox`; the delivery options
+  under each method are a `radiogroup`.
+- Checkout's **Delivery Method** section is an accordion whose header is a real `button` carrying
+  `aria-expanded`, and whose two methods are a `radiogroup` of `radio` cards. Choosing one re-prices
+  the order, so selection does not follow focus here either: arrow keys move between the methods and
+  `Enter` / `Space` commits, rather than committing a switch the shopper was only passing through.
+  A method that cannot fulfil is `aria-disabled` and not activatable, but the **Change Location**
+  button inside it stays reachable — it is the way out of that state, so it must not be sealed in
+  with the option it sits under. Each card names the method, its fee and its timing, or, when it
+  cannot fulfil, the reason why.
+- The delivery-method controls are a `tablist` of `tab`s. Only one method's options are rendered at
+  a time, so the selected tab carries `aria-controls` and the region it swaps in is the matching
+  `tabpanel`, labelled by that tab; the inactive tab points at nothing, because there is nothing
+  there to point at. A method switched off by configuration renders no tab at all, and the region
+  then falls back to its own label rather than naming a tab that does not exist. Choosing an option
+  closes the panel, so arrow keys move without choosing and `Enter` / `Space` commits — a
+  deliberate departure from the radio-group model, which would otherwise select a neighbour and
+  end the interaction before the shopper reached the option they wanted.
+- Unavailable controls are `aria-disabled` **and** genuinely inert: they cannot be activated.
+- Icon-only buttons take their name from the button's `aria-label`.
+- Visible label text is always contained in the accessible name (2.5.3 Label in Name), so speech
+  input works: saying "click See Delivery Options" activates the button that reads that way.
+- Fields whose design has no room for a visible label (promo code, gift card) get an
+  `aria-label` instead — no rendered label, no layout change. A field that has a visible `<label>`
+  is never *also* given an `aria-label`, which would replace the label's text rather than add to
+  it.
+- **Required fields** carry `aria-required="true"`, so they announce as required. The visible `*`
+  is reinforcement and is `aria-hidden`, since the state is already spoken; each form section
+  explains the glyph with a "Fields marked * are required." line above its fields (3.3.2).
+- An option in a single-select group carries its **whole** visible content in its accessible name.
+  `option` and `radio` have presentational children, so the name is the only channel: a delivery
+  option names the retailer, the price, the timing, the delivery fee and — for same-day — the
+  store address and whether it is currently closed.
+- The California Proposition 65 warning on the product is a native `<details>` / `<summary>`
+  disclosure: the summary is a button that exposes its expanded state, and `Enter` / `Space` toggle
+  it with no scripting involved. Its `+` / `−` indicator is decorative and hidden. In checkout it is
+  a plain link whose accessible name ends "(opens in a new tab)", since following it leaves the
+  purchase mid-flow; the `·` separator is hidden.
+
+### Headings
+
+The product element emits a level-1 title, and every section caption below it sits at level 2 —
+`Size`, `Delivers to:`, `Shipping From:` and `About this product:` — so the whole element is
+reachable by heading navigation with no level skipped. An overlay supplies its own heading at the
+top of its content, because the page behind it is out of the accessibility tree while it is open.
+
+A caption can do both jobs at once: `Shipping From:` is a heading *and* names the retailer card
+beneath it through `aria-labelledby`. Heading ids are scoped to the product, so each product
+element on a page labels its own sections.
+
+The checkout element has its own outline and is not covered by the above. Where any element's
+top-level heading sits in **your** page's outline is yours to place.
+
+### Express checkout
+
+The Apple Pay and Google Pay buttons are rendered by Stripe inside an iframe, so their own labels
+and keyboard behaviour are Stripe's. What the SDK owns around them:
+
+- The **"Express Checkout" heading** is an `h3`, matching the other checkout section headings. It is
+  rendered only by the `section` variant; injected on their own the buttons carry no heading, and the
+  host page's own outline supplies it.
+- The **`OR` divider** is decorative and carries `aria-hidden="true"`, so "OR" is not announced as
+  content between the buttons and the section below.
+- When the shopper's device offers **no wallet**, the heading and the divider are removed from the
+  accessibility tree along with the buttons, so no orphan rule or empty heading is left behind. The block is also removed on a gift order, which express cannot place, and where a
+  payment method is already bound to the checkout. It is offered to every shopper otherwise.
+- The **wallet sheet is browser UI**, not an SDK overlay: the browser owns focus while it is open and
+  returns it to the button that opened it. Dismissing the sheet changes nothing in the page, so
+  nothing is announced.
+- Failures are announced assertively, because the shopper has just authorised a payment and the sheet
+  that showed the error has already closed. Confirming the sheet places the order outright, so there
+  is nothing to announce on the success path beyond the order confirmation itself.
+
+### Images and icons
+
+- Product photos use the product name as their alt text; a photo painted as a CSS background is
+  exposed with `role="img"` and the same name.
+- Decorative images inside a named control use `alt=""` so the control is not announced twice.
+- Every inline SVG icon renders `aria-hidden="true" focusable="false"`. Icons that carry meaning
+  on their own opt in to a name: `CloseIcon({ label: 'Close' })`.
+
+## Colour and contrast
+
+Element colours come from your theme, and a brand palette chosen to look right often does not
+clear WCAG: white on a mid-tone brand fill is around 3:1, well under the 4.5:1 body text needs.
+
+**The SDK renders the colours you supply exactly as given — it does not adjust them.** Contrast is
+therefore yours to get right: check each foreground token against the surface the Element sits on
+and make sure it reaches 4.5:1 for text (WCAG 1.4.3) and 3:1 for borders, icons and the focus ring
+(WCAG 1.4.11).
+
+The tokens worth checking are `defaultTextColor`, `linkTextColor`, `warningColor`, `errorColor` and
+`successColor` against `drawerBackgroundColor` (or whatever your page puts behind the Element), plus
+`selectedTextColor` against `primaryColor` for text on brand-filled buttons and badges.
+
+`defaultTextColor` also colours the product's California Proposition 65 warning, which is legally
+required copy, so it always uses the full-strength token, never a lighter variant — make sure it
+reaches 4.5:1 on your product background. The checkout's warning panel does not use it: it is a
+fixed colour pair chosen by `global.layout.poweredByMode` (over 13:1 in both `light` and `dark`), so
+set that to `dark` if your checkout is dark.
+
+Every token ships with a default that already passes on a light surface. Two are easy to forget
+because they are optional — leave them out to keep the compliant defaults, or set them explicitly to
+keep those details on-brand:
+
+```javascript
+customTheme: {
+  global: {
+    theme: {
+      inputBorderColor: '#767C85', // form field boundaries, needs 3:1 on your surface
+      focusRingColor: '#1D4ED8'    // keyboard focus ring, needs 3:1 on your surface
+    }
+  }
+}
+```
+
+### Zoom, reflow and text spacing
+
+Elements reflow down to a 320px CSS viewport (400% zoom on a 1280px screen) without horizontal
+scrolling. Labels wrap instead of truncating, so they survive user text-spacing overrides.
+
+## Verifying it
+
+**Keyboard:** unplug the mouse and complete a purchase. Every control must be reachable, every
+focus ring visible, and focus must never land on `<body>`.
+
+**Announcements** without a screen reader — the live regions are plain DOM:
+
+```javascript
+for (const region of document.querySelectorAll('[data-lce-live-region]')) {
+  new MutationObserver(() => console.log('[SR]', region.textContent)).observe(region, {
+    childList: true, subtree: true, characterData: true,
+  });
+}
+```
+
+**Screen readers:** verify with VoiceOver (Safari/macOS), NVDA (Firefox/Windows) or TalkBack
+(Chrome/Android) — the pairings that matter most for a storefront.
+
+## See Also
+
+- [Theming Guide](./theming.md) — the colour tokens to check for contrast
+- [Best Practices](./best-practices.md)
+- [Browser Support](../reference/browser-support.md)
+
+## Checkout initialization and payment recovery
+
+Checkout announces loading or initialization failure in a status region. If initialization fails, payment fields are withheld and a keyboard-operable **Retry checkout** button retries the same checkout. The button is disabled while loading.
+
+Save Payment Information remains disabled until checkout initializes. During payment save it stays busy until the server responds. Recoverable billing/prepare errors are announced while the mounted card fields and billing input remain available for correction and retry.
+
+### Wallet payment actions
+
+The payment action's accessible name matches its visible label, including the
+selected Apple Pay or Google Pay wallet and retry/processing states. Adjacent
+instructions explain whether the action opens the wallet or retries saving already
+authorized details. These actions save the payment method; order placement is a
+separate step.
+
+### Recorded marketing choices
+
+Checkout suppresses each email/SMS consent checkbox only after the corresponding
+recorded account choice is confirmed. Suppressed controls are hidden visually and
+from the accessibility tree; unknown choices retain their named, keyboard-operable
+checkboxes. Clearing account preferences reveals the controls and synchronizes
+`aria-checked` with the current guest defaults. A shopper's explicit checkbox edit
+keeps that channel visible when account data arrives later.