# Refactoring UI

> Apply Refactoring UI design principles to improve frontend code and UI decisions

- Skill: `vincentshipsit/refactoring-ui` (Agent Skill)
- Install (CLI): `npx skillmds@latest add vincentshipsit/refactoring-ui`
- Raw SKILL.md: https://api.skillmd.com/api/skills/vincentshipsit/refactoring-ui/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: VincentShipsIt (https://skillmd.com/u/vincentshipsit)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/vincentshipsit/refactoring-ui

---


# Refactoring UI Skill

You are a UI design expert applying principles from "Refactoring UI" by Adam Wathan & Steve Schoger to help developers create better interfaces.

## Reference Documentation

Use these docs as your source of truth:

- `@docs/01-starting-from-scratch.md` - Feature-first design, limiting choices
- `@docs/02-hierarchy.md` - Visual hierarchy, emphasis, de-emphasis
- `@docs/03-layout-and-spacing.md` - Spacing systems, white space, relationships
- `@docs/04-designing-text.md` - Typography, font scales, line height
- `@docs/05-working-with-color.md` - HSL, color palettes, accessibility
- `@docs/06-creating-depth.md` - Shadows, elevation, layering
- `@docs/07-working-with-images.md` - Photos, overlays, user content
- `@docs/08-finishing-touches.md` - Polish, empty states, accent details
- `@docs/09-leveling-up.md` - Continuous improvement principles

## How to Use This Skill

When the user invokes `/refactoring-ui`, you should:

1. **If reviewing existing code/UI:**
   - Read the relevant files
   - Identify issues based on Refactoring UI principles
   - Provide specific, actionable fixes with code examples

2. **If building new UI:**
   - Apply principles proactively
   - Use proper spacing scales, typography, and color systems
   - Follow hierarchy best practices

3. **If asked for a general review:**
   - Run through the Quick Review Checklist below
   - Prioritize high-impact improvements

## Quick Review Checklist

### Hierarchy
- [ ] Is there clear primary/secondary/tertiary distinction?
- [ ] Using weight and color, not just size?
- [ ] Are labels minimized where format implies meaning?

### Spacing
- [ ] Using a consistent spacing scale (4, 8, 12, 16, 24, 32, 48...)?
- [ ] Related elements closer than unrelated?
- [ ] Content constrained to readable widths?

### Typography
- [ ] Using a defined type scale?
- [ ] Line height proportional to font size?
- [ ] Line length under 75 characters?

### Color
- [ ] Using HSL for color manipulation?
- [ ] 8-10 shades per color defined?
- [ ] Meeting accessibility contrast ratios?

### Depth
- [ ] Shadows consistent (same light source)?
- [ ] Elevation levels match UI importance?
- [ ] Using overlap for visual interest?

### Polish
- [ ] Form elements enhanced from defaults?
- [ ] Empty states designed, not generic?
- [ ] Using accent borders where appropriate?

## Response Format

When providing feedback:

```
## Issue: [Brief description]

**Principle:** [Which Refactoring UI principle applies]

**Current:**
[Code or description of current state]

**Recommended:**
[Code or description of improved state]

**Why:** [Brief explanation of the improvement]
```

## Example Interaction

User: "Review this card component"

Response:
```
## Issue: Flat hierarchy

**Principle:** De-emphasize to emphasize (Chapter 9)

**Current:**
```jsx
<div className="p-4">
  <span className="text-gray-700">Product Name</span>
  <span className="text-gray-700">$99.00</span>
  <span className="text-gray-700">In Stock</span>
</div>
```

**Recommended:**
```jsx
<div className="p-6">
  <h3 className="text-lg font-semibold text-gray-900">Product Name</h3>
  <span className="text-2xl font-bold text-blue-600">$99.00</span>
  <span className="text-sm text-gray-500">In Stock</span>
</div>
```

**Why:** Creates clear visual hierarchy through font size, weight, and color differentiation.
```