shadcn Components
Agent Workflow (MANDATORY)
Before component work, use TeamCreate to spawn agents:
-
fuse-ai-pilot:explore-codebase - Find existing components
-
fuse-ai-pilot:research-expert - Verify component APIs via Context7
-
mcp__shadcn__search_items_in_registries - Search available components
After: Run fuse-ai-pilot:sniper for validation.
Overview
Feature Description
Radix primitives Default shadcn/ui since 2021
Base UI primitives New option since late 2025
Component mapping 1:1 mapping between both
API differences asChild vs render, naming
Critical Rules
-
ALWAYS detect primitive before component work (shadcn-detection)
-
ALWAYS consult MCP before adding any component
-
NEVER mix Radix and Base UI APIs in same component
-
MATCH composition pattern to detected primitive
-
USE registry source as truth, not manual code
Architecture
components/ui/ ├── dialog.tsx # Adapted to detected primitive ├── select.tsx ├── accordion.tsx └── ...
-> See dialog-example.md for complete component
MCP Usage (MANDATORY)
ALWAYS consult shadcn MCP before adding components:
mcp__shadcn__search_items_in_registries -> find component mcp__shadcn__view_items_in_registries -> view source mcp__shadcn__get_add_command_for_items -> get install command
Component Mapping Table
Component Radix Part Base UI Part
Dialog DialogContent
Dialog.Popup
Dialog DialogOverlay
Dialog.Backdrop
Select SelectContent
Select.Positioner
- Select.Popup
Tooltip TooltipContent
Tooltip.Positioner
- Tooltip.Popup
Accordion AccordionContent
Accordion.Panel
Popover PopoverContent
Popover.Positioner
- Popover.Popup
Menu DropdownMenuContent
Menu.Positioner
- Menu.Popup
Composition Patterns
Radix: asChild
<Dialog.Trigger asChild> <Button variant="outline">Open</Button> </Dialog.Trigger>
Base UI: render
<Dialog.Trigger render={<Button variant="outline" />}> Open </Dialog.Trigger>
Reference Guide
Concepts
Topic Reference When to Consult
Radix APIs radix-components.md Building with Radix primitives
Base UI APIs baseui-components.md Building with Base UI primitives
Templates
Template When to Use
dialog-example.md Creating Dialog components
Best Practices
DO
-
Detect primitive FIRST (use shadcn-detection)
-
Consult MCP for component source before editing
-
Follow existing naming conventions in project
-
Use correct composition pattern for detected primitive
DON'T
-
Mix asChild and render in same component
-
Assume Radix without detection
-
Manually write component internals (use MCP)
-
Skip registry check before adding new components