MCP

---
name: Redpanda UI Registry
when: Whenever a user wants to build a UI or requests code examples or documentation for the Redpanda UI Registry (or design system or UI library)
---
# UI Development Guide

This document provides agent-optimized instructions for building user interfaces in this repository.

## Activation Conditions

Apply these instructions when the user request includes ANY of:
- Building/creating/implementing UI components or pages
- Keywords: "design system", "ui", "frontend", "registry", "component"
- Requesting code examples or documentation for UI components
- Modifying existing UI that uses registry components

## Critical Rules

### ALWAYS
- Use Redpanda UI Registry components from `./src/components/redpanda-ui` (check `components.json` for exact path)
- Use the shadcn MCP server to browse `@redpanda` registry components BEFORE writing UI code
- Use functional React components (never class-based)
- Install components using the shadcn CLI from registry documentation
- Create unit tests following this repository's testing patterns
- Use TypeScript with strict typing (infer types, never use `any`)

### NEVER
- Use `@redpanda-data/ui` library (deprecated)
- Modify files in the registry base directory (specified in `components.json` aliases)
- Copy/paste registry source code (always install via CLI)
- Install external UI libraries (unless explicitly requested by user)
- Use inline `style` prop on registry components
- Add `className` margins directly to registry components
- Leave `console.log` or TODO comments in production code

## Workflow

### 1. Fetch Documentation
```
REQUIRED FIRST STEP: Use the shadcn MCP server
- Browse @redpanda registry components for available components
- Use `bunx shadcn@latest docs @redpanda/<component>` to get component docs
- Use `bunx shadcn@latest view @redpanda/<component>` to preview code
```

### 2. Component Planning
- Identify required registry components from documentation
- Check if components already exist in `./src/components/redpanda-ui`
- Plan component composition and data flow

### 3. Install Components
```bash
# Single component
bunx shadcn@latest add @redpanda/<component-name>

# Multiple components (space-separated)
bunx shadcn@latest add @redpanda/card @redpanda/accordion @redpanda/calendar
```

**If CLI fails to install dependencies:**
- Manually install missing dependencies
- Check registry documentation for dependency list

### 4. Write Component Code

Apply these standards:

**Component Structure:**
- Use functional components with hooks
- Export named components (not default exports unless required)
- Use `ref` as a prop for ref forwarding (React 19+ pattern, not `forwardRef`)
- Prefer fragments over unnecessary wrapper divs

**TypeScript:**
- Define explicit prop interfaces
- Infer return types (don't annotate unnecessarily)
- Use proper generic types for collections
- Never cast to `any` - deduce correct types

**Styling:**
- Use Tailwind utility classes via `className`
- Leverage registry component variants and props (not custom `className` overrides)
- Wrap registry components in divs for spacing (don't add margin classes directly)
- Ensure responsive design with Tailwind breakpoints

**Performance:**
- Hoist static content outside component body
- Use `useMemo` for expensive computations
- Wrap components receiving props with `memo` when appropriate
- Avoid unnecessary re-renders

**Accessibility:**
- Include proper ARIA labels and roles
- Ensure keyboard navigation support
- Use semantic HTML elements
- Test with screen reader considerations

### 5. Create Tests
- Follow repository's testing patterns (check `vitest.config.*.mts`)
- Test component rendering and user interactions
- Mock API calls and external dependencies
- Achieve meaningful coverage of business logic

### 6. Validation Checklist

Run these commands in order:

```bash
# 1. Type checking
bun run type:check

# 2. Run tests
bun run test

# 3. Lint code
bun run lint

# 4. Build application
bun run build

# 5. Start dev server (check for runtime errors)
bun run start
```

**Success Criteria:**
- All TypeScript errors resolved
- All tests passing
- No lint errors
- Build completes without errors
- Dev server runs without console errors
- UI renders correctly in browser

### 7. End-to-End Tests (Optional)
If repository has Playwright installed:
- Ask user if they want E2E tests created
- Follow repository's E2E testing patterns

## Component Development Patterns

### Reusable Sub-Components
When logic or UI repeats within a feature:
- Create sub-components in the same file
- Keep related code colocated
- Use composition over prop drilling

### Example Structure
```typescript
// Main feature component
export function FeatureComponent() {
  return (
    <div>
      <FeatureHeader />
      <FeatureContent />
      <FeatureActions />
    </div>
  );
}

// Colocated sub-components
function FeatureHeader() { /* ... */ }
function FeatureContent() { /* ... */ }
function FeatureActions() { /* ... */ }
```

### Registry Component Usage
```typescript
// CORRECT: Use variants and component props
<Button variant="primary" size="lg">
  Click Me
</Button>

// WRONG: Custom className overrides
<Button className="bg-blue-500 px-8">
  Click Me
</Button>

// CORRECT: Wrap for spacing
<div className="mt-4">
  <Button variant="primary">Click Me</Button>
</div>

// WRONG: Direct margin on component
<Button className="mt-4" variant="primary">
  Click Me
</Button>
```

## Quick Reference

### When to Install from Registry
- User needs a button, form, card, dialog, etc.
- User asks about UI/design system capabilities
- Building new feature with visual components

### When to Check Existing Components
- Before installing, check `./src/components/redpanda-ui`
- Review `components.json` for configured registries
- Search codebase for similar patterns

### Multi-Component Installation Pattern
```bash
bunx shadcn@latest add @redpanda/button @redpanda/card @redpanda/dialog @redpanda/form @redpanda/input
```

### Testing Command Reference
```bash
bun run test          # All tests
bun run test:unit     # Unit tests only
bun run test:integration  # Integration tests only
bun run test:watch    # Watch mode with UI
bun run test:coverage # Coverage report
```