Add Snaps best practices section (#1187)

* Add Snaps best practices section

* fix links

* update design guidelines description

* minor fixes

* move dev-ex in codeowners

.github/CODEOWNERS

@@ -1,3 +1,3 @@
-* @MetaMask/dev-ex @MetaMask/tech-writers
+* @MetaMask/tech-writers
 /snaps/ @MetaMask/tech-writers @MetaMask/snaps
-/wallet/ @MetaMask/tech-writers
+/wallet/ @MetaMask/tech-writers @MetaMask/dev-ex

docusaurus.config.js

@@ -311,12 +311,12 @@ const config = {
             to: "/snaps/features/custom-evm-accounts/create-account-snap",
           },
           {
-            from: "/snaps/concepts/design-guidelines",
-            to: "/snaps/how-to/design-a-snap",
+            from: ["/snaps/concepts/design-guidelines", "/snaps/how-to/design-a-snap"],
+            to: "/snaps/learn/best-practices/design-guidelines",
           },
           {
-            from: "/snaps/concepts/security-guidelines",
-            to: "/snaps/how-to/secure-a-snap",
+            from: ["/snaps/concepts/security-guidelines", "/snaps/how-to/secure-a-snap"],
+            to: "/snaps/learn/best-practices/security-guidelines",
           },
           {
             from: "/guide/snaps-permissions",

snaps/how-to/communicate-errors.md

@@ -1,5 +1,5 @@
 ---
-description: Communicate errors from your Snap without crashing it
+description: Communicate errors from your Snap without crashing it.
 sidebar_position: 2
 ---
 

snaps/how-to/connect-to-a-snap.md

@@ -1,6 +1,6 @@
 ---
 description: Connect your dapp to existing, third-party Snaps.
-sidebar_position: 9
+sidebar_position: 7
 ---
 
 # Connect to a Snap

snaps/how-to/debug-a-snap/index.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 7
+sidebar_position: 5
 ---
 
 # Debug a Snap

snaps/how-to/publish-a-snap.md

@@ -1,6 +1,6 @@
 ---
 description: Develop, test, and publish a Snap.
-sidebar_position: 8
+sidebar_position: 6
 ---
 
 # Publish a Snap

snaps/how-to/test-a-snap.md

@@ -1,6 +1,6 @@
 ---
 description: Use Jest for end-to-end Snap testing.
-sidebar_position: 6
+sidebar_position: 4
 ---
 
 # Test a Snap

snaps/learn/best-practices/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Best practices",
+  "position": 3,
+  "link": {
+    "type": "generated-index",
+    "slug": "learn/best-practices"
+  }
+}

snaps/how-to/design-a-snap.md → snaps/learn/best-practices/design-guidelines.md

@@ -1,10 +1,10 @@
 ---
-description: Create accessible Snap installation flows.
-sidebar_position: 4
+description: Learn about best practices for designing accessible Snap installation flows.
+sidebar_position: 1
 toc_max_heading_level: 2
 ---
 
-# Design a Snap installation flow
+# Snaps design guidelines
 
 This page outlines guiding principles for designers, developers, builders, and writers to create
 Snap installation flows that are accessible to all users.
@@ -67,7 +67,7 @@ Consider introducing your Snap in your companion dapp using a modal, tooltip, or
 This introduction should be impactful, clear, and direct, and can happen before or alongside the
 installation prompt.
 
-![Introducing your Snap's features via a modal](../assets/install-modal.png)
+![Introducing your Snap's features via a modal](../../assets/install-modal.png)
 
 Important details to include when introducing your Snap:
 
@@ -95,7 +95,7 @@ Instead, **wait to prompt installation until a point when the Snap is required**
 
 In the following example, a key management Snap is suggested when the user is prompted to pick networks:
 
-![Installation and connection to your Snap embedded in existing flows](../assets/picker.png)
+![Installation and connection to your Snap embedded in existing flows](../../assets/picker.png)
 
 ## Optimize your metadata
 
@@ -142,9 +142,9 @@ For example:
 The following images demonstrate how your Snap's avatar and name are displayed during installation,
 transaction insights, and custom dialogs:
 
-![How your Snap's avatar and name are displayed during installation](../assets/install.png)
-![How your Snap's name is displayed during transaction insights](../assets/insights.png)
-![How your Snap's avatar and name are displayed during a custom dialog screen](../assets/dialog.png)
+![How your Snap's avatar and name are displayed during installation](../../assets/install.png)
+![How your Snap's name is displayed during transaction insights](../../assets/insights.png)
+![How your Snap's avatar and name are displayed during a custom dialog screen](../../assets/dialog.png)
 
 ## Enhance your copy
 

snaps/how-to/secure-a-snap.md → snaps/learn/best-practices/security-guidelines.md

@@ -1,29 +1,29 @@
 ---
 description: Learn about best practices for creating secure and reliable Snaps.
-sidebar_position: 5
+sidebar_position: 2
 ---
 
-# Secure a Snap
+# Snaps security guidelines
 
 This page outlines essential principles for builders to develop secure and reliable Snaps.
 Use these guidelines when creating your Snap to ensure it is safe for users.
 
 ## Manage permissions
 
-The following are guidelines for [managing permissions](request-permissions.md) in the Snap manifest file.
+The following are guidelines for [managing permissions](../../how-to/request-permissions.md) in the Snap manifest file.
 
 - **Minimum permissions** - Follow the principle of least authority by only adding the minimum
   permissions needed by your Snap in the manifest file.
   Before publishing your Snap, check the permissions again and remove any unused permissions.
   You can validate your permissions using the [Snaps Simulator Manifest
   Validator](https://metamask.github.io/snaps/snaps-simulator/staging/#/manifest).
 
-- **Minimum RPC access** - When adding the [`endowment:rpc`](../reference/permissions.md/#endowmentrpc)
+- **Minimum RPC access** - When adding the [`endowment:rpc`](../../reference/permissions.md#endowmentrpc)
   permission for Snaps or dapps, ask yourself if both are necessary.
   For example, if permission is granted to communicate with Snaps, it means other Snaps can call
   your Snap's sensitive RPC methods.
 
-- **Minimum network access** - Only add the [`endowment:network-access`](../reference/permissions.md/#endowmentnetwork-access)
+- **Minimum network access** - Only add the [`endowment:network-access`](../../reference/permissions.md#endowmentnetwork-access)
   permission if it's absolutely necessary, such as when needing to communicate with a remote API
   that is part of your Snap's functionality.
   This to mitigate users' concern about sharing wallet usage to remote servers.
@@ -66,7 +66,7 @@ The following are guidelines for user notifications and authorizations:
   use a companion dapp as an "admin interface" to interact with your Snap's sensitive methods.
   There are two ways to do this:
 
-  1. Restrict the [`endowment:rpc`](../reference/permissions.md#endowmentrpc) permission to specific
+  1. Restrict the [`endowment:rpc`](../../reference/permissions.md#endowmentrpc) permission to specific
      URLs using the `allowedOrigins` caveat.
 
   2. Filter specific methods to specific URLs using the built-in [URL
@@ -109,7 +109,7 @@ user IPs, emails, passwords, and private keys:
 
 - **Private keys** - Avoid retrieving the user's private key from the Snap unless
   absolutely necessary, such as to sign a transaction.
-  If you only need the user's public key, use [`snap_getBip32PublicKey`](../reference/snaps-api.md#snap_getbip32publickey)
+  If you only need the user's public key, use [`snap_getBip32PublicKey`](../../reference/snaps-api.md#snap_getbip32publickey)
   instead of deriving it from the private key.
   Never return the private key in an RPC method to a dapp or another Snap.
   To give users a way to view their private key, display it in a dialog.
@@ -142,19 +142,19 @@ The following are guidelines for validating RPC parameters and handling values:
   confirmation flow.
 
 - **Use `copyable` for safe disclosures** - When displaying arbitrary content in a Snap dialog, such
-  as for signing a message, use the [`copyable`](../features/custom-ui.md/#copyable) user
+  as for signing a message, use the [`copyable`](../../features/custom-ui.md#copyable) user
   interface component instead of `text`.
   When using dialogs, the input may contain special characters that render as Markdown and can
   mislead the user.
   For example: 
 
-  ![Example not using copyable with Markdown rendering](../assets/copyable-example-1.png)
+  ![Example not using copyable with Markdown rendering](../../assets/copyable-example-1.png)
 
   The special characters `*` and `_` render Markdown formatting, so what the user sees does not
   match the content.
   To avoid this, use `copyable` instead:
 
-  ![Example using copyable with clean rendering](../assets/copyable-example-2.png)
+  ![Example using copyable with clean rendering](../../assets/copyable-example-2.png)
 
   `copyable` does not render Markdown and has the added benefit that the user can select to copy the content.
   Also, the formatting provides a visual delineator to separate arbitrary input or fields from user
@@ -177,7 +177,7 @@ Avoid using the following deprecated methods:
 - `wallet_enable`, which is deprecated in favor of
   [`wallet_requestSnaps`](/wallet/reference/wallet_requestsnaps).
 
-- `snap_confirm`, which is deprecated in favor of [`snap_dialog`](../reference/snaps-api.md#snap_dialog).
+- `snap_confirm`, which is deprecated in favor of [`snap_dialog`](../../reference/snaps-api.md#snap_dialog).
 
 - `endowment:long-running`, which is deprecated for MetaMask stable but still allowed in MetaMask Flask.
 
@@ -187,7 +187,7 @@ The following are coding security tips and warnings:
 
 - **SES compatibility** - Use packages or libraries compatible with SES (hardened JavaScript).
   If you don't, you might encounter errors that require [patching a specific
-  dependency](debug-a-snap/common-issues.md/#patch-dependencies) to fix.
+  dependency](../../how-to/debug-a-snap/common-issues.md#patch-dependencies) to fix.
 
 - **Timers and side-channel attacks** - Certain JavaScript features such as timers (for example,
   `Date.now`) can expose critical system information, making a user vulnerable to
@@ -200,7 +200,7 @@ The following are coding security tips and warnings:
   Do not use insufficient hashing algorithms such as `md5` or `sha2`.
   Do not roll your own cryptography or use custom or unproven cryptography methods or libraries.
 
-  We recommend using [`snap_getEntropy`](../reference/snaps-api.md/#snap_getentropy) for entropy, the
+  We recommend using [`snap_getEntropy`](../../reference/snaps-api.md#snap_getentropy) for entropy, the
   built-in [Web Crypto API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API) or
   [Noble cryptography libraries](https://paulmillr.com/noble/), and safe hashing algorithms such as `sha256`.
   Choose audited, widely used libraries over obscure, untested implementations.

src/components/SnapsSection.tsx

@@ -12,7 +12,7 @@ const CardList: CardItem[] = [
   },
   {
     title: "⚙️ Snaps tutorials",
-    link: "/snaps/tutorials",
+    link: "/snaps/learn/tutorials",
     description: (<>
       Follow the step-by-step tutorials to create Snaps that estimate gas fees, provide
       transaction insights with custom UI, and more.