Contributing

This guide explains how to contribute new components to the Redpanda UI Registry whether you're a UX Engineer or Designer.

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:

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

Add Tweakpane (Optional)

You can add a Tweakpane allowing users to play with your demo props:

Number Props:

// Simple number input
"myNumber": { "value": 10 }

// Slider
"myNumber": { "value": 10, "min": 0, "max": 100, "step": 1 }

// Select dropdown
"mySize": {
  "value": 10,
  "options": {
    "Big": 30,
    "Medium": 20,
    "Small": 10
  }
}

String Props:

// Simple text input
"myString": { "value": "Hello World" }

// Select dropdown
"myVariant": {
  "value": "small",
  "options": {
    "Big": "big",
    "Medium": "medium", 
    "Small": "small"
  }
}

Boolean Props:

"myBoolean": { "value": true }

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:

---
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" />

## Installation

<ComponentInstallation name="my-component" />

## Usage

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

<MyComponent>
  Content goes here
</MyComponent>

4. Build and Verify

Run the following commands to build and verify your component:

# 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:

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:

# 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 do this locally by running bun x --bun @fumadocs/cli add --dir <your-box>/ui-registry/packages/docs/public/r <component-name>)
3. Ensure documentation renders properly with <ComponentPreview />
4. Run all build commands to verify automation works:

   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. To update the changelog, use the changelog-generator agent.

# Ask Claude Code to run the changelog-generator agent
"Please run the changelog-generator agent to update the 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

# Preview your changes locally
bun run dev # runs the component playground at localhost:3001

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:3001/button
4. Share your changes with the UX Team and we'll help you get it implemented