Refactoring Ui

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](references/shadcn.md) - Component patterns, composition, customization
• [hierarchy.md](references/hierarchy.md) - Visual hierarchy, emphasis, contrast
• [spacing.md](references/spacing.md) - Layout, whitespace, sizing
• [typography.md](references/typography.md) - Type scales, fonts, line-height
• [color.md](references/color.md) - Palettes, shades, accessibility
• [depth.md](references/depth.md) - Shadows, elevation, layering
• [polish.md](references/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
Save Changes

// Secondary: clear but not dominant
Cancel

// Outline: lighter touch
Edit

// Ghost: minimal, for toolbars/nav
Settings

// Destructive: dangerous actions (use sparingly)
Delete

// Link: text-only navigation
Learn more

Common Patterns

Card with Hierarchy

  
    Account Settings
    Manage your account preferences.
  
  
    {/* Form fields */}
  
  
    Cancel
    Save
  

Form with Labels

  
    Email
    
  
  
    Password
    
  

Alert Messages

  
  Note
  Your session will expire in 5 minutes.

  
  Error
  Failed to save changes.

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)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: opkod-france
• Source: opkod-france/claude-skill-refactoring-ui
• License: MIT

Install and usage instructions live in the source repository linked above.