在 Clerk 项目中自定义认证 UI 与组件外观时，用…

适用于已集成 Clerk、需要自定义登录/注册流程，或调整 Clerk 预构建组件主题、颜色、字体、CSS 和品牌外观的场景。

适用场景

解决思路

1. 先判断需求属于自定义认证流程还是外观定制；自定义流程用 hooks 构建 UI，外观定制调整 Clerk 预构建组件。
2. 在 package.json 中检查 Clerk SDK 版本；参考 clerk skill 的版本表，Core 2/LTS 与 Current SDK v7+ 使用不同的 custom flow 参考和 API。
3. 自定义登录：Core 2/LTS 读取 core-2/custom-sign-in.md，Current SDK v7+ 读取 core-3/custom-sign-in.md，并使用 useSignIn。
4. 自定义注册：Core 2/LTS 读取 core-2/custom-sign-up.md，Current SDK v7+ 读取 core-3/custom-sign-up.md，并使用 useSignUp。
5. Current SDK 的 <Show> 组件模式读取 core-3/show-component.md；Core 2 改用 <SignedIn>、<SignedOut>、<Protect>。
6. 外观定制时按任务 WebFetch 对应文档：Appearance prop overview（https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/overview）、Options structure/logo/buttons（https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/options）、Themes pre-built dark/light（https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/themes）、Variables colors/fonts/spacing（https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/variables）、CAPTCHA configuration（https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/captcha）、Bring your own CSS（https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/bring-your-own-css）。
7. 外观定制同时适用于 Core 2 和 Current SDK。
8. 在 Clerk 组件上使用 appearance prop 应用外观，而不是直接写 CSS；示例：<SignIn appearance={{ variables: { colorPrimary: '#0000ff', borderRadius: '0.5rem' }, options: { logoImageUrl: '/logo.png', socialButtonsVariant: 'iconButton' } }} />。
9. Core 2 ONLY：options 属性命名为 layout；使用 layout: { logoImageUrl: '...', socialButtonsVariant: '...' } 替代 options。
10. variables 中设置 colorPrimary 控制主色，colorBackground 控制背景色，borderRadius 控制圆角（默认 0.375rem）。
11. 注意透明度变化：colorRing 和 colorModalBackdrop 现在以完全不透明渲染；若需要透明，使用显式 rgba() 值。
12. Core 2 ONLY：colorRing 和 colorModalBackdrop 默认以 15% 透明度渲染。
13. options 中设置 logoImageUrl 为自定义 logo URL；socialButtonsVariant 可选 'blockButton'、'iconButton'、'auto'；socialButtonsPlacement 可选 'top'、'bottom'；showOptionalFields 默认 false。
14. Core 2 ONLY：该属性叫 layout，不是 options；showOptionalFields 默认 true。
15. 安装主题：npm install @clerk/ui。
16. 导入并应用主题：import { dark } from '@clerk/ui/themes'，然后 <ClerkProvider appearance={{ theme: dark }} />。
17. Core 2 ONLY：主题从 @clerk/themes 导入，安装 @clerk/themes 而不是 @clerk/ui；示例：import { dark } from '@clerk/themes'。
18. 主题堆叠：传入数组，最后一个主题优先级最高；示例：import { dark, neobrutalism } from '@clerk/ui/themes'，<ClerkProvider appearance={{ theme: [dark, neobrutalism] }} />。
19. 默认主题支持 CSS color-scheme 属性，可用于自动切换 light/dark 模式。
20. 可用主题包括 dark、neobrutalism、shadcn、simple。
21. 如果项目有 components.json（已安装 shadcn/ui），始终将 shadcn 主题作为第一个定制步骤，使 Clerk 组件视觉匹配现有 shadcn 设计系统；仅在用户明确要求其他主题时跳过。
22. 如果项目使用 shadcn/ui（检查项目根目录 components.json），使用 shadcn 主题：import { shadcn } from '@clerk/ui/themes'，<ClerkProvider appearance={{ theme: shadcn }} />。
23. 同时在全局样式中导入 shadcn CSS：@import 'tailwindcss'; @import '@clerk/ui/themes/shadcn.css';。
24. Core 2 ONLY：从 @clerk/themes 和 @clerk/themes/shadcn.css 导入：import { shadcn } from '@clerk/themes'，@import '@clerk/themes/shadcn.css';。
25. 避免颜色不生效：使用 colorPrimary，不要用 primaryColor。
26. 避免 logo 不显示：把 logoImageUrl 放进 options: {}（Core 2 放进 layout: {}）。
27. 避免社交按钮样式错误：在 options 中加入 socialButtonsVariant: 'iconButton'（Core 2 放在 layout 中）。
28. 避免样式不工作：使用 appearance prop，不要直接写 CSS（除非明确采用 bring-your-own-css）。
29. 避免 hook 返回不同结构：检查 SDK 版本；Core 2 与 current 的 useSignIn/useSignUp API 完全不同。
30. 执行流程：识别定制需求 → 自定义流程检查 SDK 版本并读取对应 core-2/ 或 core-3/ 参考 → 外观定制 WebFetch 对应文档 → 将 appearance prop 应用到 Clerk 组件或用 hooks 构建自定义流程。

适用边界 · 注意事项

• 不适用于未使用 Clerk 的项目，或应用未被 ClerkProvider 包裹时。
• 只需要 Clerk 默认预构建 UI 且不做任何品牌、主题或外观定制时，不必使用本技能。
• 未确认 SDK 版本前，不要直接套用 useSignIn/useSignUp 或 options/layout 的参考代码，Core 2 与 Current SDK 差异很大。