refactoring-ui

name

refactoring-ui

description

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.

Refactoring UI with Tailwind + shadcn/ui

Apply professional design principles using Tailwind's design system and shadcn/ui components.

Core Principles

1. Start with functionality, not chrome - Design the feature first, not the shell
2. Work in grayscale first - Add color only after hierarchy is established
3. Use existing systems - Tailwind scale + shadcn components, don't reinvent
4. 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="[e-mail]" />
  </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)