Contributing

Learn how to add new components to the Redpanda UI Registry.

Installation

bash

npx shadcn@latest add @redpanda/my-component

bash

pnpm dlx shadcn@latest add @redpanda/my-component

bash

yarn dlx shadcn@latest add @redpanda/my-component

bash

bunx shadcn@latest add @redpanda/my-component

bash

nubx shadcn@latest add @redpanda/my-component

bash

aube dlx 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.

Quick Start with Claude Code

The fastest way to contribute is with Claude 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.

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:

plaintext

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" suffixexport function MyComponentDemo() {  return (    <div className="flex items-center justify-center p-4">      <MyComponent>Example usage</MyComponent>    </div>  );}

Demo Directory Structure:

plaintext

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 Componentdescription: Brief description of what the component does.icon: Squareauthor:  name: Your Name  url: https://github.com/yourusername---
<ComponentPreview name="my-component-demo" />
## Usage
```tsximport { 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 checkbun run type:check
# Formatbun run format
# Lintbun run lint
# Build registrybun run registry:build # this ensures your component source code is exposed whenever anyone installs the registry package
# Build projectbun 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:

Verify component renders correctly in the demo (run bun run dev to see your component in the playground and docs site)
Test installation via CLI (you can test locally by pointing a consumer project at your local registry output)
Ensure documentation renders properly with <ComponentPreview />

Run all build commands to verify automation works:

bash

bun run format # Formats the codebun run lint # Lints the codebun run type:check  # Validates TypeScriptbun run build  # Tests navigation auto-generation and routing

Test in both light and dark themes
Run the registry-component-validator agent to catch integration issues early
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 and v0 to rapidly prototype UIs and iterate on visual designs with real component examples
Follow the instructions in MCP to get setup with the UI Registry inside of Builder.io

Theme Customization

Use TweakCN 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 locallybun run dev # runs the component playground at localhost:4001

Example: Customizing Button Variants

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