From 3faf9a319aa93a58b433ee77c1ac3d5f73e6a0ca Mon Sep 17 00:00:00 2001 From: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com> Date: Wed, 15 Jan 2025 13:33:56 -0500 Subject: [PATCH] Update styleguides (#1773) Co-authored-by: victoria --- .../social-connections/linkedin.mdx | 2 +- .../social-connections/twitter.mdx | 2 +- .../redirect-to-createorganization.mdx | 2 +- .../redirect-to-organizationprofile.mdx | 2 +- .../control/redirect-to-userprofile.mdx | 2 +- docs/custom-flows/add-email.mdx | 2 +- docs/custom-flows/add-phone.mdx | 2 +- docs/custom-flows/email-password-mfa.mdx | 2 +- docs/custom-flows/email-password.mdx | 4 +- docs/custom-flows/email-sms-otp.mdx | 4 +- docs/custom-flows/forgot-password.mdx | 2 +- .../multi-session-applications.mdx | 8 +- docs/custom-flows/oauth-connections.mdx | 4 +- docs/custom-flows/sign-out.mdx | 2 +- docs/customization/elements/overview.mdx | 2 +- docs/deployments/deploy-chrome-extension.mdx | 4 +- docs/index.mdx | 6 +- docs/manifest.json | 6 +- docs/quickstarts/ios.mdx | 2 +- docs/quickstarts/overview.mdx | 4 +- docs/quickstarts/react-router.mdx | 2 +- docs/quickstarts/tanstack-start.mdx | 2 +- docs/references/ios/overview.mdx | 2 +- docs/references/overview.mdx | 2 +- docs/users/deleting-users.mdx | 2 +- styleguides/SSO.STYLEGUIDE.MD | 154 +----- styleguides/STYLEGUIDE.md | 470 +++++++----------- 27 files changed, 229 insertions(+), 469 deletions(-) diff --git a/docs/authentication/social-connections/linkedin.mdx b/docs/authentication/social-connections/linkedin.mdx index 41645cba86..e0ba1967f9 100644 --- a/docs/authentication/social-connections/linkedin.mdx +++ b/docs/authentication/social-connections/linkedin.mdx @@ -1,5 +1,5 @@ --- -title: LinkedIn (Deprecated) +title: LinkedIn (deprecated) description: Learn how to set up social connection with LinkedIn. --- diff --git a/docs/authentication/social-connections/twitter.mdx b/docs/authentication/social-connections/twitter.mdx index 4ef9177dfe..d147c694e9 100644 --- a/docs/authentication/social-connections/twitter.mdx +++ b/docs/authentication/social-connections/twitter.mdx @@ -1,5 +1,5 @@ --- -title: Twitter v1 (Deprecated) +title: Twitter v1 (deprecated) description: Learn how to set up social connection with Twitter v1. --- diff --git a/docs/components/control/redirect-to-createorganization.mdx b/docs/components/control/redirect-to-createorganization.mdx index 2f67555cfb..e3487d9089 100644 --- a/docs/components/control/redirect-to-createorganization.mdx +++ b/docs/components/control/redirect-to-createorganization.mdx @@ -1,5 +1,5 @@ --- -title: '`` (Deprecated)' +title: '`` (deprecated)' description: The component will navigate to the user profile URL which has been configured in your application instance. The behavior will be just like a server-side (3xx) redirect, and will override the current location in the history stack. --- diff --git a/docs/components/control/redirect-to-organizationprofile.mdx b/docs/components/control/redirect-to-organizationprofile.mdx index 800023b7d0..484e28c2d2 100644 --- a/docs/components/control/redirect-to-organizationprofile.mdx +++ b/docs/components/control/redirect-to-organizationprofile.mdx @@ -1,5 +1,5 @@ --- -title: '`` (Deprecated)' +title: '`` (deprecated)' description: The component will navigate to the organization profile URL which has been configured in your application instance. The behavior will be just like a server-side (3xx) redirect, and will override the current location in the history stack. --- diff --git a/docs/components/control/redirect-to-userprofile.mdx b/docs/components/control/redirect-to-userprofile.mdx index 953ec78ca8..fb35884440 100644 --- a/docs/components/control/redirect-to-userprofile.mdx +++ b/docs/components/control/redirect-to-userprofile.mdx @@ -1,5 +1,5 @@ --- -title: '`` (Deprecated)' +title: '``' (deprecated) description: The component will navigate to the user profile URL which has been configured in your application instance. The behavior will be just like a server-side (3xx) redirect, and will override the current location in the history stack. --- diff --git a/docs/custom-flows/add-email.mdx b/docs/custom-flows/add-email.mdx index e1b3db453d..c0006b4546 100644 --- a/docs/custom-flows/add-email.mdx +++ b/docs/custom-flows/add-email.mdx @@ -16,7 +16,7 @@ The following example demonstrates how to build a custom user interface that all 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. - + ```tsx {{ filename: 'app/account/add-email/page.tsx', collapsible: true }} 'use client' diff --git a/docs/custom-flows/add-phone.mdx b/docs/custom-flows/add-phone.mdx index 81ff9ffc38..615eca6dc5 100644 --- a/docs/custom-flows/add-phone.mdx +++ b/docs/custom-flows/add-phone.mdx @@ -16,7 +16,7 @@ The following example demonstrates how to build a custom user interface that all 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. - + ```tsx {{ filename: 'app/account/add-phone/page.tsx', collapsible: true }} 'use client' diff --git a/docs/custom-flows/email-password-mfa.mdx b/docs/custom-flows/email-password-mfa.mdx index 2296237854..f9b0dc782c 100644 --- a/docs/custom-flows/email-password-mfa.mdx +++ b/docs/custom-flows/email-password-mfa.mdx @@ -44,7 +44,7 @@ This guide will walk you through how to build a custom email/password sign-in fl > [!TIP] > For this example to work, the user must have MFA enabled on their account. You need to add the ability for your users to manage their MFA settings. See the [manage SMS-based MFA](/docs/custom-flows/manage-sms-based-mfa) or the [manage TOTP-based MFA](/docs/custom-flows/manage-totp-based-mfa) guide, depending on your needs. - + ```tsx {{ filename: 'app/sign-in/[[...sign-in]]/page.tsx', collapsible: true }} 'use client' diff --git a/docs/custom-flows/email-password.mdx b/docs/custom-flows/email-password.mdx index d22ac988ff..9165dd3e8e 100644 --- a/docs/custom-flows/email-password.mdx +++ b/docs/custom-flows/email-password.mdx @@ -30,7 +30,7 @@ This guide will walk you through how to build a custom email/password sign-up an 1. Collect the one-time code and attempt to complete the email address verification with it. 1. If the email address verification is successful, set the newly created session as the active session. - + This example is written for Next.js App Router but it can be adapted for any React meta framework, such as Remix. @@ -474,7 +474,7 @@ This guide will walk you through how to build a custom email/password sign-up an 1. Initiate the sign-in process by creating a `SignIn` using the email address and password provided. 1. If the attempt is successful, set the newly created session as the active session. - + This example is written for Next.js App Router but it can be adapted for any React meta framework, such as Remix. diff --git a/docs/custom-flows/email-sms-otp.mdx b/docs/custom-flows/email-sms-otp.mdx index 9eaec44650..c877593d4f 100644 --- a/docs/custom-flows/email-sms-otp.mdx +++ b/docs/custom-flows/email-sms-otp.mdx @@ -27,7 +27,7 @@ This guide will walk you through how to build a custom SMS OTP sign-up and sign- 1. Attempt to complete the verification with the code the user provides. 1. If the verification is successful, set the newly created session as the active session. - + This example is written for Next.js App Router but can be adapted to any React meta framework, such as Remix. @@ -313,7 +313,7 @@ This guide will walk you through how to build a custom SMS OTP sign-up and sign- 1. Attempt verification with the code the user provides. 1. If the attempt is successful, set the newly created session as the active session. - + This example is written for Next.js App Router but can be adapted to any React meta framework, such as Remix. diff --git a/docs/custom-flows/forgot-password.mdx b/docs/custom-flows/forgot-password.mdx index 3795f0b3cc..aeb6376aec 100644 --- a/docs/custom-flows/forgot-password.mdx +++ b/docs/custom-flows/forgot-password.mdx @@ -16,7 +16,7 @@ For the sake of this guide, this example is written for Next.js App Router but i {/* TODO: Add JavaScript example. */} - + ```tsx {{ filename: 'app/forgot-password.tsx', collapsible: true }} 'use client' import React, { useState } from 'react' diff --git a/docs/custom-flows/multi-session-applications.mdx b/docs/custom-flows/multi-session-applications.mdx index 1653dcff07..41c0684329 100644 --- a/docs/custom-flows/multi-session-applications.mdx +++ b/docs/custom-flows/multi-session-applications.mdx @@ -26,7 +26,7 @@ To enable multi-session in your application, you need to configure it in the Cle ## Get the active session and user - + ```jsx import { useClerk } from '@clerk/clerk-react' @@ -53,7 +53,7 @@ To enable multi-session in your application, you need to configure it in the Cle ## Switch between sessions - + ```jsx import { useClerk } from '@clerk/clerk-react' @@ -97,7 +97,7 @@ For more information on how Clerk's sign-in flow works, see the [detailed sign-i Use [`signOut()`](/docs/references/javascript/clerk/clerk#sign-out) to deactivate all sessions on the current client. - + ```jsx import { useClerk } from '@clerk/clerk-react' @@ -122,7 +122,7 @@ Use [`signOut()`](/docs/references/javascript/clerk/clerk#sign-out) to deactivat Use [`signOut()`](/docs/references/javascript/clerk/clerk#sign-out) to deactivate a specific session by passing the session ID. - + ```jsx import { useClerk } from '@clerk/clerk-react' diff --git a/docs/custom-flows/oauth-connections.mdx b/docs/custom-flows/oauth-connections.mdx index a12985d0af..3456fe07f6 100644 --- a/docs/custom-flows/oauth-connections.mdx +++ b/docs/custom-flows/oauth-connections.mdx @@ -13,7 +13,7 @@ You must configure your application instance through the Clerk Dashboard for the When using OAuth, the sign-up and sign-in flows are equivalent. - + A successful OAuth flow consists of the following steps: @@ -167,7 +167,7 @@ It is common for users who are authenticating with OAuth to use a sign-in button The following example demonstrates how to handle these cases in your sign-in flow. To apply the same logic to the sign-up flow, simply replace `signIn.authenticateWithRedirect()` with `signUp.authenticateWithRedirect()` in your code. - + ```tsx {{ filename: 'app/sign-in/page.tsx', collapsible: true }} 'use client' diff --git a/docs/custom-flows/sign-out.mdx b/docs/custom-flows/sign-out.mdx index 732a57ebf8..86c4acfa0d 100644 --- a/docs/custom-flows/sign-out.mdx +++ b/docs/custom-flows/sign-out.mdx @@ -12,7 +12,7 @@ The `signOut()` function signs a user out of all sessions in a [multi-session ap > [!NOTE] > The sign-out flow deactivates only the current session. Other valid sessions associated with the same user (e.g., if the user is signed in on another device) will remain active. - + The [`useClerk()`](/docs/references/react/use-clerk) hook is used to access the `signOut()` function, which is called when the user clicks the sign-out button. diff --git a/docs/customization/elements/overview.mdx b/docs/customization/elements/overview.mdx index b571fe7ad4..5ce3b1254e 100644 --- a/docs/customization/elements/overview.mdx +++ b/docs/customization/elements/overview.mdx @@ -1,5 +1,5 @@ --- -title: Clerk Elements (Beta) +title: Clerk Elements (beta) description: Learn how to use Clerk Elements to build custom UIs on top of the Clerk APIs without having to manage the underlying logic. --- diff --git a/docs/deployments/deploy-chrome-extension.mdx b/docs/deployments/deploy-chrome-extension.mdx index 33ada0d783..609cd33bf6 100644 --- a/docs/deployments/deploy-chrome-extension.mdx +++ b/docs/deployments/deploy-chrome-extension.mdx @@ -17,7 +17,7 @@ For Clerk production instances, there must be a domain associated with the insta - 1. At the top in the Clerk Dashboard, in the instance selection dropdown, ensure that your production instance is selected. + 1. At the top of the Clerk Dashboard, in the instance selection dropdown, ensure that your production instance is selected. 1. In the navigation sidebar, select [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys). 1. In the **Quick Copy** section, select **Chrome Extension** and copy your Clerk Publishable and Frontend API keys. 1. Paste your keys into your `.env.production` file. @@ -64,7 +64,7 @@ The following example shows how to configure `host_permissions` for production: - 1. At the top in the Clerk Dashboard, in the instance selection dropdown, ensure that your production instance is selected. + 1. At the top of the Clerk Dashboard, in the instance selection dropdown, ensure that your production instance is selected. 1. In the navigation sidebar, select [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys). 1. Copy your Secret Key. It should begin with `sk_live_`. 1. In your terminal, paste the following command. Replace `YOUR_SECRET_KEY` with your Clerk Secret Key and the `` with your extension's ID. diff --git a/docs/index.mdx b/docs/index.mdx index cfc967dd9f..d533435561 100644 --- a/docs/index.mdx +++ b/docs/index.mdx @@ -69,19 +69,19 @@ Find all the guides and resources you need to develop with Clerk. --- - - [iOS (Beta)](/docs/quickstarts/ios) + - [iOS (beta)](/docs/quickstarts/ios) - Use the Clerk iOS SDK to authenticate users in your native Apple applications. - {} --- - - [TanStack Start (Beta)](/docs/quickstarts/tanstack-start) + - [TanStack Start (beta)](/docs/quickstarts/tanstack-start) - Easily add secure and SSR-friendly authentication to your TanStack Start application with Clerk. - ![](data:image/webp;base64,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) --- - - [React Router (Beta)](/docs/quickstarts/react-router) + - [React Router (beta)](/docs/quickstarts/react-router) - Easily add secure, edge- and SSR-friendly authentication to React Router with Clerk. - {} diff --git a/docs/manifest.json b/docs/manifest.json index ddee60a42e..f9b33e6bad 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -430,7 +430,7 @@ "href": "/docs/authentication/social-connections/linkedin-oidc" }, { - "title": "LinkedIn (Deprecated)", + "title": "LinkedIn (deprecated)", "href": "/docs/authentication/social-connections/linkedin" }, { @@ -458,7 +458,7 @@ "href": "/docs/authentication/social-connections/twitch" }, { - "title": "Twitter v1 (Deprecated)", + "title": "Twitter v1 (deprecated)", "href": "/docs/authentication/social-connections/twitter" }, { @@ -766,7 +766,7 @@ "href": "/docs/backend-requests/handling/manual-jwt" }, { - "title": "Node.js (Deprecated)", + "title": "Node.js (deprecated)", "href": "/docs/backend-requests/handling/nodejs" } ] diff --git a/docs/quickstarts/ios.mdx b/docs/quickstarts/ios.mdx index 6ee004f264..0aef3efdfe 100644 --- a/docs/quickstarts/ios.mdx +++ b/docs/quickstarts/ios.mdx @@ -1,5 +1,5 @@ --- -title: iOS Quickstart (Beta) +title: iOS Quickstart (beta) description: Add authentication and user management to your iOS app with Clerk. --- diff --git a/docs/quickstarts/overview.mdx b/docs/quickstarts/overview.mdx index ae8326fb50..de428cfb4f 100644 --- a/docs/quickstarts/overview.mdx +++ b/docs/quickstarts/overview.mdx @@ -30,7 +30,7 @@ description: See the getting started guides and tutorials. --- - - [TanStack Start (Beta)](/docs/quickstarts/tanstack-start) + - [TanStack Start (beta)](/docs/quickstarts/tanstack-start) - Easily add secure and SSR-friendly authentication to your TanStack Start application with Clerk. - ![](data:image/webp;base64,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) @@ -62,7 +62,7 @@ description: See the getting started guides and tutorials. --- - - [iOS (Beta)](/docs/quickstarts/ios) + - [iOS (beta)](/docs/quickstarts/ios) - Use the Clerk iOS SDK to authenticate users in your native Apple applications. - {} diff --git a/docs/quickstarts/react-router.mdx b/docs/quickstarts/react-router.mdx index 48c27b5398..bd97ce191b 100644 --- a/docs/quickstarts/react-router.mdx +++ b/docs/quickstarts/react-router.mdx @@ -1,5 +1,5 @@ --- -title: React Router Quickstart (Beta) +title: React Router Quickstart (beta) description: Learn how to use Clerk to quickly and easily add secure authentication and user management to your React Router application. --- diff --git a/docs/quickstarts/tanstack-start.mdx b/docs/quickstarts/tanstack-start.mdx index 0490284dca..4086fe8555 100644 --- a/docs/quickstarts/tanstack-start.mdx +++ b/docs/quickstarts/tanstack-start.mdx @@ -1,5 +1,5 @@ --- -title: TanStack Start Quickstart (Beta) +title: TanStack Start Quickstart (beta) description: Learn how to use Clerk to quickly and easily add secure authentication and user management to your TanStack Start application. --- diff --git a/docs/references/ios/overview.mdx b/docs/references/ios/overview.mdx index 8370e1a2a2..d96909ecc9 100644 --- a/docs/references/ios/overview.mdx +++ b/docs/references/ios/overview.mdx @@ -1,5 +1,5 @@ --- -title: Clerk iOS SDK (Beta) +title: Clerk iOS SDK (beta) description: Learn how to integrate Clerk into your iOS application using the Clerk iOS SDK. --- diff --git a/docs/references/overview.mdx b/docs/references/overview.mdx index be1073a7e6..ff55023b5d 100644 --- a/docs/references/overview.mdx +++ b/docs/references/overview.mdx @@ -48,7 +48,7 @@ description: Learn about the Clerk and community SDK's available for integrating --- - - [TanStack Start (Beta)](/docs/quickstarts/tanstack-start) + - [TanStack Start (beta)](/docs/quickstarts/tanstack-start) - Easily add secure and SSR-friendly authentication to your TanStack Start application with Clerk. - ![](data:image/webp;base64,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) diff --git a/docs/users/deleting-users.mdx b/docs/users/deleting-users.mdx index 3c2586a37a..6e9e74bf12 100644 --- a/docs/users/deleting-users.mdx +++ b/docs/users/deleting-users.mdx @@ -9,7 +9,7 @@ There are two ways to delete users in Clerk: [through the Clerk Dashboard](#dele To delete users in the Clerk Dashboard: -1. At the top in the Clerk Dashboard, select [**Users**](https://dashboard.clerk.com/last-active?path=users). +1. At the top of the Clerk Dashboard, select [**Users**](https://dashboard.clerk.com/last-active?path=users). 1. You can either select the user and then in the side navigation menu, select **Delete user**, or select the menu icon on the right side of the user's row and select **Delete user**. ## Delete users using the Clerk API diff --git a/styleguides/SSO.STYLEGUIDE.MD b/styleguides/SSO.STYLEGUIDE.MD index d7f7061968..72556e8255 100644 --- a/styleguides/SSO.STYLEGUIDE.MD +++ b/styleguides/SSO.STYLEGUIDE.MD @@ -69,18 +69,7 @@ These are the guidelines we use to write our SSO guides. Screenshots should be used little to none in the docs. The instructions should be explicit and include all necessary details without the need for a visual reference. The instructions should be laid out as numbered lists to make the content more palatable to readers. Links should be added on their first reference. -### Do - -```mdx -1. In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. -1. Select **Add connection** and select **For all users**. -1. In the **Choose provider** dropdown, select **Microsoft**. -1. Select **Add connection**. -``` - -### Don't - -In this example, the instructions are not explicit, as it tells the reader to select **Microsoft** but doesn't specify where to find it. +> ❌ In the example below, the instructions are not explicit, as it tells the reader to select **Microsoft** but doesn't specify where to find it. ```mdx 1. In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. @@ -89,162 +78,59 @@ In this example, the instructions are not explicit, as it tells the reader to se 1. Select **Microsoft**. ``` -## Bold proper nouns - -Bold proper nouns found in the UI, such as titles, headings, product names, etc. - -An exception to this rule is the Clerk Dashboard, which doesn't need to be bolded to enforce consistency across the docs. - -### Do - -```mdx -In the **Azure services** section, select **Microsoft Entra ID**. -``` - -### Don't +> ✅ In the example below, the instructions are explicit and include all necessary details without the need for a visual reference. ```mdx -In the Azure services section, select Microsoft Entra ID. +1. In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. +1. Select **Add connection** and select **For all users**. +1. In the **Choose provider** dropdown, select **Microsoft**. +1. Select **Add connection**. ``` ## Writing about redirects If the step ends with a redirect, include the redirect instructions in the step. -### Do - -1. Select **New application**. You'll be redirected to the . -1. Select **Create your own application**. - -### Don't +> ❌ +```mdx 1. Select **New application**. 1. In the ****, select **Create your own application**. - -## Component naming - -The proper names for the components are: - -- Dashboard: refers to a control panel or central hub where users can interact with multiple tools or view data -- Panel: drawer -- Modal: popup -- Dropdown - -## Use conjunctions - -Use conjunctions in the copy to make the copy more colloquial. - -### Do - -"You'll" - -### Don't - -"You will" - -## Avoid using "button" - -### Do - -```mdx -1. Select **New client secret**. ``` -### Don't +> ✅ ```mdx -1. Select the **New client secret** button. -``` - -## Avoid using "click" - -### Do - -```mdx -1. Select **New client secret**. -``` - -### Don't - -```mdx -1. Click **New client secret**. -``` - -## Avoid using "appears" - -### Do - -```mdx -In the panel that opens -``` - -### Don't - -```mdx -In the panel that appears +1. Select **New application**. You'll be redirected to the . +1. Select **Create your own application**. ``` -## Action verbs - -- Add: general use (e.g., Add your app information) -- Enter: general typing (e.g., Enter your email address) -- Paste: to copy and paste values (e.g., Paste the Client ID you copied from the Clerk Dashboard) -- Complete: to fill out forms - -## Application vs. app - -Use "application" for the first instance where it's used and then "app" for the rest of the guide. - -## Redirected to vs. taken to - -Use "redirected to" instead of "taken to." +## Page vs. tab -## Ensure vs. make sure - -Use "ensure" instead of "make sure." - -### Do - -```mdx -On this same page, under **Client credentials**, select **Add a certificate or secret** to generate a Client Secret. You'll be redirected to the **Certificate & secrets** page. -``` +Assume users are opening windows versus browser tabs. Use active voice (e.g., "keep" vs. "leave). -### Don't +> ❌ The first example is wrong because it uses "leave" instead of "keep" and "tab" instead of "page." ```mdx -On this same page, under **Client credentials**, select **Add a certificate or secret** to generate a Client Secret. You'll be taken to the **Certificate & secrets** page. +Leave the tab open. ``` -## Page vs. Tab - -Assume users are opening windows versus browser tabs. Use active voice (e.g., "keep" vs. "leave). - -### Do +> ✅ This example is correct because it uses "keep" and "page". ```mdx Keep the page open. ``` -### Don't +## Complete vs. fill out -```mdx -Leave the page open. -``` +> ❌ ```mdx -Leave the tab open. +Fill out the form as follows ``` -## Complete vs. Fill out - -### Do +> ✅ ```mdx Complete the form as follows ``` - -### Don't - -```mdx -Fill out the form as follows -``` diff --git a/styleguides/STYLEGUIDE.md b/styleguides/STYLEGUIDE.md index 83c03cdbba..6c1552da28 100644 --- a/styleguides/STYLEGUIDE.md +++ b/styleguides/STYLEGUIDE.md @@ -1,452 +1,326 @@ -# Clerk Docs Styleguides +# Clerk Docs Styleguide These are the guidelines we use to write our docs. -## 1. Write with consistency +## Content (grammar/structure) -### 1.1 Use American English +### De-dupe reference links -Clerk is an American company and the epicenter of our development community is located in America's tech community. For that reason, we use the American flavor of English (as opposed to British English). - -#### Do - -> You might not realize it, but you can change the colors of your Clerk components with global CSS. - -#### Don't - -> You might not realise it, but you can change the colours of your Clerk components with global CSS. - -### 1.2 Hyphens? Spaces? Neither! - -Tech has created many new words by associating two words with each other like "front end" and "web site." On a long enough timeline, these migrate to hyphenated forms: "web site" became "web-site." And finally they become concatenated words: "website." We use the concatenated forms. - -#### Do - -> Frontend and fullstack developers often build websites with React. - -#### Don't - -> Front-end and full stack developers often build web-sites with React. - -### 1.3 De-dupe reference links - -When mentioning a documented component, function, etc, multiple times on a page, link to the reference documentation on the first mention of that item. The exception to this rule is when the reference is mentioned under a different heading. In that case, link to the reference documentation again. - -#### Do - -> The [`currentUser()`](https://clerk.com/docs/references/nextjs/current-user) helper will return the [`User`](https://clerk.com/docs/references/javascript/user/user) object of the currently active user. The following example uses the `currentUser()` helper to access the `User` object for the authenticated user. - -#### Don't +When mentioning a documented component, function, etc, multiple times on a page, link to the reference documentation on the **first mention** of that item. The exception to this rule is when the reference is mentioned under a different heading. In that case, link to the reference documentation again. +> ❌ > The [`currentUser()`](https://clerk.com/docs/references/nextjs/current-user) helper will return the [`User`](https://clerk.com/docs/references/javascript/user/user) object of the currently active user. The following example uses the [`currentUser()`](https://clerk.com/docs/references/nextjs/current-user) helper to access the [`User`](https://clerk.com/docs/references/javascript/user/user) object for the authenticated user. -### 1.4 Write out abbreviations when introducing them - -If you want to abbreviate a term in your article, write it out fully first, then put the abbreviation in parentheses. If you want to make an abbreviation plural treat them as regular words, e.g. APIs, IDEs or OSes. - -#### Do - -> An abstract syntax tree (AST) is a tree representation of code. ASTs are a fundamental part of the way a compiler works. +> ✅ +> The [`currentUser()`](https://clerk.com/docs/references/nextjs/current-user) helper will return the [`User`](https://clerk.com/docs/references/javascript/user/user) object of the currently active user. The following example uses the `currentUser()` helper to access the `User` object for the authenticated user. -#### Don't +### Use sentence-case for titles -> An AST is a tree representation of code. AST's are a fundamental part of the way a compiler works. +> ❌ +> How to Set up Custom Pages -### 1.5 Use sentence case for titles +> ✅ +> How to set up custom pages -#### Do +### Use backticks for component references in MDX page titles -> ## How to set up custom pages +When writing titles that contain component references in MDX pages, wrap the component name in backticks and escape any angle brackets. -#### Don't +> ❌ +> title: '' +> title: -> ## How to Set up Custom Pages +> ✅ +> title: '``' -### 1.5 When referring to Next.js proper nouns, follow Next.js's capitalization conventions +### When referring to Next.js proper nouns, follow Next.js's capitalization conventions "Middleware," "Server Actions," "Server Components," "Route Handlers" are capitalized in the Next.js docs and in Clerk's docs where referring to a Next.js project or code. -#### Do +> ❌ +> Add it to your app's middleware. +> ✅ > Add it to your app's Middleware. -#### Don't - -> Add it to your app's middleware. - -### 1.6 Use "Sign in", not "Log in" +### Use "Sign in", not "Log in" -When referring to Clerk's SDKs, components, and dashboard, use "sign in" and "sign out" rather than "log in" or "log out". This is consistent with our `` component and `SignIn` class. +Use "sign in" and "sign out" rather than "log in" or "log out". -#### Do +> ❌ +> `` creates a button that allows users to log into your Clerk application. +> ✅ > `` creates a button that allows users to sign into your Clerk application. -#### Don't - -> `` creates a button that allows users to log into your Clerk application. - -## 2. Write for clarity +### Write out abbreviations when introducing them -### 2.1 “You” is the reader; "Clerk" is Clerk +If you want to abbreviate a term in your article, write it out fully first, then put the abbreviation in parentheses. If you want to make an abbreviation plural treat them as regular words, e.g. APIs, IDEs or OSes. -Clerk is the entity writing these docs and providing these services. The learner is the person consuming these things and building their own projects. To distinguish between the two and write with clarity, we refer to the learner with "you/your/yours." We objectively refer to Clerk as "Clerk," not "we/us/our/ours." +> ❌ +> An AST is a tree representation of code. AST's are a fundamental part of the way a compiler works. -#### Do +> ✅ +> An abstract syntax tree (AST) is a tree representation of code. ASTs are a fundamental part of the way a compiler works. -> Clerk's `` provides active session and user context to Clerk's hooks and other components. Import it into your app by adding `import { ClerkProvider } from '@clerk/nextjs'` at the top of your file. +### Avoid "we/us/our/ours" -#### Don't +We refer to the reader with "you/your/yours." We objectively refer to Clerk as "Clerk," not "we/us/our/ours." +> ❌ > Our `` provides active session and user context to our hooks and other components. Let's import it into our app by adding `import { ClerkProvider } from '@clerk/nextjs'` at the top of the file. -### 2.2 "Users" are people logging in/out with Clerk. "Developers" are the audience we’re writing for. - -People building with clerk are building for other people to make it clear whether we are talking about the builder or their users, we call builders "developers" and the peoeple they are building for "users." - -#### Do - -> Clerk helps developers overcome as many challenges as possible without additional configuration. This ensures their users have a secure, safe session. - -#### Don't - -> Clerk helps users overcome as many challenges as possible without additional configuration. This ensures their users have a secure, safe session. - -### 2.3 Shorter is better - -Write short sentences. Short sentences are easier for both human and robots to translate. Concise writing is understandable writing. Look for commas that string together different thoughts. These are often good places to shorten and clarify content. +> ✅ +> Clerk's `` provides active session and user context to Clerk's hooks and other components. Import it into your app by adding `import { ClerkProvider } from '@clerk/nextjs'` at the top of your file. -#### Do +## Use conjunctions -> Clerk is now installed and mounted in your application. You can decide which pages are public or require authentication to access. +Use conjunctions in the copy to make the copy more colloquial. -#### Don't +> ❌ +> "You will" -> Now that Clerk is installed and mounted in your application, you can decide which pages are public and which should require authentication to access. +> ✅ +> "You'll" -### 2.4 Avoid gerunds (-ing words) +### Avoid gerunds (-ing words) English gerunds ("-ing" words like "running") turn verbs into nouns ("run" becomes "running"). This makes the sentence sound passive ("They run" becomes "they are running") and makes it harder to translate. Use an active voice as much as possible and avoid these words. -#### Do - -> How to use a routing library with Clerk - -#### Don't - +> ❌ > Using a routing library with Clerk -### 2.5 Use task and outcome-based headings and titles that use verbs. - -Tell the learner what they will learn from diving into the content. - -#### Do - -> How to read session and user data - -> How user sessions and user data work - -Clearly explains what information the learner will find, helping them decide which to choose. - -#### Don't - -> User session and user data - -Obscure. Doesn't convey whether this is the conceptual or task-based content the learner is looking for. They may pass over it or look briefly, then bounce out. This increases friction. +> ✅ +> How to use a routing library with Clerk -### 2.6 Lead with location; end with action. +### Lead with location; end with action. When learners are performing an order of operations, it helps for them to start with _where_ they need to be to perform the action. -#### Do - -> In your Next.js project's root folder, open your `.env.local file`. - -The learner navigates to the project folder first, opens the file second. - -#### Don't - +> ❌ > Open your `.env.local file` in your Next.js project's folder. -The learner must remember the file they need to open before finding out which folder to navigate to. This uses more mental energy. - -### 2.7 Avoid colloquialisms - -English speakers may find themselves using phrases which cultural meaning may be different around the world. - -#### Do - -> Something that is difficult for someone new to programming may not be for a senior engineer. - -#### Don't - -> Something that is difficult for someone new to programming may be child's play for a senior engineer. - -Some learners may not have heard this expression before. It may be difficult for machine translation as well. +> ✅ +> In your Next.js project's root folder, open your `.env.local file`. -### 2.8 Use a active voice vs. passive voice. +### Use an active voice vs. passive voice Use active verbs that put the reader in the first person instead of passive verbs; "be" verbs that describe the learners actions as a state of being, like "is/was/to be". -#### Do - -> Create the `middleware.ts` file in the root folder of your application or inside the `src/` if that is how your app is set up. - -#### Don't - +> ❌ > The `middleware.ts` file should be created in the root folder of your application or inside `src/` if that is how you set up your app. -## 3. Write to include people - -### 3.1 Do not assume proficiency - -Avoid using language that assumes someone's level of proficiency. Something that is difficult for someone new to programming may not be difficult for a senior engineer. This language can inadvertently alienate or insult a learner. Avoid words like "just," "easy," "simple," "senior," "hard." - -Use as little [jargon](https://dictionary.cambridge.org/dictionary/english/jargon) as necessary. Describe jargon in parentheses on first reference or link to a trusted definition. - -#### Do - -> You can authenticate your app with Clerk in three steps. Install Clerk with `npm install @clerk/nextjs`, add your environment variables, and then wrap your app in ``, and add [control components](https://clerk.com/docs/components/overview). Visit our [Quickstarts](https://clerk.com/docs/quickstarts/overview) for a step-by-step guide written for your framework. - -> Clerk supports offline mode, a feature that lets users use an app without being connected to data or wifi. This means Clerk works great with progressive web apps, apps built with web platform technologies that provide similar experiences to platform-specific apps. You can use the [dynamic import pattern](https://www.patterns.dev/vanilla/dynamic-import) to improve loading speeds. +> ✅ +> Create the `middleware.ts` file in the root folder of your application or inside the `src/` if that is how your app is set up. -#### Don't +> ❌ +> User session and data -> It's easy to authenticate your app with Clerk! Just install Clerk with `npm install @clerk/nextjs`, add your environment variables, wrap your app in ``, and simply add [control components](https://clerk.com/docs/components/overview). +> ✅ +> Read user session and data -> Clerk works great with PWA as it supports offline mode. You can use the dynamic import pattern to improve loading speeds. +### Bold proper nouns -### 3.2 Avoid pop culture references +Bold proper nouns found in the UI, such as titles, headings, product names, etc. -It's tempting to use things that are familiar to us to explain things to others—our favorite TV shows, books, and memes are entertaining and rich sources of metaphors. However, they assume a shared context between author and reader. A joke that mainstream American audiences understand may be completely misunderstood to a learner in Chile. +An exception to this rule is "the Clerk Dashboard", which doesn't need to be bolded because it's referenced often in the docs and we want to avoid too much visual noise. -#### Do +> ❌ -```js -const updateUser = async () => { - await user.update({ - firstName: 'John', - lastName: 'Doe', - }) -} +```mdx +In the Azure services section, select Microsoft Entra ID. ``` -#### Don't +> ✅ -```js -const updateUser = async () => { - await user.update({ - firstName: 'Twilight', - lastName: 'Sparkle', - }) -} +```mdx +In the **Azure services** section, select **Microsoft Entra ID**. ``` -This assumes the learner is familiar with the cartoon _My Little Pony: Friendship is Magic,_ which is irrelevant. - -### 3.3 Use "they/them/theirs" pronouns - -For many years it was common to write with "he/him/his" pronouns in English technical documentation. But pronouns are difficult to translate into some languages. Gendering learners also sends the message that some genders are "default"—and this might not be the learner's gender. We use the neutral "they/them/theirs" pronouns. - -#### Do +### Component naming -> When the user logs out using the button, they will be taken to the sign-in page. +The proper names for the components are: -#### Don't +- Dashboard: refers to a control panel or central hub where users can interact with multiple tools or view data +- Panel: drawer +- Modal: popup +- Dropdown -> When he logs out using the button, he will be taken to the sign-in page. +### Application vs. app -### 3.4 Avoid "click" +Use "application" for the first instance where it's used and then "app" for the rest of the guide. -"Click" is an outdated term that assumes the learner is using a mouse. But learners may be navigating by touchscreen, keyboard, or assistive technology. Often there are better words than "click"—like "select" and "open". +### Redirected to vs. taken to -#### Do - -> Open the **Settings tab.** - -> Select the **Google** social connection. +Use "redirected to" instead of "taken to." -#### Don't +> ❌ -> Click the **Settings tab.** - -> Click the **Google** social connection. - -## 4. Write for code - -### 4.1 Use monospace fonts for code, commands, file names, copy-ables, and URLs; use bold for menus, and other UI copy. - -#### Do - -> In the Clerk Dashboard, go to **User & Authentication > [Social Connections](https://dashboard.clerk.com/last-active?path=user-authentication/social-connections)** and open the **Settings** tab. - -> In your browser, open [`http://localhost:3000/`](http://localhost:3000/). - -#### Don't - -> In the [Clerk Dashboard](https://dashboard.clerk.com/), go to `User & Authentication > Social Connections` and open the "Settings tab." - -> In your browser, open [`http://localhost:3000/`](http://localhost:3000/). - -### 4.2 Use carets to help users navigate menus - -Use carets to nest operations of the same type like menu navigation. - -#### Do +```mdx +On this same page, under **Client credentials**, select **Add a certificate or secret** to generate a Client Secret. You'll be taken to the **Certificate & secrets** page. +``` -> In the [Clerk Dashboard](https://dashboard.clerk.com/), go to **User & Authentication > [Social Connections](https://dashboard.clerk.com/last-active?path=user-authentication/social-connections)** and open the **Settings tab.** +> ✅ -#### Don't +```mdx +On this same page, under **Client credentials**, select **Add a certificate or secret** to generate a Client Secret. You'll be redirected to the **Certificate & secrets** page. +``` -> In the [Clerk Dashboard](https://dashboard.clerk.com/), go to **User & Authentication**, click on **Social Connections**, and open the **Settings tab.** +## Ensure vs. make sure -### 4.3 Write compliant JSON: no single quotes, no comments +Use "ensure" instead of "make sure." -Conform to the [JSON standard](https://www.json.org/json-en.html): +> ❌ +> Make sure you have the correct permissions. -- Key names are enclosed in double quotes (`"`) -- Values are between double quotes (`"`), not single quotes (`'`) -- No comments, neither `//` nor `/* */` +> ✅ +> Ensure you have the correct permissions. -#### Do +### Syntax for code example explanations -> This is the user's primary email address in the User object +Code examples should always have an explanation preceding them. Typically, they begin with something along the lines of "The following example demonstrates..." -```json -{ - "email": "{{user.primary_email_address}}" -} -``` +> ❌ You might have already configured ``. Ensure that `` wraps `ConvexProviderWithClerk` and that `useAuth` is passed to `ConvexProviderWithClerk`. -#### Don't +> ✅ The following example demonstrates how to configure Clerk and Convex's providers. Clerk's `useAuth()` hook must be passed to `` and Clerk's `` must be wrapped around it. -```json -{ - // this is the user's primary email address in the User object - "email": "{{user.primary_email_address}}" -} -``` +## Accessibility -### 4.4 Use 2-space indents for code blocks +### Do not assume proficiency -We use 2-space indents to conserve horizontal space in code blocks. +Avoid using language that assumes someone's level of proficiency. Something that is difficult for someone new to programming may not be difficult for a senior engineer. This language can inadvertently alienate or insult a learner. Avoid words like "just", "easy", "simple", "senior", "hard". -#### Do +Use as little [jargon](https://dictionary.cambridge.org/dictionary/english/jargon) as necessary. Describe jargon in parentheses on first reference or link to a trusted definition. -```js -export const config = { - matcher: ['/((?!.+\\.[\\w]+$|_next).*)', '/', '/(api|trpc)(.*)'], -} -``` +> ❌ +> It's _easy_ to authenticate your app with Clerk! -#### Don't +> ✅ +> You can authenticate your app with Clerk in three steps. -```js -export const config = { - matcher: ['/((?!.+\\.[\\w]+$|_next).*)', '/', '/(api|trpc)(.*)'], -} -``` +> ❌ +> Clerk works great with PWA as it supports offline mode. -### 4.5 Authentication states should be hyphenated and bold. +> ✅ +> Clerk supports offline mode, a feature that lets users use an app without being connected to data or wifi. -Clerk authentication states **signed-in**, **signed-out**, and **unknown** should be hyphenated and bold to distinguish them from general states of being. +### Avoid "click" -#### Do +"Click" is an outdated term that assumes the learner is using a mouse. But learners may be navigating by touchscreen, keyboard, or assistive technology. Often there are better words than "click", like "select" and "open". -> Once you have a **signed-in** user, you need to give them a way to sign out. +> ❌ +> Click the **Settings tab.** +> +> Click the **Google** social connection. -#### Don't +> ✅ +> Open the **Settings tab.** +> +> Select the **Google** social connection. -> Once you have a signed-in user, you need to give them a way to sign out. +### Avoid using "button" -### 4.6 Group like with like under tabs +> ❌ Select the **New client secret** button. -When presenting things in a series of tabs, ensure that similar things are grouped together. +> ✅ Select **New client secret**. -#### Do +## Code -![App Router and Pages Router exist as two tabs, side by side](/.github/media/uncrowded-tabs.png) +### Use monospace fonts for code, commands, file names, and URLs -Next.js is a platform with two different implementations grouped underneath it. +> ❌ +> Copy the environment variables to your .env file. -#### Don't +> ✅ +> Copy the environment variables to your `.env` file. -![App Router and Pages Router are sitting alongside other very different methods of retrieving data](/.github/media/crowded-tabs.png) +> ❌ +> In your browser, open http://localhost:3000/. -Next.js's two implementations are given equal weight to the other members of the tab bar. Someone unfamiliar with Next.js may become confused, and the ever growing tab bar is harder to navigate at smaller sizes. +> ✅ +> In your browser, open [`http://localhost:3000/`](http://localhost:3000/). -### 4.7 Wrap component references in the appropriate tags +### Wrap component references in the appropriate tags Component references should be wrapped in `< />` if they are self closing. Otherwise, they should be wrapped in `< >`. -#### Do - -> Use the `` component. - -> Use the `` component. - -#### Don't - +> ❌ > Use the `` component. +> ❌ > Use the "SignIn component". +> ❌ > Use the `SignIn` component. +> ❌ > Use the `` component. The last case is incorrect because the `` component will never wrap children, and therefore, should have a self-closing tag. -> Use the `` component. - -The last case is incorrect because the `` component will always wrap children and will never be self-closing. +> ✅ +> Use the `` component. -### 4.8 Specify syntax and filename for terminal commands +### Specify syntax and filename for terminal commands If the code should run in a terminal, set the code block's syntax highlighting and filename with `sh filename="terminal"`. -#### Do +> ❌ ```` -​```sh {{ filename: 'terminal' }} +​``` npm i @clerk/nextjs ​``` ```` -#### Don't +> ✅ ```` -​``` +​```sh {{ filename: 'terminal' }} npm i @clerk/nextjs ​``` ```` -### 4.9 Pass properties to components; Parameters to functions +### Pass properties to components; parameters to functions Be sure to use the correct term with components vs functions. -> Be sure to use the appropriate terms on reference page headings. - -#### Do +> ❌ +> The `` component accepts the `signUpProps` parameter. The `buildUrlWithAuth()` function accepts the `to` property. +> ✅ > Pass the `signUpProps` property to ``. `buildUrlWithAuth()` accepts a `string` for the `to` parameter. -#### Don't - -> The `` component accepts the `signUpProps` parameter. The `buildUrlWithAuth()` function accepts the `to` property. +## Page navigation -### 4.10 Provide users with clear instructions and a direct link when navigating the Clerk Dashboard +### Provide users with clear instructions and a direct link when navigating the Clerk Dashboard When instructing learners to perform an operation in the Clerk Dashboard, begin with "In the Clerk Dashboard" and end with a link to the page you're directing them to using this URL syntax: **`https://dashboard.clerk.com/last-active?path=PAGE`** -#### Do +> ❌ +> Go to **User & Authentication** in your dashboard. + +> ✅ +> In the Clerk Dashboard, navigate to the [**User & Authentication**](https://dashboard.clerk.com/last-active?path=user-authentication) page. -> In the Clerk Dashboard, navigate to **[User & Authentication](https://dashboard.clerk.com/last-active?path=user-authentication)** page. +> ❌ +> Find fallback redirects in the Redirect tab on the Account Portal in the Clerk Dashboard. +> ✅ > To specify the fallback redirects, in the Clerk Dashboard, go to the **[Account Portal](https://dashboard.clerk.com/last-active?path=account-portal)** page and open the **Redirects** tab. -#### Don't +### Avoid using "appears" -> Go to **User & Authentication** in your dashboard. +> ❌ +> A modal will appear. -> Find fallback redirects in the Redirect tab on the Account Portal in the Clerk Dashboard. +> ✅ +> A modal will open. + +### Address the top of the Clerk Dashboard + +> ❌ +> In the top navigation bar of the Clerk Dashboard, select [**Users**](https://dashboard.clerk.com/last-active?path=users). + +> ✅ +> At the top of the Clerk Dashboard, select [**Users**](https://dashboard.clerk.com/last-active?path=users).