Custom flows audit (#1544)

Co-authored-by: victoria <[email protected]>

docs/custom-flows/add-email.mdx

@@ -3,8 +3,8 @@ title: Build a custom flow for adding an email to a user's account
 description: Learn how to use Clerk's API to build a custom flow for adding an email to a user's account.
 ---
 
-> [!CAUTION]
-> This guide is for users who want to build a _custom_ user interface using the Clerk API. To use a _prebuilt_ UI, you should use Clerk's [Account Portal pages](/docs/customization/account-portal/overview) or [prebuilt components](/docs/components/overview).
+> [!WARNING]
+> This guide is for users who want to build a _custom_ user interface using the Clerk API. To use a _prebuilt_ UI, use Clerk's [Account Portal pages](/docs/customization/account-portal/overview) or [prebuilt components](/docs/components/overview).
 
 Users are able to add multiple email addresses to their account.
 
@@ -13,16 +13,13 @@ Every user has a [`User`](/docs/references/javascript/user/user) object that rep
 The following example demonstrates how to build a custom user interface that allows users to add an email address to their account. The example:
 
 1. Uses the [`useUser()`](/docs/references/react/use-user) hook to get the `User` object.
-1. Uses the [`User.createEmailAddress()`](/docs/references/javascript/user/create-metadata#create-email-address) method to add the email address to the user's account.
-
-- A new [`EmailAddress`](/docs/references/javascript/email-address) object is created and stored in `User.emailAddresses`.
-
+1. Uses the [`User.createEmailAddress()`](/docs/references/javascript/user/create-metadata#create-email-address) method to add the email address to the user's account. A new [`EmailAddress`](/docs/references/javascript/email-address) object is created and stored in `User.emailAddresses`.
 1. Uses the `prepareVerification()` method on the newly created `EmailAddress` object to send a verification code to the user.
 1. Uses the `attemptVerification()` method on the same `EmailAddress` object with the verification code provided by the user to verify the email address.
 
 <Tabs items={["Next.js", "iOS (Beta)"]}>
  <Tab>
- ```tsx {{ filename: 'app/account/add-email/page.tsx' }}
+ ```tsx {{ filename: 'app/account/add-email/page.tsx', collapsible: true }}
  'use client'
 
  import * as React from 'react'
@@ -153,7 +150,7 @@ The following example demonstrates how to build a custom user interface that all
  </Tab>
 
  <Tab>
- ```swift {{ filename: 'AddEmailView.swift' }}
+ ```swift {{ filename: 'AddEmailView.swift', collapsible: true }}
  import SwiftUI
  import ClerkSDK
 

docs/custom-flows/add-phone.mdx

@@ -3,8 +3,8 @@ title: Build a custom flow for adding a phone number to a user's account
 description: Learn how to use Clerk's API to build a custom flow for adding a phone number to a user's account.
 ---
 
-> [!CAUTION]
-> This guide is for users who want to build a _custom_ user interface using the Clerk API. To use a _prebuilt_ UI, you should use Clerk's [Account Portal pages](/docs/customization/account-portal/overview) or [prebuilt components](/docs/components/overview).
+> [!WARNING]
+> This guide is for users who want to build a _custom_ user interface using the Clerk API. To use a _prebuilt_ UI, use Clerk's [Account Portal pages](/docs/customization/account-portal/overview) or [prebuilt components](/docs/components/overview).
 
 Users are able to add multiple phone numbers to their account.
 
@@ -13,16 +13,13 @@ Every user has a [`User`](/docs/references/javascript/user/user) object that rep
 The following example demonstrates how to build a custom user interface that allows users to add a phone number to their account. The example:
 
 1. Uses the [`useUser()`](/docs/references/react/use-user) hook to get the `User` object.
-1. Uses the [`User.createPhoneNumber()`](/docs/references/javascript/user/create-metadata#create-phone-number) method to add the phone number to the user's account.
-
-- A new [`PhoneNumber`](/docs/references/javascript/phone-number) object is created and stored in `User.phoneNumbers`.
-
+1. Uses the [`User.createPhoneNumber()`](/docs/references/javascript/user/create-metadata#create-phone-number) method to add the phone number to the user's account. A new [`PhoneNumber`](/docs/references/javascript/phone-number) object is created and stored in `User.phoneNumbers`.
 1. Uses the `prepareVerification()` method on the newly created `PhoneNumber` object to send a verification code to the user.
 1. Uses the `attemptVerification()` method on the same `PhoneNumber` object with the verification code provided by the user to verify the phone number.
 
 <Tabs items={["Next.js", "iOS (Beta)"]}>
  <Tab>
- ```tsx {{ filename: 'app/account/add-phone/page.tsx' }}
+ ```tsx {{ filename: 'app/account/add-phone/page.tsx', collapsible: true }}
  'use client'
 
  import * as React from 'react'
@@ -152,7 +149,7 @@ The following example demonstrates how to build a custom user interface that all
  </Tab>
 
  <Tab>
- ```swift {{ filename: 'AddPhoneView.swift' }}
+ ```swift {{ filename: 'AddPhoneView.swift', collapsible: true }}
  import SwiftUI
  import ClerkSDK
 

docs/custom-flows/bot-sign-up-protection.mdx

@@ -4,15 +4,15 @@ description: Learn how to add Clerk's bot protection to your custom sign-up flow
 ---
 
 > [!WARNING]
-> This guide is for users who want to build a _custom_ user interface using the Clerk API. To implement Clerk's [Bot Protection](/docs/security/bot-protection) feature for your sign-ups using a _prebuilt_ UI, you should use Clerk's [`<SignUp />` component](/docs/components/authentication/sign-up).
+> This guide is for users who want to build a _custom_ user interface using the Clerk API. To use a _prebuilt_ UI, use Clerk's [Account Portal pages](/docs/customization/account-portal/overview) or [prebuilt components](/docs/components/overview).
 
-Clerk provides the ability to add a CAPTCHA widget to your sign-up flows to protect against bot sign-ups. This guide will show you how to add the CAPTCHA widget to your custom sign-up flow.
+Clerk provides the ability to add a CAPTCHA widget to your sign-up flows to protect against bot sign-ups. Clerk's [`<SignUp />`](/docs/components/authentication/sign-up) component handles this flow out-of-the-box. However, if you're building a custom user interface, this guide will show you how to add the CAPTCHA widget to your custom sign-up flow.
 
 <Steps>
  ### Enable bot sign-up protection
 
  1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/attack-protection).
- 1. Go to **User & Authentication > Attack Protection** in the sidebar menu.
+ 1. In the navigation sidebar, select **User & Authentication > Attack Protection**.
  1. In the **Bot sign-up protection** section, enable the feature and choose the **CAPTCHA type** you want to use.
 
  ### Add the CAPTCHA widget to your custom sign-up form
@@ -28,7 +28,7 @@ Clerk provides the ability to add a CAPTCHA widget to your sign-up flows to prot
  <Tab>
  The following example demonstrates how to add the CAPTCHA widget to a custom sign-up form. This example uses the [Email & password custom flow](/docs/custom-flows/email-password) but you can add the CAPTCHA widget to _any_ custom sign-up form.
 
- ```tsx {{ filename: 'app/sign-up/[[...sign-up]]/page.tsx', mark: [112, 113] }}
+ ```tsx {{ filename: 'app/sign-up/[[...sign-up]]/page.tsx', mark: [112, 113], collapsible: true }}
  'use client'
 
  import * as React from 'react'