AgentSkillsCN

clerk-custom-ui

自定义 Clerk 组件的外观——主题、布局、颜色、字体、CSS。适用于外观美化、视觉定制与品牌塑造。

SKILL.md
--- frontmatter
name: clerk-custom-ui
description: Customize Clerk component appearance - themes, layout, colors, fonts, CSS. Use for appearance styling, visual customization, branding.
allowed-tools: WebFetch
license: MIT
metadata:
  author: clerk
  version: "1.0.0"

Component Customization

Prerequisite: Ensure ClerkProvider wraps your app. See setup/.

Component Customization Options

TaskDocumentation
Appearance prop overviewhttps://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/overview
Layout (structure, logo, buttons)https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/layout
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 configurationhttps://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/captcha
Bring your own CSShttps://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/bring-your-own-css

Appearance Pattern

typescript
<SignIn
  appearance={{
    variables: {
      colorPrimary: '#0000ff',
      borderRadius: '0.5rem',
    },
    layout: {
      logoImageUrl: '/logo.png',
      socialButtonsVariant: 'iconButton',
    },
  }}
/>

variables (colors, typography, borders)

PropertyDescription
colorPrimaryPrimary color throughout
colorBackgroundBackground color
borderRadiusBorder radius (default: 0.375rem)

layout (structure, logo, social buttons)

PropertyDescription
logoImageUrlURL to custom logo
socialButtonsVariant'blockButton' | 'iconButton' | 'auto'
socialButtonsPlacement'top' | 'bottom'

shadcn Theme

If the project has components.json (shadcn/ui installed), use the shadcn theme:

typescript
import { shadcn } from '@clerk/themes'

<ClerkProvider
  appearance={{
    theme: shadcn,
  }}
/>

Also import shadcn CSS in your global.css:

css
@import 'tailwindcss';
@import '@clerk/themes/shadcn.css';

Workflow

  1. •Identify customization needs (colors, layout, theme, CSS)
  2. •WebFetch the appropriate documentation from table above
  3. •Follow official code examples from the docs
  4. •Apply appearance prop to your Clerk components

Common Pitfalls

IssueSolution
Colors not applyingUse colorPrimary not primaryColor
Logo not showingPut logoImageUrl inside layout: {}
Social buttons wrongAdd socialButtonsVariant: 'iconButton' in layout
Styling not workingUse appearance prop, not direct CSS (unless with bring-your-own-css)