Refactoring UI with Tailwind + shadcn/ui
Apply professional design principles using Tailwind's design system and shadcn/ui components.
Core Principles
- Start with functionality, not chrome - Design the feature first, not the shell
- Work in grayscale first - Add color only after hierarchy is established
- Use existing systems - Tailwind scale + shadcn components, don't reinvent
- Hierarchy is everything - Not all elements deserve equal emphasis
Topic References
- shadcn.md - Component patterns, composition, customization
- hierarchy.md - Visual hierarchy, emphasis, contrast
- spacing.md - Layout, whitespace, sizing
- typography.md - Type scales, fonts, line-height
- color.md - Palettes, shades, accessibility
- depth.md - Shadows, elevation, layering
- polish.md - Finishing touches, borders, backgrounds
Quick Start with shadcn/ui
Installation (Next.js)
npx shadcn@latest init
npx shadcn@latest add button card input label
Core Components to Know
| Component |
Use for |
Button |
Actions with built-in variants (default, secondary, outline, ghost, destructive) |
Card |
Content containers with header, content, footer |
Input + Label |
Form fields with consistent styling |
Dialog |
Modals with accessible focus management |
DropdownMenu |
Actions menus with keyboard navigation |
Select |
Styled native-like selects |
Tabs |
Content organization |
Badge |
Status indicators, counts |
Alert |
Feedback messages |
Skeleton |
Loading states |
Button Hierarchy (shadcn)
// Primary: one per section max
<Button>Save Changes</Button>
// Secondary: clear but not dominant
<Button variant="secondary">Cancel</Button>
// Outline: lighter touch
<Button variant="outline">Edit</Button>
// Ghost: minimal, for toolbars/nav
<Button variant="ghost">Settings</Button>
// Destructive: dangerous actions (use sparingly)
<Button variant="destructive">Delete</Button>
// Link: text-only navigation
<Button variant="link">Learn more</Button>
Common Patterns
Card with Hierarchy
<Card>
<CardHeader>
<CardTitle>Account Settings</CardTitle>
<CardDescription>Manage your account preferences.</CardDescription>
</CardHeader>
<CardContent className="space-y-4">
{/* Form fields */}
</CardContent>
<CardFooter className="flex justify-end gap-2">
<Button variant="outline">Cancel</Button>
<Button>Save</Button>
</CardFooter>
</Card>
Form with Labels
<div className="space-y-4">
<div className="space-y-2">
<Label htmlFor="email">Email</Label>
<Input id="email" type="email" placeholder="you@example.com" />
</div>
<div className="space-y-2">
<Label htmlFor="password">Password</Label>
<Input id="password" type="password" />
</div>
</div>
Alert Messages
<Alert>
<InfoIcon className="h-4 w-4" />
<AlertTitle>Note</AlertTitle>
<AlertDescription>Your session will expire in 5 minutes.</AlertDescription>
</Alert>
<Alert variant="destructive">
<AlertCircle className="h-4 w-4" />
<AlertTitle>Error</AlertTitle>
<AlertDescription>Failed to save changes.</AlertDescription>
</Alert>
Anti-Patterns
- ❌ Multiple primary buttons in one view
- ❌
variant="destructive" for non-destructive actions
- ❌ Skipping
Label components (accessibility)
- ❌ Overriding shadcn styles instead of using variants
- ❌ Not using
space-y-* or gap-* for consistent spacing
- ❌ Arbitrary Tailwind values like
w-[423px] (use scale)
- ❌ Grey text on colored backgrounds (use same-hue shades)
1---2name: refactoring-ui3description: Professional UI design principles using Tailwind CSS and shadcn/ui. Use this skill when creating web interfaces, React components, HTML layouts, landing pages, dashboards, or any visual UI work. Applies Refactoring UI principles via Tailwind utilities and shadcn components for polished, professional designs. Triggers when building UI components, styling interfaces, creating layouts, designing forms, or when user wants something to look better or more professional.4---56# Refactoring UI with Tailwind + shadcn/ui78Apply professional design principles using Tailwind's design system and shadcn/ui components.910## Core Principles11121. **Start with functionality, not chrome** - Design the feature first, not the shell132. **Work in grayscale first** - Add color only after hierarchy is established143. **Use existing systems** - Tailwind scale + shadcn components, don't reinvent154. **Hierarchy is everything** - Not all elements deserve equal emphasis1617## Topic References1819- **[shadcn.md](references/shadcn.md)** - Component patterns, composition, customization20- **[hierarchy.md](references/hierarchy.md)** - Visual hierarchy, emphasis, contrast21- **[spacing.md](references/spacing.md)** - Layout, whitespace, sizing22- **[typography.md](references/typography.md)** - Type scales, fonts, line-height23- **[color.md](references/color.md)** - Palettes, shades, accessibility24- **[depth.md](references/depth.md)** - Shadows, elevation, layering25- **[polish.md](references/polish.md)** - Finishing touches, borders, backgrounds2627## Quick Start with shadcn/ui2829### Installation (Next.js)30```bash31npx shadcn@latest init32npx shadcn@latest add button card input label33```3435### Core Components to Know3637| Component | Use for |38|-----------|---------|39| `Button` | Actions with built-in variants (default, secondary, outline, ghost, destructive) |40| `Card` | Content containers with header, content, footer |41| `Input` + `Label` | Form fields with consistent styling |42| `Dialog` | Modals with accessible focus management |43| `DropdownMenu` | Actions menus with keyboard navigation |44| `Select` | Styled native-like selects |45| `Tabs` | Content organization |46| `Badge` | Status indicators, counts |47| `Alert` | Feedback messages |48| `Skeleton` | Loading states |4950## Button Hierarchy (shadcn)5152```tsx53// Primary: one per section max54<Button>Save Changes</Button>5556// Secondary: clear but not dominant57<Button variant="secondary">Cancel</Button>5859// Outline: lighter touch60<Button variant="outline">Edit</Button>6162// Ghost: minimal, for toolbars/nav63<Button variant="ghost">Settings</Button>6465// Destructive: dangerous actions (use sparingly)66<Button variant="destructive">Delete</Button>6768// Link: text-only navigation69<Button variant="link">Learn more</Button>70```7172## Common Patterns7374### Card with Hierarchy75```tsx76<Card>77 <CardHeader>78 <CardTitle>Account Settings</CardTitle>79 <CardDescription>Manage your account preferences.</CardDescription>80 </CardHeader>81 <CardContent className="space-y-4">82 {/* Form fields */}83 </CardContent>84 <CardFooter className="flex justify-end gap-2">85 <Button variant="outline">Cancel</Button>86 <Button>Save</Button>87 </CardFooter>88</Card>89```9091### Form with Labels92```tsx93<div className="space-y-4">94 <div className="space-y-2">95 <Label htmlFor="email">Email</Label>96 <Input id="email" type="email" placeholder="you@example.com" />97 </div>98 <div className="space-y-2">99 <Label htmlFor="password">Password</Label>100 <Input id="password" type="password" />101 </div>102</div>103```104105### Alert Messages106```tsx107<Alert>108 <InfoIcon className="h-4 w-4" />109 <AlertTitle>Note</AlertTitle>110 <AlertDescription>Your session will expire in 5 minutes.</AlertDescription>111</Alert>112113<Alert variant="destructive">114 <AlertCircle className="h-4 w-4" />115 <AlertTitle>Error</AlertTitle>116 <AlertDescription>Failed to save changes.</AlertDescription>117</Alert>118```119120## Anti-Patterns121122- ❌ Multiple primary buttons in one view123- ❌ `variant="destructive"` for non-destructive actions124- ❌ Skipping `Label` components (accessibility)125- ❌ Overriding shadcn styles instead of using variants126- ❌ Not using `space-y-*` or `gap-*` for consistent spacing127- ❌ Arbitrary Tailwind values like `w-[423px]` (use scale)128- ❌ Grey text on colored backgrounds (use same-hue shades)
opkod-france