Refresh customization docs

[brkalow]

⚠️ Typedoc PR: #2870. We will need to combine these PRs to avoid missing pages for incorrect links.

✅ Typedoc PR: clerk/javascript#7384

🔎 Previews:

• https://clerk.com/docs/pr/brkfeat-customization-docs-tweaks/guides/customizing-clerk/overview
• https://clerk.com/docs/pr/brkfeat-customization-docs-tweaks/guides/customizing-clerk/bring-your-own-css

What does this solve?

• Clarifies the different layers of Clerk customization so readers can choose the right approach instead of hunting through scattered content
• Moves the Account Portal guide out of the customization section

What changed?

• Added a Customizing Clerk overview plus a dedicated Bring Your Own CSS guide, which moves existing content from the appearance prop overview page to a more use case focused guide
• Reworked the appearance prop reference to point toward the new guides and trim redundant explanations
• Relocated account-portal/overview to its own guide folder and updated the docs manifest and redirects to match the new structure

Checklist

• I have clicked on "Files changed" and performed a thorough self-review
• All existing checks pass

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Updated (UTC)
clerk-docs	Error		Dec 10, 2025 8:31pm

[github-actions]

⚠️ TypeDoc files detected in this PR

This PR modifies files in the 'clerk-typedoc/' folder. These files are auto-generated from the clerk/javascript repository and should not be edited directly.

To make changes to TypeDoc documentation:

1. 🔄 Make your changes in the appropriate files in the clerk/javascript repository.
2. 🚀 The TypeDoc documentation will be pulled through to this repository via a CI action.

Thanks for contributing! 🙏

[SarahSoutoul]

Okay, I have left an initial docs review with mostly writing style / syntax consistency.

There are some bigger restructuring changes I want to do, but I wanted to first suggest them here and get everyone's opinions as they're important discussion pts @brkalow @alexisintech @manovotny:

1. As part of this PR, the account portal was moved into its own section. This change was based on the following rationale according to @brkalow: "it doesn't fit under customization IMO. customizing Clerk is mostly focused on customizing components / UI and other code-side settings". I do agree with this reasoning; only thing is it does look a bit odd on its own. One solution could be to destructure the Account portal overview into diff pages like we used to have, or we leave it as is. So I'd like to check opinions on this:

   

2. To me, the Bring your own CSS page belongs within Component customization, so as a sub-sidebar option rather than its own sidebar option. It's still about customizing components, uses the appearance prop, and is mentioned within the appearance prop itself alongside the other props. So consistency wise, it makes more sense to have it as a sub-section.

3. I agree that Build your own UI should be under Component customization, as it's about custom flows. But, we may as well physically move the current Build your own UI section under Development, rather than link it to lead the user there. This would also align with what we had planned already: https://clerkinc.slack.com/archives/C01QFRQNHSN/p1764110358607419.

4. I'm not sure about the necessity of the new Overview - to me it just feels like a repetition of the Appearance prop page but in diff words. It only mentions the stuff under Component customization, and not the other stuff. If we want it as an actual overview of the entire Customizing Clerk section, I think it should mention other things like localization, custom menu items, etc. Or, if it's just for everything under Component customization, then it should be moved within that section.

[SarahSoutoul]

@alexisintech @manovotny @brkalow point 4 has now been tackled in this commit. In addition to revamping the overview, I have also added a reference to the Theme editor in the Themes page. I also descoped that overview to be visible for all SDKs since it now refers to things that are available in all SDKs. But, I made sure to have a callout for native apps (for now iOS with ClerkTheme, but will get updated to include Android after Sam's PR is out)

Let me know if this new overview flows nicely.

It's worth noting that the build fails for now, as the "old" account portal links are mentioned in some of the Typedocs. But this is where the Typedoc PR linked in this PR's description comes in.

[alexisintech]

needs typedoc changes pulled in, but the most recent typedoc pr didn't pull in the merged typedoc changes
🤔 does this have something to do with the core-2/core-3 branches? i couldn't find these changes pulled in neither the core-2 nor core-3 prs
@SarahSoutoul @NWylynko

[SarahSoutoul]

needs typedoc changes pulled in, but the most recent typedoc pr didn't pull in the merged typedoc changes 🤔 does this have something to do with the core-2/core-3 branches? i couldn't find these changes pulled in neither the core-2 nor core-3 prs @SarahSoutoul @NWylynko

Someone seems to have removed the linked Typedoc PR I had in the PR description. It is this one yeah: #2870. It did pull them in. If you check the clerk-typedoc/clerk-react/clerk-provider-props.mdx file, it's all there @alexisintech.

Example:

[alexisintech]

needs typedoc changes pulled in, but the most recent typedoc pr didn't pull in the merged typedoc changes 🤔 does this have something to do with the core-2/core-3 branches? i couldn't find these changes pulled in neither the core-2 nor core-3 prs @SarahSoutoul @NWylynko

Someone seems to have removed the linked Typedoc PR I had in the PR description. It is this one yeah: #2870. It did pull them in. If you check the clerk-typedoc/clerk-react/clerk-provider-props.mdx file, it's all there @alexisintech.

Example:

awesome! i reviewed yesterday and it seems like its ready to ship 🚢