{"id":14575,"plugin_id":"plugin_asdk_app_6a9a3c1cd0108191807da33c4cd319ed","kind":"skill","collection_source":null,"comparison_source":null,"observed_at":"2026-09-30T23:09:49.310Z","digest":"6a54a05be05fe3381a21a1066cbc8d8716e3422b828c4f90412fa63f9106bbd4","against":null,"payload":{"name":"clerk-custom-ui","description":"Custom authentication flows and component appearance - hooks (useSignIn, useSignUp), themes, colors, fonts, CSS. Use for custom sign-in/sign-up flows, appearance styling, visual customization, branding.","included_files":[{"relative_path":"core-2/custom-sign-in.md","size_in_bytes":5539},{"relative_path":"core-2/custom-sign-up.md","size_in_bytes":4688},{"relative_path":"core-3/custom-sign-in.md","size_in_bytes":9179},{"relative_path":"core-3/custom-sign-up.md","size_in_bytes":7728},{"relative_path":"core-3/show-component.md","size_in_bytes":3287}],"skill_md_contents":"---\nname: clerk-custom-ui\ndescription: Custom authentication flows and component appearance - hooks (useSignIn,\n  useSignUp), themes, colors, fonts, CSS. Use for custom sign-in/sign-up flows, appearance\n  styling, visual customization, branding.\nallowed-tools: WebFetch\nlicense: MIT\nmetadata:\n  author: clerk\n  version: 2.3.0\n---\n\n# Custom UI\n\n> **Prerequisite**: Ensure `ClerkProvider` wraps your app. See `clerk-setup` skill.\n>\n> **Version**: Check `package.json` for the SDK version — see `clerk` skill for the version table. This determines which custom flow references to use below.\n\nThis skill covers two areas:\n1. **Custom authentication flows** — build your own sign-in/sign-up UI with hooks\n2. **Appearance customization** — theme, style, and brand Clerk's pre-built components\n\n## What Do You Need?\n\n| Task | Reference |\n|------|-----------|\n| Custom sign-in (Core 2 / LTS) | core-2/custom-sign-in.md |\n| Custom sign-up (Core 2 / LTS) | core-2/custom-sign-up.md |\n| Custom sign-in (Current SDK v7+) | core-3/custom-sign-in.md |\n| Custom sign-up (Current SDK v7+) | core-3/custom-sign-up.md |\n| Show component pattern (Current SDK) | core-3/show-component.md |\n\n## Custom Flow References\n\n| Task | Core 2 | Current |\n|------|--------|---------|\n| Custom sign-in (useSignIn) | `core-2/custom-sign-in.md` | `core-3/custom-sign-in.md` |\n| Custom sign-up (useSignUp) | `core-2/custom-sign-up.md` | `core-3/custom-sign-up.md` |\n| `<Show>` component | *(use `<SignedIn>`, `<SignedOut>`, `<Protect>`)* | `core-3/show-component.md` |\n\n---\n\n## Appearance Customization\n\nAppearance customization applies to both Core 2 and the current SDK.\n\n### Component Customization Options\n\n| Task | Documentation |\n|------|---------------|\n| Appearance prop overview | https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/overview |\n| Options (structure, logo, buttons) | https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/layout |\n| Themes (pre-built dark/light) | https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/themes |\n| Variables (colors, fonts, spacing) | https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/variables |\n| CAPTCHA configuration | https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/captcha |\n| Bring your own CSS | https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/bring-your-own-css |\n\n### Appearance Pattern\n\n```typescript\n<SignIn\n  appearance={{\n    variables: {\n      colorPrimary: '#0000ff',\n      borderRadius: '0.5rem',\n    },\n    options: {\n      logoImageUrl: '/logo.png',\n      socialButtonsVariant: 'iconButton',\n    },\n  }}\n/>\n```\n\n> **Core 2 ONLY (skip if current SDK):** The `options` property was named `layout`. Use `layout: { logoImageUrl: '...', socialButtonsVariant: '...' }` instead of `options`.\n\n### variables (colors, typography, borders)\n\n| Property | Description |\n|----------|-------------|\n| `colorPrimary` | Primary color throughout |\n| `colorBackground` | Background color |\n| `borderRadius` | Border radius (default: `0.375rem`) |\n\n**Opacity change:** `colorRing` and `colorModalBackdrop` now render at full opacity. Use explicit `rgba()` values if you need transparency.\n\n> **Core 2 ONLY (skip if current SDK):** `colorRing` and `colorModalBackdrop` rendered at 15% opacity by default.\n\n### options (structure, logo, social buttons)\n\n| Property | Description |\n|----------|-------------|\n| `logoImageUrl` | URL to custom logo |\n| `socialButtonsVariant` | `'blockButton'` \\| `'iconButton'` \\| `'auto'` |\n| `socialButtonsPlacement` | `'top'` \\| `'bottom'` |\n| `showOptionalFields` | Show optional fields (default: `false`) |\n\n> **Core 2 ONLY (skip if current SDK):** This property is called `layout`, not `options`. Also, `showOptionalFields` defaulted to `true`.\n\n### Themes\n\nInstall themes from `@clerk/ui`:\n\n```bash\nnpm install @clerk/ui\n```\n\n```typescript\nimport { dark } from '@clerk/ui/themes'\n\n<ClerkProvider appearance={{ theme: dark }} />\n```\n\n> **Core 2 ONLY (skip if current SDK):** Themes are imported from `@clerk/themes` (install `@clerk/themes` instead of `@clerk/ui`). Example: `import { dark } from '@clerk/themes'`.\n\n**Theme stacking** — pass an array where the last theme takes precedence:\n\n```typescript\nimport { dark, neobrutalism } from '@clerk/ui/themes'\n\n<ClerkProvider appearance={{ theme: [dark, neobrutalism] }} />\n```\n\n**CSS `color-scheme` support** — the default theme respects the CSS `color-scheme` property for automatic light/dark mode toggling.\n\n**Available themes:** `dark`, `neobrutalism`, `shadcn`, `simple`\n\n#### shadcn Theme\n\n> **IMPORTANT:** If the project has `components.json` (shadcn/ui installed), ALWAYS apply the shadcn theme as the FIRST customization step. This ensures Clerk components visually match the existing shadcn design system. Skip this only if the user explicitly requests a different theme.\n\n**If the project uses shadcn/ui** (check for `components.json` in the project root), **always use the shadcn theme**:\n\n```typescript\nimport { shadcn } from '@clerk/ui/themes'\n\n<ClerkProvider appearance={{ theme: shadcn }} />\n```\n\nAlso import shadcn CSS in your global styles:\n```css\n@import 'tailwindcss';\n@import '@clerk/ui/themes/shadcn.css';\n```\n\n> **Core 2 ONLY (skip if current SDK):** Import from `@clerk/themes` and `@clerk/themes/shadcn.css`:\n> ```typescript\n> import { shadcn } from '@clerk/themes'\n> ```\n> ```css\n> @import '@clerk/themes/shadcn.css';\n> ```\n\n## Workflow\n\n1. Identify customization needs (custom flow or appearance)\n2. For custom flows: check SDK version → read appropriate `core-2/` or `core-3/` reference\n3. For appearance: WebFetch the appropriate documentation from table above\n4. Apply appearance prop to your Clerk components or build custom flow with hooks\n\n## Common Pitfalls\n\n| Issue | Solution |\n|-------|----------|\n| Colors not applying | Use `colorPrimary` not `primaryColor` |\n| Logo not showing | Put `logoImageUrl` inside `options: {}` (or `layout: {}` in Core 2) |\n| Social buttons wrong | Add `socialButtonsVariant: 'iconButton'` in `options` (or `layout` in Core 2) |\n| Styling not working | Use appearance prop, not direct CSS (unless with bring-your-own-css) |\n| Hook returns different shape | Check SDK version — Core 2 and current have completely different `useSignIn`/`useSignUp` APIs |\n\n## See Also\n\n- `clerk-setup` - Initial Clerk install\n- `clerk-nextjs-patterns` - Next.js patterns\n- `clerk-orgs` - B2B organizations\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}