---
title: Contributing
description: Learn how to add new components to the Redpanda UI Registry.
icon: construction
---

### Installation

```package-install
npx shadcn@latest add @redpanda/my-component
```

This guide explains how to contribute new components to the Redpanda UI Registry whether you're a UX Engineer or [Designer](#designer).

## Quick Start with Claude Code

The fastest way to contribute is with [Claude Code](https://claude.ai/code) slash commands. Open a terminal in the `ui-registry` repo and type any of these:

| Command      | What it does                                                                                                                      | When to use it                                                                               |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `/new-comp`  | Built a new component? Edited an existing one? Let Claude handle the rest. Adds: demos, playground route, and docs — all wired up | You're adding a brand new component or made a change to turn it into a ui-registry component |
| `/upstream`  | Pulls changes from Console or CloudV2 back into the registry                                                                      | You fixed or improved a component in a consumer app and want to share it                     |
| `/changelog` | Writes a changelog entry based on your git diff                                                                                   | You're done making changes and need to document them                                         |

Each command walks you through the process step by step — just follow the prompts. No design system experience required.

:::info
Don't have Claude Code yet? Run `npm i -g @anthropic-ai/claude-code` and then `claude` in the repo root. That's it.
:::

## Edit an Existing Component

If modifying a component to correct or improve it:

- Add a screenshot (photo or video) showing before and after the modification
- Clearly explain why you made the modification
- Update the demo and documentation if necessary
- Don't change behavior completely unless there's a good reason

## Adding a New Component

Follow these steps to add a new component to the registry:

### 1. Create the Component

Create your component in `/packages/registry/src/components/<component-name>/` with the following files:

- `index.tsx` - The main component implementation

**Example structure:**

```
packages/registry/src/
  components/
    my-component/
      index.tsx
```

**Best Practices:**

- Reuse existing registry components when possible
- Minimize external dependencies
- Follow Tailwind CSS conventions for styling
- Implement proper forwarding of refs and props where applicable
- Create multiple variants and states for each component
- Ensure accessibility and responsive behavior
- Expose a `className` prop for styling

### 2. Create Component Demo

You can continue to implement everything manually, or use the new claude code slash command `/new-comp` to create the component, demos, playground routes, and documentation for you.

**IMPORTANT: Each demo MUST be in its own directory with an `index.tsx` file.**

Add a demo showcasing your component in `/packages/registry/src/demo/<component-name>/index.tsx`:

```tsx
import { MyComponent } from '@/components/my-component';

// Export with PascalCase name matching directory + "Demo" suffix
export function MyComponentDemo() {
  return (
    <div className="flex items-center justify-center p-4">
      <MyComponent>Example usage</MyComponent>
    </div>
  );
}
```

**Demo Directory Structure:**

```
packages/registry/src/demo/
  my-component/
    index.tsx          → exports MyComponentDemo
  my-component-variant/
    index.tsx          → exports MyComponentVariantDemo
  my-component-large/
    index.tsx          → exports MyComponentLargeDemo
```

**Critical Rules:**

- **ONE demo per directory** - Never export multiple demos from the same file
- Each directory must have its own `index.tsx` file
- Each `index.tsx` exports exactly ONE demo component
- The export name must match: `component-name` → `ComponentNameDemo`

**Best Practices:**

- Create realistic demo implementations showing real-world usage
- Build interactive examples that developers can copy-paste

Always make sure to export as a module!

**Export Requirements:**

- Module export must follow PascalCase + "Demo" pattern (e.g., `ComponentDemo`)
- Directory `component` → Export `ComponentDemo`
- For variants: Directory `component-variant` → Export `ComponentVariantDemo`
- Each variant gets its own directory: `button-destructive/index.tsx` → `ButtonDestructiveDemo`

### 3. Add Documentation

**Best Practices:**

- Use the same format as existing components (for example copy from `card.mdx`)
- Document component APIs, props, and usage patterns
- Include clear usage examples
- Provide multiple demo variations when relevant
- Document all props and customization options

Create a documentation file at `/packages/docs/content/docs/<component-name>.mdx`:

````mdx
---
title: My Component
description: Brief description of what the component does.
icon: Square
author:
  name: Your Name
  url: https://github.com/yourusername
---

<ComponentPreview name="my-component-demo" />

## Usage

```tsx
import { MyComponent } from '@/components/ui/my-component';
```
````

```tsx
<MyComponent>Content goes here</MyComponent>
```

### 4. Build and Verify

Run the following commands to build and verify your component:

```bash
# Type check
bun run type:check

# Format
bun run format

# Lint
bun run lint

# Build registry
bun run registry:build # this ensures your component source code is exposed whenever anyone installs the registry package

# Build project
bun run build # automatically generates docs navigation, playground routes, and component discovery
```

### 5. Add Playground Route (Optional)

The playground **automatically discovers and routes all components**, but you can create a custom route for enhanced visual regression testing in `/packages/playground/src/routes/demo/<component-name>.tsx`:

```tsx
import { MyComponentDemo } from '@redpanda/registry/demo/my-component';
import PageHeader, { ComponentCard, PageGrid } from '@/components/component-preview';

export const myComponentComponents = [
  { name: 'my-component', meta: { style: 1 } },
  // Add variants here if needed
];

const myComponentVariants = [<MyComponentDemo key="my-component" />];

export default function MyComponentPage() {
  return (
    <div className="min-h-screen bg-background p-8">
      <PageHeader title="My Component">Brief description of the component.</PageHeader>
      <PageGrid>
        {myComponentComponents.map((component, index) => (
          <ComponentCard key={component.name} component={component}>
            {myComponentVariants[index]}
          </ComponentCard>
        ))}
      </PageGrid>
    </div>
  );
}
```

The component array export pattern ensures our visual regression script picks it up at build time.

### 6. Validate Component Integration

Use the **registry-component-validator** agent to ensure your component is properly integrated across all packages:

```bash
# Ask Claude Code to run the validator
"Please run the registry-component-validator agent to check my new component"
```

The validator will:

- ✅ Verify your component exports work with dynamic loading
- ✅ Check MDX files use proper `<ComponentPreview name="..." />` syntax
- ✅ Validate cross-package consistency (registry, docs, playground)
- ✅ Ensure proper naming conventions and file structure
- ✅ Ensure playground routes exist for visual regression testing
- ✅ Generate a comprehensive validation report

## Testing Your Component

Before submitting:

1. **Verify component renders correctly** in the demo (run `bun run dev` to see your component in the playground and docs site)
2. **Test installation via CLI** (you can test locally by pointing a consumer project at your local registry output)
3. **Ensure documentation renders properly** with `<ComponentPreview />`
4. **Run all build commands** to verify automation works:
   ```bash
   bun run format # Formats the code
   bun run lint # Lints the code
   bun run type:check  # Validates TypeScript
   bun run build  # Tests navigation auto-generation and routing
   ```
5. **Test in both light and dark themes**
6. **Run the registry-component-validator agent** to catch integration issues early
7. **Request UX Team for review** - request a review from the UX Team to ensure the component is properly integrated into the Redpanda UI

## Update the Changelog

Since this is not a package, rather a registry, we don't have versioning, but we do have a changelog. Run the `/changelog` slash command in Claude Code to generate an entry automatically:

```bash
/changelog
```

This will analyze the git diff and update the changelog accordingly.

## Designer

As a **Designer**, you focus on visual consistency, user experience, and design system evolution.

Why designers should learn shadcn?

1️⃣ AI speaks shadcn - ChatGPT, Claude, Cursor, v0, Figma Make... they all generate shadcn/ui by default. Your AI-assisted prototypes will use it anyway. Designing in shadcn = better results and consistency.

2️⃣ Bridge the gap - Speak the same language as your devs AND your AI assistant. Modern workflow: Design → AI generates shadcn → Dev tweaks → Ship. Know the pipeline.

3️⃣ Tailwind mastery - Learn the utility-first CSS that AI loves. Your design tokens = Tailwind classes = AI's vocabulary.

4️⃣ Prompt like a pro:
Vague: "Create a nice looking card for user profiles"
Specific: "Create a shadcn/ui Card component with: Avatar on the left using shadcn Avatar component, User name as CardTitle, Bio as CardDescription, Tailwind classes for hover state with scale-105 transform"

5️⃣ Design with real constraints - Don't reinvent the wheel. Build prototypes using actual production components. What you design = what ships.

6️⃣ Future-proof yourself - As AI tools evolve, they're standardizing on shadcn/ui patterns. Stay ahead of the curve.

### Tools You Can Use

**Visual Prototyping & Iteration**

- We use [builder.io](https://builder.io/) and [v0](https://v0.dev) to rapidly prototype UIs and iterate on visual designs with real component examples
- Follow the instructions in [MCP](/docs/mcp) to get setup with the UI Registry inside of Builder.io

**Theme Customization**

- Use [TweakCN](https://tweakcn.com) to visually adjust Tailwind CSS variables
- Preview changes across light/dark modes instantly

**Design System Evolution**

- Suggest new component variants by modifying existing examples
- Propose color palette adjustments through CSS variable changes
- Create visual specifications for new components needed by the team

### Local Development

```bash
# Preview your changes locally
bun run dev # runs the component playground at localhost:4001
```

**Example: Customizing Button Variants**

1. Find the button component at `/packages/registry/src/components/button/`
2. Modify the variant styles or add new ones
3. Test in the browser at `localhost:4001/button`
4. Share your changes with the UX Team and we'll help you get it implemented