shadcn/ui Patterns

tech-specific ~629 tokens updated 2026-08-04

shadcn/ui component patterns: composition over custom builds, semantic theming tokens, proper form architecture, accessibility, and CLI workflow.

Tags

  • shadcn
  • ui
  • components
  • react
  • radix

README

shadcn

shadcn/ui component patterns and best practices.

What It Does

Installs a rules file covering shadcn/ui workflows:

  • Composition over custom - Search the registry before building, combine existing components
  • Semantic theming - Use theme tokens (bg-primary) not raw colors (bg-blue-500)
  • Component patterns - Forms with FieldGroup/Field, flex with gap, icon handling, overlay accessibility
  • CLI workflow - info, docs, add with --dry-run --diff, preset switching
  • Conventions - cn() for class merging, no manual z-index, components in ui/ directory

Manual Installation

# Global (all projects)
mkdir -p ~/.claude/rules
cp rules/shadcn.md ~/.claude/rules/shadcn.md

# Project-level
mkdir -p .claude/rules
cp rules/shadcn.md .claude/rules/shadcn.md

Files

File Description
rules/shadcn.md shadcn/ui patterns covering composition, theming, forms, and workflow

Will install

Path Action Target Type
rules/shadcn.md → rules/shadcn.md rule

Dependencies

No dependencies.

Required by

No other module depends on this one.

Included in presets

Install this module

Agent prompt

Recommended for agent users -- hands the whole install off to your assistant.

Fetch https://cd23a9be.ccgm-site.pages.dev/modules/shadcn.md and install this module into my Claude Code setup.

Native plugin marketplace

One command via the native plugin marketplace -- additive, does not merge settings.json.

claude plugin install shadcn@ccgm

The marketplace path is additive, not a replacement: it installs commands, agents, and skills as native plugin components, but it does not perform the bash installer's deep settings.json merge, and it does not write the always-loaded global CLAUDE.md context. Rules are only injected via an opt-in SessionStart hook rather than being auto-loaded. Use the bash installer when those pieces matter to you.

Manual, per file

Full control -- copy exactly the files you want from the sections below.

Files

Files

rule (1)

rules/shadcn.md

# shadcn/ui Patterns

Guidelines for working with shadcn/ui components in React projects.

## Core Approach

### Composition Over Custom

Always search the shadcn registry before building custom components.

```bash
# Check project context
npx shadcn@latest info --json

# Search for existing components
npx shadcn@latest docs <component>

# Preview before installing
npx shadcn@latest add <component> --dry-run --diff
```

Combine existing components rather than building from scratch. A settings page combines Tabs, Card, and form controls. A data view combines Table, Pagination, and Dialog.

### Semantic Theming

Use theme tokens, not raw color values:

- `bg-primary`, `text-primary-foreground` - not `bg-blue-500`, `text-white`
- `bg-muted`, `text-muted-foreground` - not `bg-gray-100`, `text-gray-500`
- `bg-destructive`, `text-destructive-foreground` - not `bg-red-500`, `text-white`

Never hardcode colors. Never add manual `dark:` overrides - the theme system handles this.

## Component Patterns

### Forms

Use FieldGroup + Field containers with proper semantic structure:

- Wire up `aria-invalid` and `aria-describedby` for validation states
- Use `data-invalid` attributes for styling error states
- Pair every input with a Label component

### Layout

- Use `flex` with `gap-*` instead of `space-x-*` or `space-y-*`
- Use `size-*` shorthand instead of separate `w-*` and `h-*` when equal
- Use `cn()` utility for conditional class merging

### Icons in Buttons

Use `data-icon` attributes on icons inside buttons. Do not add sizing classes to icons directly - let the button component manage icon sizing.

### Overlays (Dialog, Sheet, Drawer)

- Always include a Title element for accessibility
- Use `className="sr-only"` to visually hide the title when not needed
- Never manually set z-index on overlay components

## Workflow

### Adding Components

1. Search the registry first
2. Preview with `--dry-run --diff`
3. Install the component
4. Customize by editing the installed source (these are your files, not a dependency)

### Switching Presets/Themes

Three approaches when changing visual presets:

- **Reinstall**: Overwrites component files (clean but loses customizations)
- **Merge**: Intelligently updates (preserves customizations)
- **Skip**: Keep current version

### Conventions

- Never decode preset codes manually
- Never manually set z-index on overlay components
- Use `cn()` for all conditional class composition
- Keep component source files in `components/ui/` directory

View source on GitHub