shadcn Web Components

Build web-specific UI components using shadcn MCP tools with custom pattern registries.

CRITICAL: Start Registry First

Before ANY component work, run:

shadcn-patterns

This starts the local @my-patterns registry at http://localhost:3000. Without it, custom pattern searches fail silently.

Registry Priority (Non-Negotiable)

Priority	Registry	Patterns	Reason
🥇 First	@my-patterns	1,105+	Project-specific, theme-integrated, WCAG compliant
🥈 Second	@reui	Professional	Rich variants, modern patterns
🥉 Third	@shadcn	Standard	Official fallback

Workflow

1. Search All Registries

mcp-cli call shadcn/search_items_in_registries '{"query": "button", "registries": ["@my-patterns", "@reui", "@shadcn"]}'

Always include all three registries. Never search only @shadcn.

2. Get Examples First

mcp-cli call shadcn/get_item_examples_from_registries '{"item": "@my-patterns/pattern-button-1", "includeCode": true}'

Review structure before installing. This prevents wasted installs.

3. Install Component

pnpm dlx shadcn@latest add @my-patterns/pattern-button-1

4. Verify Installation

mcp-cli call shadcn/get_audit_checklist '{"items": ["@my-patterns/pattern-button-1"]}'

Always run audit. Catches missing dependencies, import issues, TypeScript errors.

Quick Reference

Need	MCP Tool
Find components	shadcn/search_items_in_registries
View examples	shadcn/get_item_examples_from_registries
Get install command	shadcn/get_add_command_for_items
Verify install	shadcn/get_audit_checklist
List registries	shadcn/get_project_registries

Red Flags - STOP If You're Doing This

• Searching only @shadcn registry
• Installing without viewing examples
• Skipping audit checklist
• Not starting shadcn-patterns first
• Using Tamagui for web-only complex components

All of these mean: Start over, follow the workflow.

When to Use This vs Tamagui

Use shadcn MCP	Use Tamagui
Complex data tables	Simple cross-platform UI
Rich form components	Layout primitives (XStack/YStack)
Web-specific features	Mobile + web shared components
Advanced menus/dialogs	Basic buttons, cards

Troubleshooting

@my-patterns returns empty? → Run shadcn-patterns first, verify curl http://localhost:3000/r/pattern-button-1.json

Registry not in project? → Check components.json has registry configured

Related Docs

• Full workflow: .claude/references/shadcn-mcp/shadcn-mcp-workflow.md
• Pattern catalog (53 categories, 1,105 patterns): references/PATTERNS_GUIDE.md
• ReUI reference: docs/tools/shadcn-mcp/REUI_LLMS.txt