Merge pull request #429 from kinde-oss/feat/custom-ui-pages

Update understand-page-design.mdx

Author: clairekinde11

src/content/docs/design/customize-with-code/understand-page-design.mdx

@@ -144,7 +144,7 @@ If you are using React for templating, note this code is rendered on the server.
 
 </Aside>
 
-### Page structure in the Git directory
+## Page structure in the Git directory
 
 The code for your pages must live in a GitHub repository (other git providers to be supported later). Your directory structure in the repo is critical to Kinde being able to run your design code.
 
@@ -162,7 +162,7 @@ myApp/
   └── kinde.json
 ```
 
-### Kinde.json
+## Kinde.json
 
 The `kinde.json` file defines the config for all custom code in Kinde, including workflows and custom pages. A typical config file will look as follows:
 
@@ -177,25 +177,93 @@ The `kinde.json` file defines the config for all custom code in Kinde, including
 
 `version` - based on the date when the API version was released. Any breaking changes will be released in a new API version.
 
-### Which pages can I customize?
+## Which pages can I customize?
 
 All Kinde hosted pages can be customized and use url route mapping to determine which template to use.
 
 If a specific mapped route does not exist, a special route called `(default)` will be rendered. Set up the `(default)` page to ensure all your pages follow this design unless you have overridden them with custom code.  
 
-Available routes:
+<Aside type="warning">
 
-`(default)` - The page template that will be used for all Kinde hosted pages when a specific one cannot be found.
+Once you start customizing pages, it's on you not to break them. We recommend always applying custom code to pages in a non-prod environment first.
 
-`(register)` - The sign up page
+</Aside>
+
+### Common pages
+
+These are the most frequently used or fallback pages.
+
+* `(default)` – Fallback template used when a specific page is not found.
+* `(register)` – The sign-up page.
+* `(login)` – The sign-in page.
+* `(index)` – Landing page when visiting the root domain (e.g. `https://<yourdomain>.kinde.com`).
+
+### Authentication
+
+Pages involved in initiating authentication flows.
+* `(register)` – The sign-up page.
+* `(login)` – The sign-in page.
+* `(sso_home_realm)` – Displayed when a user selects “Continue with SSO” to choose their identity provider.
+* `(provide_email)` – Shown when using a social login provider that does not return an email address.
+* `(clickwrap)` – Displays terms and conditions or agreements that must be accepted.
+
+### Password flows
+
+Used in password-based authentication and recovery.
+
+* `(verify_password)` – Shown during sign-in when using a password-based method.
+* `(set_password)` – Shown during a password-based sign-up flow.
+* `(reset_password_verify_email_otp)` – First step of the reset flow where the user verifies identity using an email OTP.
+* `(reset_password)` – Password entry screen shown after verification during the reset flow.
+
+### One-Time Passcode (OTP) verification
+
+Used in sign-in and sign-up flows with OTP (email or phone).
+
+* `(sign_in_use_email_otp)` – Sign in with a one-time email code.
+* `(sign_up_use_email_otp)` – Sign up with a one-time email code.
+* `(sign_in_sign_up_use_phone_otp)` – Sign in or sign up with a one-time phone code.
+
+### Multi-Factor Authentication (MFA)
+
+Shown after primary authentication when MFA is required or being set up.
+
+* `(mfa_method_selection)` – User selects their preferred MFA method.
+* `(mfa_authenticator_app)` – Setup screen for using an authenticator app.
+* `(mfa_setup_email)` – Setup screen for email-based MFA.
+* `(mfa_setup_phone)` – Setup screen for phone-based MFA.
+* `(mfa_use_email_otp)` – Enter a one-time email code for MFA.
+* `(mfa_use_phone_otp)` – Enter a one-time phone code for MFA.
+* `(mfa_use_recovery_code)` – Enter a recovery code if unable to use other MFA methods.
+* `(mfa_view_recovery_codes)` – View and save MFA recovery codes.
+
+### Billing (coming soon)
+
+Pages related to choosing a plan and making a payment.
+
+* `(choose_plan)` – User selects a subscription plan.
+* `(collect_payment_details)` – User enters billing information.
+* `(subscription_success)` – Confirmation page shown after successful subscription.
+
+### Early access
+
+Pages for gated access to your product before full launch.
+
+* `(request_access)` – Request early access to your product.
+* `(request_access_success)` – Confirmation page after a request is submitted.
+
+### Error pages
 
-`(login)` - The sign in page
+Shown when a user encounters an error state.
 
-`(index)` - If someone visits the root domain for your business, e.g. `https://<yourdomain>.kinde.com`
+* `(account_locked)` – The user’s account has been locked.
+* `(account_not_found)` – No account was found for the entered credentials.
+* `(invalid_redirect_url)` – The redirect URL is invalid or not on the allowed list.
+* `(error)` – Generic error screen.
 
 If you want specific customization for a page not listed here, reach out and let us know.
 
-### Set the page default export function
+## Set the page default export function
 
 Your `page.[ext]` file should contain a default export. It doesn’t matter what this is called, but the general convention is to call it `Page`. This is provided a single `event` argument which is an object containing 2 keys `context` and `request`.
 
@@ -225,7 +293,7 @@ The top level `context` key object contains information about the page itself, l
         - `description` the page description
         - `logoAlt` the alt text for your company logo
 
-### Page settings
+## Page settings
 
 Sometimes additional information needs to be passed to Kinde from your page. You can use the page settings object for this.