diff --git a/platforms/web/README.md b/platforms/web/README.md
index a2d42523..02db5a85 100644
--- a/platforms/web/README.md
+++ b/platforms/web/README.md
@@ -1,57 +1,278 @@
-# @shopify/checkout-kit
+# Shopify Checkout Kit - Web
 
-A web component for embedding Shopify checkout in any website.
+[![GitHub license](https://img.shields.io/badge/license-MIT-lightgrey.svg?style=flat)](https://github.com/Shopify/checkout-kit/blob/main/LICENSE) [![npm latest](https://img.shields.io/npm/v/@shopify/checkout-kit/latest.svg?label=npm)](https://www.npmjs.com/package/@shopify/checkout-kit)
 
-[![npm latest](https://img.shields.io/npm/v/@shopify/checkout-kit/latest.svg?label=npm)](https://www.npmjs.com/package/@shopify/checkout-kit)
+<img width="3200" height="800" alt="gradients" src="https://github.com/user-attachments/assets/72813286-1bec-493b-b08a-6cc4ba23dbda" />
 
-## Install
+**Shopify Checkout Kit** is a web component library that enables any website to
+present the world's highest converting, customizable, one-page checkout. The
+presented experience is a fully-featured checkout that preserves all of the
+store customizations: Checkout UI extensions, Functions, branding, and more. It
+also provides web idiomatic defaults such as opening checkout in a popup or
+new tab, a transient overlay scrim while the popup is open, and convenient
+developer APIs to embed, customize, and follow the lifecycle of the checkout
+experience via the
+[Embedded Checkout Protocol](https://ucp.dev/2026-04-08/specification/embedded-checkout/).
 
-```bash
-npm i @shopify/checkout-kit
+Check out our blog to
+[learn how and why we built the Shopify Checkout Kit](https://www.shopify.com/partners/blog/mobile-checkout-sdks-for-ios-and-android).
+
+- [Platform Requirements](#platform-requirements)
+- [Getting Started](#getting-started)
+  - [Installation](#installation)
+- [Basic Usage](#basic-usage)
+- [Programmatic Usage](#programmatic-usage)
+- [Usage with the Shopify Storefront API](#usage-with-the-shopify-storefront-api)
+- [Configuration](#configuration)
+  - [`src`](#src)
+  - [`target`](#target)
+  - [`debug`](#debug)
+  - [Popup dimensions](#popup-dimensions)
+  - [Overlay scrim](#overlay-scrim)
+- [Explore the sample app](#explore-the-sample-app)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Platform Requirements
+
+- **Browsers** — evergreen Chromium, Firefox, and WebKit (Safari 16.4+). The
+  component relies on `<dialog>`, native `customElements`, and `AbortController`
+  — all stable in every supported browser.
+- **TypeScript** (optional) — `5.0+` for consumers using the bundled type
+  definitions.
+- **Bundler** (optional) — works with Vite, Rollup, esbuild, webpack, or
+  no bundler at all via `<script type="module">`.
+
+## Getting Started
+
+Shopify Checkout Kit for the web is an open-source npm package.
+
+Use the following steps to get started with adding it to your web application:
+
+### Installation
+
+```sh
+pnpm add @shopify/checkout-kit
+
+# or using yarn
+yarn add @shopify/checkout-kit
+
+# or using npm
+npm install @shopify/checkout-kit
 ```
 
-## Layout
+## Basic Usage
+
+Import the package once anywhere in your application. The import has a side
+effect — it registers `<shopify-checkout>` with `customElements`:
 
+```ts
+import '@shopify/checkout-kit';
 ```
-platforms/web/
-├── src/                    # source — add web component code here
-│   └── index.ts            # public API
-├── package.json            # the published @shopify/checkout-kit
-├── vite.config.ts          # build (lib mode + dts) + vitest config
-├── tsconfig.json
-├── custom-elements-manifest.config.mjs
-└── .oxlintrc.json
+
+Then render the element anywhere in your HTML and call `open()` to present
+checkout:
+
+```html
+<shopify-checkout
+  id="checkout"
+  src="https://your-store.myshopify.com/checkouts/cn/abc123"
+  target="popup"
+></shopify-checkout>
+
+<button id="buy-now">Buy now</button>
+
+<script type="module">
+  import '@shopify/checkout-kit';
+
+  const checkout = document.getElementById('checkout');
+  document.getElementById('buy-now').addEventListener('click', () => {
+    checkout.open();
+  });
+</script>
 ```
 
-## Development
+The element has no visible layout of its own beyond a transient `<dialog>`
+scrim that appears over the host page while the popup is open. It can sit
+anywhere in your DOM.
 
-```bash
-cd platforms/web
-pnpm install
+See [usage with the Storefront API](#usage-with-the-shopify-storefront-api)
+below for details on how to obtain a checkout URL.
 
-pnpm build              # vite + custom-elements-manifest
-pnpm dev                # vite build --watch
-pnpm test               # vitest with coverage
-pnpm test:watch
-pnpm lint               # typecheck + oxlint + oxfmt --check
-pnpm format             # oxfmt (writes in place)
-pnpm verify             # publint
+## Programmatic Usage
 
-pnpm sample             # serve the playground at http://localhost:5173
-pnpm sample:build       # build the playground (sample/dist/)
+If you'd rather not declare the element in HTML, create one from JavaScript:
+
+```ts
+import '@shopify/checkout-kit';
+import type {ShopifyCheckout} from '@shopify/checkout-kit';
+
+const checkout = document.createElement('shopify-checkout') as ShopifyCheckout;
+checkout.src = 'https://your-store.myshopify.com/checkouts/cn/abc123';
+checkout.target = 'popup';
+document.body.append(checkout);
+
+checkout.addEventListener('ec:complete', () => {
+  console.log('Order complete', checkout.checkout);
+});
+
+checkout.open();
+// Later:
+checkout.close();
+```
+
+The `ShopifyCheckout` class is also exported directly if you want to import
+the constructor without registering the element globally:
+
+```ts
+import {ShopifyCheckout} from '@shopify/checkout-kit';
+
+if (!customElements.get('shopify-checkout')) {
+  customElements.define('shopify-checkout', ShopifyCheckout);
+}
 ```
 
-## Tooling
+## Usage with the Shopify Storefront API
+
+To present checkout you first need a checkout URL. The most common way is to
+use the [Storefront GraphQL API](https://shopify.dev/docs/api/storefront) to
+assemble a cart (via `cartCreate` and related mutations) and read the
+[`checkoutUrl`](https://shopify.dev/docs/api/storefront/2024-10/objects/Cart#field-cart-checkouturl)
+field. Alternatively, a
+[cart permalink](https://help.shopify.com/en/manual/products/details/cart-permalink)
+can be provided.
+
+```ts
+const response = await fetch(
+  'https://your-store.myshopify.com/api/2024-10/graphql.json',
+  {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'X-Shopify-Storefront-Access-Token': '<storefront access token>',
+    },
+    body: JSON.stringify({
+      query: /* GraphQL */ `
+        query CheckoutUrl($id: ID!) {
+          cart(id: $id) {
+            checkoutUrl
+          }
+        }
+      `,
+      variables: {id: 'gid://shopify/Cart/...'},
+    }),
+  },
+);
+
+const {data} = await response.json();
+checkout.src = data.cart.checkoutUrl;
+```
+
+> [!IMPORTANT]
+> `src` must be an `https:` URL. The component drops invalid or non-HTTPS
+> values and refuses to open. When `debug` is enabled, a warning is logged
+> to the console.
+
+## Configuration
+
+The presented checkout is customized via attributes on the
+`<shopify-checkout>` element (or the equivalent properties on the
+`ShopifyCheckout` instance — both are reflected).
+
+### `src`
+
+The URL of the checkout to load. Typically `cart.checkoutUrl` from the
+Storefront API.
+
+```html
+<shopify-checkout src="https://your-store.myshopify.com/checkouts/cn/abc123" />
+```
+
+```ts
+checkout.src = 'https://your-store.myshopify.com/checkouts/cn/abc123';
+```
+
+The component appends a handful of query parameters to `src` when it opens
+checkout: `ec_version` (Embedded Checkout Protocol version),
+`ec_delegate` (which capabilities the host delegates), and `ck_version`
+(the Checkout Kit version).
+
+### `target`
+
+Where the checkout is presented. Defaults to `"auto"`.
+
+| Value      | Behavior                                                            |
+| ---------- | ------------------------------------------------------------------- |
+| `"auto"`   | Opens checkout in a new browser tab (default).                      |
+| `"popup"`  | Opens checkout in a popup window sized and centered over the page.  |
+| `"_blank"` | Synonym for `"auto"` — new tab.                                     |
+| _(string)_ | Any other value is treated as a named window target, the same as the [`target` parameter of `window.open()`](https://developer.mozilla.org/en-US/docs/Web/API/Window/open#target). |
+
+```html
+<shopify-checkout target="popup" />
+```
+
+> [!NOTE]
+> `"_self"`, `"_parent"`, and `"_top"` are not allowed — they would navigate
+> the host page away. The component falls back to `"auto"` if you set one,
+> and logs a warning when `debug` is enabled.
+
+### `debug`
+
+Enables console diagnostics during integration. Useful while wiring up `src`
+and event handlers; turn it off in production.
+
+```html
+<shopify-checkout src="..." debug />
+```
+
+### Popup dimensions
+
+When `target="popup"`, the popup is centered over the host window. Defaults
+are `600 × 600`, capped at 90% of the host window. Override via CSS custom
+properties:
+
+```css
+shopify-checkout {
+  --shopify-checkout-dialog-width: 720;
+  --shopify-checkout-dialog-height: 800;
+}
+```
+
+### Overlay scrim
+
+While a popup is open the component renders a `<dialog>` scrim over the host
+page, with a "Continue your purchase in the checkout window" link and a close
+button. Hide it by either:
+
+- Setting `display: none` on the element itself, or
+- Targeting the `overlay` shadow part:
+
+```css
+shopify-checkout::part(overlay) {
+  display: none;
+}
+```
+
+## Explore the sample app
+
+See the [`sample/`](./sample) directory for a small Vite playground that mounts
+the real `<shopify-checkout>` element next to a faux storefront. Run it from
+this directory with:
+
+```sh
+pnpm install
+pnpm sample
+```
+
+Then open the dev server URL and paste a valid checkout URL into the `src`
+field to try `open()` / `close()` / `focus()` and see the live event stream.
+
+## Contributing
 
-| Concern         | Tool                                         |
-| --------------- | -------------------------------------------- |
-| Bundler         | Vite (lib mode) + `vite-plugin-dts`          |
-| Tests           | Vitest + happy-dom                           |
-| Lint            | oxlint                                       |
-| Format          | oxfmt                                        |
-| Element docs    | `@custom-elements-manifest/analyzer` → `dist/custom-elements.json` |
-| Publish hygiene | `publint`                                    |
+We welcome code contributions, feature requests, and reporting of issues.
+Please see [guidelines and instructions](../../.github/CONTRIBUTING.md).
 
 ## License
 
-[MIT](./LICENSE)
+Shopify's Checkout Kit is provided under an [MIT License](LICENSE).