---
name: create-element
description: |
  Create new UI elements for tryelements.dev registry. Use when: (1) Adding new UI components (buttons, inputs, cards), (2) Building integration components (Clerk, Stripe, Uploadthing), (3) Creating theme-related elements, (4) Any shadcn-style registry component. IMPORTANT: For logo components with variants (icon/wordmark/logo + dark/light), use the logo-with-variants skill instead. This skill includes scaffolding, registry schema, and component patterns. ALWAYS use Context7 MCP to fetch latest dependency docs before implementing.
---

# Create Element

Creates new elements for the Elements registry (tryelements.dev).

## Quick Start

```
Step 1: Scaffold
bun run .claude/skills/create-element/scripts/scaffold-element.ts <category> <name>

Step 2: Implement
Edit component following patterns in references/component-patterns.md

Step 3: Register
bun run build:registry && bun run dev
```

## Context7 Integration (CRITICAL)

**Before implementing any component with external dependencies**, fetch the latest documentation:

### Step 1: Resolve Library ID

```
mcp__context7__resolve-library-id
  libraryName: "radix-ui"
  query: "dialog component accessibility patterns"
```

### Step 2: Query Specific Docs

```
mcp__context7__query-docs
  libraryId: "/radix-ui/primitives"
  query: "Dialog API controlled vs uncontrolled portal usage"
```

### Common Libraries

| Library | Query For |
|---------|-----------|
| `radix-ui` | Primitives (Dialog, Dropdown, Tabs, Select) |
| `next-themes` | Theme provider, useTheme hook, hydration |
| `cmdk` | Command palette patterns |
| `class-variance-authority` | CVA variant patterns |
| `embla-carousel-react` | Carousel implementation |
| `lucide-react` | Icon usage patterns |

## Element Types

| Type | Example | When to Use |
|------|---------|-------------|
| `registry:ui` | button, card, input | Base UI primitives |
| `registry:block` | theme-switcher, polar-checkout | Feature-complete blocks |
| `registry:example` | button-demo | Usage examples |

## References

Read these based on what you're doing:

- **[references/registry-schema.md](references/registry-schema.md)** - When creating/editing registry-item.json
- **[references/component-patterns.md](references/component-patterns.md)** - When writing component code (CVA, cn(), data-slot)
- **[references/documentation.md](references/documentation.md)** - When creating MDX documentation

## Directory Structure

```
registry/default/blocks/{category}/{component-name}/
├── registry-item.json          # Metadata
├── components/
│   └── elements/
│       └── {component}.tsx     # Main component
└── routes/                     # Optional demo routes
    ├── layout.tsx
    └── page.tsx
```

## Workflow Example: Theme Switcher Tabs

### 1. Scaffold

```bash
bun run .claude/skills/create-element/scripts/scaffold-element.ts theme theme-switcher-tabs
```

### 2. Fetch Docs

```
mcp__context7__resolve-library-id
  libraryName: "next-themes"
  query: "useTheme hook theme switching"

mcp__context7__query-docs
  libraryId: "/pacocoursey/next-themes"
  query: "useTheme setTheme resolvedTheme hydration"
```

### 3. Implement

Edit `registry/default/blocks/theme/theme-switcher-tabs/components/elements/theme-switcher-tabs.tsx`:

```tsx
"use client";

import { useTheme } from "next-themes";
import { useEffect, useState } from "react";
import { cn } from "@/lib/utils";

export function ThemeSwitcherTabs({ className }: { className?: string }) {
  const { theme, setTheme } = useTheme();
  const [mounted, setMounted] = useState(false);

  useEffect(() => { setMounted(true); }, []);

  if (!mounted) return <div className="h-8 w-24 animate-pulse bg-muted rounded" />;

  return (
    <div data-slot="theme-switcher-tabs" className={cn("...", className)}>
      {/* Implementation */}
    </div>
  );
}
```

### 4. Update registry-item.json

```json
{
  "name": "theme-switcher-tabs",
  "type": "registry:ui",
  "title": "Theme Switcher Tabs",
  "description": "Tab-based theme switcher with Light/Dark/System options",
  "registryDependencies": [],
  "dependencies": ["next-themes"],
  "files": [...],
  "docs": "Requires ThemeProvider. Tab-style theme switcher with system support."
}
```

### 5. Build & Test

```bash
bun run build:registry
bun run dev
```

## Verification Checklist

- [ ] registry-item.json has all required fields ($schema, name, type, title, description, files)
- [ ] Component exports PascalCase function (e.g., `export function ThemeSwitcherTabs`)
- [ ] Uses `cn()` for className merging
- [ ] Has `data-slot` attribute on root element
- [ ] Client components have `"use client"` directive
- [ ] Hydration-safe if using theme/client state
- [ ] `bun run build:registry` succeeds
- [ ] Component renders correctly in dev
- [ ] **If new category**: Provider grouping configured (see "Creating New Categories" section)

## Commands

```bash
# Scaffold new element
bun run .claude/skills/create-element/scripts/scaffold-element.ts <category> <name>

# Build registry
bun run build:registry

# Development server
bun run dev

# Lint/format
bun run lint
bun run format
```

## Common Patterns

### Simple Component (No Dependencies)

```tsx
import { cn } from "@/lib/utils";

interface BadgeProps extends React.ComponentProps<"span"> {}

export function Badge({ className, ...props }: BadgeProps) {
  return (
    <span
      data-slot="badge"
      className={cn("inline-flex items-center rounded-full px-2.5 py-0.5 text-xs font-semibold", className)}
      {...props}
    />
  );
}
```

### With CVA Variants

```tsx
import { cva, type VariantProps } from "class-variance-authority";
import { cn } from "@/lib/utils";

const badgeVariants = cva("inline-flex items-center rounded-full px-2.5 py-0.5 text-xs font-semibold", {
  variants: {
    variant: {
      default: "bg-primary text-primary-foreground",
      secondary: "bg-secondary text-secondary-foreground",
      destructive: "bg-destructive text-white",
    },
  },
  defaultVariants: {
    variant: "default",
  },
});

interface BadgeProps extends React.ComponentProps<"span">, VariantProps<typeof badgeVariants> {}

export function Badge({ className, variant, ...props }: BadgeProps) {
  return (
    <span
      data-slot="badge"
      className={cn(badgeVariants({ variant, className }))}
      {...props}
    />
  );
}

export { badgeVariants };
```

### With External Dependency (Radix)

```tsx
"use client";

import * as DialogPrimitive from "@radix-ui/react-dialog";
import { cn } from "@/lib/utils";

export function Dialog({ children, ...props }: DialogPrimitive.DialogProps) {
  return <DialogPrimitive.Root {...props}>{children}</DialogPrimitive.Root>;
}

export function DialogTrigger({ className, ...props }: DialogPrimitive.DialogTriggerProps) {
  return <DialogPrimitive.Trigger data-slot="dialog-trigger" className={cn("", className)} {...props} />;
}
```

## Pitfalls to Avoid

- Don't forget `"use client"` for components using hooks
- Don't hardcode colors - use CSS variables (`text-foreground`, `bg-background`)
- Don't skip hydration handling for theme-dependent components
- Don't use `any` types - properly type props
- Don't forget to run `build:registry` after changes

## Creating New Categories (Provider Grouping)

When creating a **new category of components** (not just a new component in an existing category), you must configure the provider system for proper landing page display. Otherwise, each component will appear as a separate "Coming Soon" card.

### When This Applies

- Creating a new integration (e.g., `charts/`, `payments/`, `analytics/`)
- Adding multiple related components that should be grouped together
- The category doesn't exist in the current provider list

### Two-File Setup Required

#### 1. `src/lib/registry-loader.ts`

**Add grouping logic** in `getProviderFromName()` (~line 53):

```typescript
// Special case: chart components go to "charts" provider
if (
  name === "area-chart" ||
  name === "bar-chart-vertical" ||
  name === "heatmap-grid" ||
  name === "growth-stats"
) {
  return "charts";
}
```

**Add provider metadata** in `getProviderMetadata()` (~line 156):

```typescript
charts: {
  displayName: "Charts",
  description: "Data visualization primitives - area charts, heatmaps, bar charts",
  category: "DATA VIZ",
  brandColor: "#14B8A6",
},
```

#### 2. `src/lib/providers.tsx`

**Add provider config** in `providerConfig` (~line 46):

```typescript
charts: {
  isEnabled: true,
  displayName: "Charts",
  description: "Data visualization primitives - area charts, heatmaps, bar charts",
  category: "Data Viz",
},
```

**Add provider icon** in `ProviderIcon()` (~line 196):

```typescript
charts: <ChartIcon className="w-10 h-10" />,
```

Create the icon at `src/components/icons/{provider}.tsx` if needed.

### Provider Metadata Fields

| Field | Example | Purpose |
|-------|---------|---------|
| `displayName` | "Charts" | Landing page card title |
| `description` | "Data visualization..." | Card description |
| `category` | "DATA VIZ" | Badge shown on card |
| `brandColor` | "#14B8A6" | Diagonal hatch pattern color |

### Existing Providers (Reference)

| Provider Key | Display Name | Category |
|--------------|--------------|----------|
| `clerk` | Clerk | USER MGMT |
| `polar` | Polar | MONETIZATION |
| `theme` | Theme Switcher | UI |
| `logos` | Brand Logos | BRAND |
| `uploadthing` | UploadThing | FILES |
| `tinte` | Tinte | THEMING |
| `charts` | Charts | DATA VIZ |

### Naming Convention

The default extraction uses the first part before hyphen:
- `clerk-sign-in` → `clerk`
- `polar-checkout` → `polar`

Add special cases when:
- Components share a category but have different prefixes (e.g., `area-chart`, `heatmap-grid`)
- You want a custom provider name (e.g., `theme-switcher-*` → `theme`)

### MDX Documentation Setup

New categories also need MDX documentation files for the docs pages to render properly:

#### 1. Create Demo Components

For each component, create a demo in `/registry/default/examples/{component}-demo.tsx`:

```tsx
"use client";

import { MyComponent } from "@/registry/default/blocks/{category}/{component}/components/elements/{component}";

export default function MyComponentDemo() {
  return (
    <div className="flex items-center justify-center p-4">
      <MyComponent />
    </div>
  );
}
```

#### 2. Register in MDX Components

Add imports and mappings in `/src/mdx-components.tsx`:

```tsx
// Add import
import MyComponentDemo from "@/registry/default/examples/my-component-demo";

// Add to getMDXComponents return object
MyComponent: MyComponentDemo,
```

#### 3. Create Provider MDX

Create `/src/content/providers/{provider}.mdx`:

```mdx
---
title: My Provider
description: Description of the category
category: CATEGORY TAG
brandColor: "#hexcolor"
---

## Overview

Brief description.

## Components

### Component Name

<ComponentPreviewItem
  componentKey="component-name"
  installUrl="@elements/component-name"
  category="Category"
  name="Component Name"
>
  <ComponentName />
</ComponentPreviewItem>
```

#### 4. Create Component MDX Files

Create `/src/content/components/{provider}/{component}.mdx` for each component:

```mdx
---
title: Component Name
description: Brief description
---

<ComponentPreviewItem
  componentKey="component-name"
  installUrl="@elements/component-name"
  category="Category"
  name="Component Name"
>
  <ComponentName />
</ComponentPreviewItem>

## Overview

## Installation

## Usage

## Props

## Features
```