Update EW introduction content (#2790)

bgravenorst · yashovardhan · alexandratran · web-flow · commit 917d22c11e85 · 2026-04-09T14:19:15.000+10:00
* Add svg.

Signed-off-by: bgravenorst &lt;byron.gravenorst@consensys.net&gt;

* Update EW introduction content.

Signed-off-by: bgravenorst &lt;byron.gravenorst@consensys.net&gt;

* Add rebrand admonition.

Signed-off-by: bgravenorst &lt;byron.gravenorst@consensys.net&gt;

* Remove MPC.

Signed-off-by: bgravenorst &lt;byron.gravenorst@consensys.net&gt;

* Add svg.

Signed-off-by: bgravenorst &lt;byron.gravenorst@consensys.net&gt;

* Update EW introduction content.

Signed-off-by: bgravenorst &lt;byron.gravenorst@consensys.net&gt;

* Add rebrand admonition.

Signed-off-by: bgravenorst &lt;byron.gravenorst@consensys.net&gt;

* Remove MPC.

Signed-off-by: bgravenorst &lt;byron.gravenorst@consensys.net&gt;

* Apply suggestions from code review

Co-authored-by: Alexandra Carrillo &lt;12214231+alexandratran@users.noreply.github.com&gt;

* Address feedback.

Signed-off-by: bgravenorst &lt;byron.gravenorst@consensys.net&gt;

---------

Signed-off-by: bgravenorst &lt;byron.gravenorst@consensys.net&gt;
Co-authored-by: Yashovardhan Agrawal &lt;yashovardhan.agrawal@gmail.com&gt;
Co-authored-by: Alexandra Carrillo &lt;12214231+alexandratran@users.noreply.github.com&gt;
diff --git a/.cursor/rules/editorial-voice.mdc b/.cursor/rules/editorial-voice.mdc
@@ -34,6 +34,14 @@ The rules below are the most actionable subset for AI-assisted editing.
   Windows").
 - Do not start sentences with "So," "Basically," or "Actually."
 
+## Lists
+
+- Include at least two items but, if possible, no more than seven.
+- Keep items short enough that the reader can see two or three at a glance. A couple of short
+  paragraphs per item is acceptable, but don't exceed that length often.
+- Make all items consistent in structure (for example, each item is a noun or a phrase that starts
+  with a verb).
+
 ## Punctuation and formatting
 
 - Do not use em dashes or en dashes. Use commas, parentheses, semicolons, or rephrase the sentence.
diff --git a/embedded-wallets/README.mdx b/embedded-wallets/README.mdx
@@ -6,9 +6,6 @@ description: 'What are MetaMask Embedded Wallets? Pluggable wallet infrastructur
 ---
 
 import Head from '@docusaurus/Head'
-import BrowserOnly from '@docusaurus/BrowserOnly'
-import PnPCoreKitFlowLight from '@site/static/img/embedded-wallets/flow-diagrams/pnp-core-kit-flow-light.png'
-import PnPCoreKitFlowDark from '@site/static/img/embedded-wallets/flow-diagrams/pnp-core-kit-flow-dark.png'
 
 <Head>
   <meta
@@ -32,85 +29,73 @@ import PnPCoreKitFlowDark from '@site/static/img/embedded-wallets/flow-diagrams/
   <meta name="author" content="MetaMask" />
 </Head>
 
-MetaMask Embedded Wallets (formerly Web3Auth) provides a pluggable embedded wallet infrastructure to simplify Web3 wallet integration and user onboarding. It supports OAuth-based logins and multiple platforms, allowing users to access Web3 applications through familiar authentication methods in under a minute.
+MetaMask Embedded Wallets (formerly Web3Auth) provides a pluggable embedded wallet infrastructure to
+simplify Web3 wallet integration and user onboarding. It supports OAuth-based logins and multiple
+platforms, allowing your users to access Web3 applications through familiar authentication methods.
 
-Users enjoy seamless onboarding while maintaining full control of their non-custodial wallets, ensuring both convenience and security.
+MetaMask Embedded Wallets reduces traditional wallet management overhead by removing the need
+to manage private keys and seed phrases directly.
 
-## Key features
+<p style={{ margin: '1.25rem 0' }}>
+  <img
+    src="/img/embedded-wallets/wallet-user-flow-comparison.svg"
+    alt="End-user steps: traditional standalone wallet versus Embedded Wallets"
+    style={{
+      display: 'block',
+      width: '100%',
+      maxWidth: 794,
+      height: 'auto',
+      marginLeft: 'auto',
+      marginRight: 'auto',
+    }}
+  />
+</p>
 
-<BrowserOnly>
-  {() => {
-    const ModalAnim = require('@site/src/components/ModalAnim').default
-    return <ModalAnim />
-  }}
-</BrowserOnly>
+Users get a smoother onboarding experience while retaining control of non-custodial wallets.
+
+## Key features
 
-### 🔐 Authentication made simple
+### Authentication
 
-Get your users started in seconds with familiar login methods they already use:
+Help users get started quickly with sign-in methods they already use:
 
-- Sign in with Google, Twitter, GitHub and other popular social accounts
-- Passwordless login via email, SMS and authenticator apps.
-- Bring your own auth system while leveraging our secure wallet infrastructure
+- Sign in with Google, Twitter, GitHub, and other popular social accounts.
+- Sign in with email, SMS, and authenticator apps without passwords.
+- Bring your own auth system while using MetaMask Embedded Wallets infrastructure.
 
-### 🛡️ Bank-grade security
+### Security
 
 Enterprise-level protection for your users' digital assets:
 
-- Advanced MPC technology splits keys across multiple parties
-- Users maintain 100% control of their non-custodial wallets
-- Distributed architecture prevents single points of failure
-- Multiple backup options for worry-free recovery
+- Users maintain 100% control of their non-custodial wallets.
+- A distributed architecture prevents single points of failure.
+- Multiple recovery options support account recovery flows.
 
-### 💻 Built for developers
+### Developer experience
 
-Integrate MetaMask Embedded Wallets into your app with minimal effort:
+Integrate MetaMask Embedded Wallets into your app with minimal setup:
 
-- Drop-in solution works with your existing auth system
-- No complex migrations or infrastructure changes needed
-- Full control to customize the look and feel
-- Support for web, mobile, and gaming platforms
+- Use a drop-in solution that works with your existing auth system.
+- Avoid complex migrations or infrastructure changes.
+- Customize the look and feel.
+- Integrate on web, mobile, and gaming platforms.
 
-### 👥 Designed for users
+### User experience
 
-The smoothest path to Web3 for your users:
+Provide a low-friction path to Web3:
 
-- Get started in under 60 seconds
-- No crypto knowledge needed
-- Users own and control their wallets
-- Simple, reliable account recovery
+- Help users get started quickly.
+- Avoid requiring users to understand blockchain concepts up front.
+- Let users own and control their wallets.
+- Support account recovery flows.
 
-MetaMask Embedded Wallets (formerly Web3Auth) operate as wallet infrastructure, providing enhanced flexibility and security for decentralized applications (dapps) and blockchain wallets. Throughout this documentation, we'll explore the functionality of MetaMask Embedded Wallets, showcasing how it produces unique cryptographic key providers for each user and application.
+MetaMask Embedded Wallets provides wallet infrastructure for dapps and blockchain wallets. This
+documentation explains how it works, including how it generates cryptographic key providers for
+each user and application.
 
 ## How do Embedded Wallets work?
 
-### High-level architecture
-
-The Embedded Wallet SDKs live solely on the user/application's frontend client and handle the interactions between OAuth providers and the Embedded Wallet network.
-
-The diagram below describes the relationship between the SDKs and integrating applications. It also depicts the difference between the products that power the infrastructure for a developer-friendly integration.
-
-<picture>
-  <source srcset={PnPCoreKitFlowLight} media="(prefers-color-scheme: light)" />
-  <source srcset={PnPCoreKitFlowDark} media="(prefers-color-scheme: dark)" />
-  <img
-    src={PnPCoreKitFlowLight}
-    style={{ display: 'block', maxHeight: '600px', margin: '20px auto' }}
-    alt="This diagram describes the relationship between the Embedded Wallet SDK and integrating application"
-  />
-</picture>
-
-### Wallet management infrastructure
-
-The [wallet management infrastructure](./infrastructure/README.mdx) enhances security by distributing a user's wallet across various key shares, thereby avoiding direct exposure of seed phrases. These key shares form a 'web of trust' and enable wallet management akin to multi-factor account handling. Users employ OAuth logins, trusted devices, and other factors to manage their cryptographic key pairs. Importantly, the complete private keys are not stored anywhere within the wallet infrastructure system, including our databases or any participating nodes.
-
-To create a social login share, users interact with the Embedded Wallets network, where key generation operates via a 5/9 consensus system. This setup guarantees that wallets remain non-custodial, ensuring that neither MetaMask, social login providers, nor any other party holding a key share can claim full ownership.
-
-:::tip managing wallets
-
-For managing wallets, our infrastructure uses various cryptographic techniques such as [Shamir's Secret Sharing](./infrastructure/sss-architecture.mdx), threshold cryptography, and [Multi Party Computation (MPC)](./infrastructure/mpc-architecture.mdx). To learn more about how we manage wallets, please refer to our [Wallet Management and Security of our Infrastructure](./infrastructure/README.mdx).
-
-:::
+See **[Architecture](./architecture.mdx)** for the high-level system design, SDK and integration diagram, and wallet management infrastructure.
 
 ## Is MetaMask Embedded Wallets a wallet?
 
@@ -124,15 +109,8 @@ The MetaMask Embedded Wallets infrastructure is built to handle millions of user
 
 - Global availability across multiple regions with consistent low-latency performance worldwide
 - Automatic horizontal scaling that adjusts capacity based on demand, eliminating bottlenecks and ensuring uninterrupted service
-- Enhanced security and reliability through distributed MPC architecture, maintaining a track record of zero downtime over three years of operation
 - Enterprise-grade infrastructure running on Kubernetes orchestration for maximum reliability and performance
 
-:::note[Rebrand]
-
-The SDKs are now branded as MetaMask Embedded Wallet SDKs (formerly Web3Auth Plug and Play SDKs). Package names and APIs remain Web3Auth (for example, Web3Auth React SDK), and code snippets may reference `web3auth` identifiers.
-
-:::
-
 :::tip[Start]
 
 [Get started with Embedded Wallets](./get-started.mdx).
diff --git a/embedded-wallets/architecture.mdx b/embedded-wallets/architecture.mdx
@@ -0,0 +1,62 @@
+---
+title: Architecture
+sidebar_label: Architecture
+description: "How MetaMask Embedded Wallets fit together: SDK layout, integrations, and wallet management infrastructure."
+---
+
+import PnPCoreKitFlowLight from '@site/static/img/embedded-wallets/flow-diagrams/pnp-core-kit-flow-light.png'
+import PnPCoreKitFlowDark from '@site/static/img/embedded-wallets/flow-diagrams/pnp-core-kit-flow-dark.png'
+
+MetaMask Embedded Wallets includes front-end SDKs that run in your app and coordinate OAuth sign-in
+with the Embedded Wallets network. You use these SDKs to authenticate a user, retrieve the key
+material required for that user, and create a client that can sign requests on the user's behalf.
+
+:::note[Rebrand]
+
+The SDKs are now branded as MetaMask Embedded Wallet SDKs (formerly Web3Auth Plug and Play SDKs).
+Package names and APIs remain Web3Auth (for example, Web3Auth React SDK), and code snippets may reference `web3auth` identifiers.
+
+:::
+
+At a high level, the flow includes:
+
+1. **Your app**: Starts OAuth sign-in with the selected login provider.
+1. **Login providers**: Authenticates the user and returns an ID token.
+1. **Embedded Wallet SDK**: Submits the ID token for validation and requests the user's OAuth key share.
+1. **Core kit (tKey)**: Combines key shares to recreate the user's signing key.
+1. **Embedded Wallets network**: Validates tokens and returns the required key share.
+1. **Your app**: uses the SDK-provided client to create a wallet provider and sign requests on the
+    user's behalf.
+
+The following diagram summarizes the login flow and shows how the SDK components interact with the
+integrating app and the Embedded Wallets network.
+
+<picture>
+  <source srcset={PnPCoreKitFlowLight} media="(prefers-color-scheme: light)" />
+  <source srcset={PnPCoreKitFlowDark} media="(prefers-color-scheme: dark)" />
+  <img
+    src={PnPCoreKitFlowLight}
+    style={{ display: 'block', maxHeight: '600px', margin: '20px auto' }}
+    alt="This diagram describes the relationship between the Embedded Wallet SDK and integrating application"
+  />
+</picture>
+
+### Wallet management infrastructure
+
+The [wallet management infrastructure](./infrastructure/README.mdx) improves security by splitting a
+user's wallet into multiple key shares, which avoids direct exposure of seed phrases. Users combine
+OAuth sign-in, trusted devices, and other recovery factors to access and manage their cryptographic
+keys. The infrastructure is designed so that no single party holds the full private key.
+
+To create an OAuth login share, users interact with the Embedded Wallets network. Key generation
+uses a threshold process that requires multiple participants to contribute shares. This helps keep
+wallets non-custodial, because no single party (including MetaMask or the login provider) can use a
+single share to control the wallet.
+
+:::tip managing wallets
+
+The infrastructure uses [Shamir's Secret Sharing](./infrastructure/sss-architecture.mdx) to split and
+recover wallet keys.
+For more details, see [Wallet management infrastructure](./infrastructure/README.mdx).
+
+:::
diff --git a/ew-sidebar.js b/ew-sidebar.js
@@ -128,6 +128,7 @@ const sidebar = {
   overview: [
     { type: "doc", id: "README", label: "About" },
     { type: "doc", id: "get-started", label: "Get Started" },
+    { type: "doc", id: "architecture", label: "Architecture" },
     "build-with-ai",
     {
       type: "category",
diff --git a/static/img/embedded-wallets/wallet-user-flow-comparison.svg b/static/img/embedded-wallets/wallet-user-flow-comparison.svg
@@ -0,0 +1,133 @@
+<!--
+  scale(0.85) about frame center (476,264); viewBox fits transformed artwork (~15% smaller, no empty margin).
+  Dark: @media (prefers-color-scheme: dark) — transparent frame (page shows through), white text.
+  As <img>, this tracks OS/browser dark mode, not the Docusaurus navbar theme if they differ.
+-->
+<svg
+  xmlns="http://www.w3.org/2000/svg"
+  viewBox="79 47 794 434"
+  color-scheme="light dark"
+  role="img"
+  aria-labelledby="wf-title wf-desc"
+>
+  <title id="wf-title">Traditional standalone wallet versus Embedded Wallets end-user steps</title>
+  <desc id="wf-desc">
+    Six numbered steps for a traditional standalone wallet compared to three steps for Embedded Wallets,
+    with a vertical divider between the columns.
+  </desc>
+  <defs>
+    <style>
+      .wf-title {
+        font-family: Geist, Arial, 'Helvetica Neue', Helvetica, sans-serif;
+        font-size: 20px;
+        font-weight: 600;
+        fill: #121314;
+      }
+      .wf-body {
+        font-family: Geist, Arial, 'Helvetica Neue', Helvetica, sans-serif;
+        font-size: 19px;
+        font-weight: 400;
+        fill: #121314;
+      }
+      .wf-num {
+        font-family: Geist, Arial, 'Helvetica Neue', Helvetica, sans-serif;
+        font-size: 18px;
+        font-weight: 600;
+        fill: #3d065f;
+      }
+
+      .wf-frame {
+        fill: #f7f9fc;
+        stroke: #d075ff;
+        stroke-width: 2;
+      }
+
+      .wf-rule {
+        stroke: #d075ff;
+        stroke-width: 2;
+      }
+
+      .wf-step-circle {
+        fill: #eac2ff;
+        stroke: #d075ff;
+        stroke-width: 2;
+      }
+
+      @media (prefers-color-scheme: dark) {
+        .wf-frame {
+          fill: none;
+          stroke: #d075ff;
+        }
+
+        .wf-title,
+        .wf-body {
+          fill: #ffffff;
+        }
+
+        .wf-num {
+          fill: #ffffff;
+        }
+
+        .wf-rule {
+          stroke: #d075ff;
+        }
+
+        .wf-step-circle {
+          fill: #3d065f;
+          stroke: #eac2ff;
+        }
+      }
+    </style>
+  </defs>
+  <g transform="translate(476,264) scale(0.85) translate(-476,-264)">
+  <rect class="wf-frame" x="16" y="16" width="920" height="496" rx="14" ry="14" />
+  <g transform="translate(24,20)">
+    <!-- Inner coords: frame world y 16–512 → iy = wy − 20 -->
+    <line class="wf-rule" x1="460" y1="-4" x2="460" y2="492" />
+    <!-- Column headings -->
+    <text class="wf-title" x="28" y="40">Traditional standalone wallet</text>
+    <text class="wf-title" x="482" y="40">Embedded Wallets</text>
+    <!-- Spines (between circle edges) -->
+    <line class="wf-rule" x1="42" y1="112" x2="42" y2="415" />
+    <line class="wf-rule" x1="496" y1="112" x2="496" y2="214" />
+    <!-- Standalone steps -->
+    <circle cx="42" cy="96" r="16" class="wf-step-circle" />
+    <text class="wf-num" x="42" y="96" text-anchor="middle" dominant-baseline="central">1</text>
+    <text class="wf-body">
+      <tspan x="80" y="90">Download and install the wallet</tspan>
+      <tspan x="80" y="114">extension or mobile app.</tspan>
+    </text>
+    <circle cx="42" cy="163" r="16" class="wf-step-circle" />
+    <text class="wf-num" x="42" y="163" text-anchor="middle" dominant-baseline="central">2</text>
+    <text class="wf-body" x="80" y="163" dominant-baseline="central">Create a new wallet</text>
+    <circle cx="42" cy="230" r="16" class="wf-step-circle" />
+    <text class="wf-num" x="42" y="230" text-anchor="middle" dominant-baseline="central">3</text>
+    <text class="wf-body" x="80" y="230" dominant-baseline="central">Store the 12-24 word seed phrase</text>
+    <circle cx="42" cy="297" r="16" class="wf-step-circle" />
+    <text class="wf-num" x="42" y="297" text-anchor="middle" dominant-baseline="central">4</text>
+    <text class="wf-body" x="80" y="297" dominant-baseline="central">Connect the dapp and the wallet</text>
+    <circle cx="42" cy="364" r="16" class="wf-step-circle" />
+    <text class="wf-num" x="42" y="364" text-anchor="middle" dominant-baseline="central">5</text>
+    <text class="wf-body">
+      <tspan x="80" y="357">Sign the wallet request to approve</tspan>
+      <tspan x="80" y="381">the connection</tspan>
+    </text>
+    <circle cx="42" cy="431" r="16" class="wf-step-circle" />
+    <text class="wf-num" x="42" y="431" text-anchor="middle" dominant-baseline="central">6</text>
+    <text class="wf-body" x="80" y="431" dominant-baseline="central">Ready to receive wallet requests</text>
+    <!-- Embedded steps -->
+    <circle cx="496" cy="96" r="16" class="wf-step-circle" />
+    <text class="wf-num" x="496" y="96" text-anchor="middle" dominant-baseline="central">1</text>
+    <text class="wf-body">
+      <tspan x="536" y="90">Sign in using the preferred provider</tspan>
+      <tspan x="536" y="114">(Google, Facebook, etc.)</tspan>
+    </text>
+    <circle cx="496" cy="163" r="16" class="wf-step-circle" />
+    <text class="wf-num" x="496" y="163" text-anchor="middle" dominant-baseline="central">2</text>
+    <text class="wf-body" x="536" y="163" dominant-baseline="central">Approve the sign-in request</text>
+    <circle cx="496" cy="230" r="16" class="wf-step-circle" />
+    <text class="wf-num" x="496" y="230" text-anchor="middle" dominant-baseline="central">3</text>
+    <text class="wf-body" x="536" y="230" dominant-baseline="central">Ready to receive wallet requests</text>
+  </g>
+  </g>
+</svg>

Original file line number	Diff line number	Diff line change
`@@ -128,6 +128,7 @@ const sidebar = {`
`128`	`128`	`overview: [`
`129`	`129`	`{ type: "doc", id: "README", label: "About" },`
`130`	`130`	`{ type: "doc", id: "get-started", label: "Get Started" },`
	`131`	`+ { type: "doc", id: "architecture", label: "Architecture" },`
`131`	`132`	`"build-with-ai",`
`132`	`133`	`{`
`133`	`134`	`type: "category",`