Add Snaps best practices section

docusaurus.config.js

@@ -300,12 +300,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/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
+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,16 +1,16 @@
 ---
 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.
@@ -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.
@@ -148,13 +148,13 @@ The following are guidelines for validating RPC parameters and handling values:
   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.