ui-refactor

What this skill does

# UI Refactor — Design Review Skill

## Core Philosophy

Design quality comes from specific, learnable decisions — not innate talent. Three principles underpin everything:

1. **Hierarchy is the #1 factor.** An interface where every element competes equally for attention feels chaotic. Deliberately de-emphasize secondary elements before amplifying primary ones.
2. **Constrained choices beat infinite options.** Pre-define systems for spacing, type sizes, colors, and shadows. Pick from the system, never from the infinite continuum. Decision fatigue kills quality.
3. **Start functional, add polish last.** Design features not layouts, work in grayscale before adding color, ship the smallest useful version. Details like shadows and icons are finishing touches, not starting points.

## Review Workflow

When reviewing a design (screenshot, code, or description), evaluate across six dimensions in priority order:

1. **Hierarchy & Emphasis** — Can you identify primary, secondary, and tertiary content instantly? Is there a clear visual path?
2. **Spacing & Layout** — Is spacing systematic? Do groups feel cohesive? Is there ambiguous spacing?
3. **Typography** — Is the type scale constrained? Are line-heights proportional? Are line lengths readable?
4. **Color** — Are colors from a defined system? Do greys have temperature? Is contrast accessible?
5. **Depth & Images** — Are shadows from a defined elevation system? Is text readable on images?
6. **Polish & Finishing** — Are defaults supercharged? Are borders overused? Are empty states designed?

**Output format:**
```
## Design Review

### What Works Well
- [Specific praise with why it works]

### Issues Found
1. **[Issue Name]** — [Dimension]
   - What: [Observable problem]
   - Why: [Principle being violated]
   - Fix: [Concrete CSS/code change]

### Quick Wins
- [Highest-impact, lowest-effort changes]
```

## Advisory Workflow

When answering design questions during development (not reviewing existing work):

1. Identify which dimension the question falls under
2. Load the relevant reference file
3. Provide the specific principle, concrete values, and reasoning
4. If the question spans multiple dimensions, address the highest-priority one first

## Decision Tree — Which Reference to Load

Route to the right reference based on the symptom:

| Symptom | Load |
|---------|------|
| "Everything looks the same weight/importance" | `references/hierarchy-and-emphasis.md` |
| "It looks cramped" or "spacing feels off" | `references/spacing-and-layout.md` |
| "The fonts don't feel right" or "text is hard to read" | `references/typography.md` |
| "Colors feel random" or "it looks washed out" | `references/color.md` |
| "It feels flat" or "text on images is unreadable" | `references/depth-and-images.md` |
| "It looks amateur" or "needs more polish" | `references/polish-and-finishing.md` |
| "Where do I even start?" or general design process | `references/design-process.md` |
| Reviewing a full screenshot or page | Load `references/hierarchy-and-emphasis.md` first, then others as issues emerge |

## Quick Anti-Pattern Checklist

Before loading any reference files, check for these 8 high-signal problems:

1. **Wall of Content** — Everything at the same size/weight/color. No primary-secondary-tertiary distinction.
2. **Ambiguous Spacing** — Equal gaps between a label and its input vs. between form groups. Proximity doesn't signal relationship.
3. **Font Size Soup** — More than 8 distinct font sizes visible. No constrained type scale.
4. **Color Without System** — Ad-hoc hex values. No visible shade palette. Grey text on colored backgrounds using literal grey.
5. **One Shadow Fits All** — Same box-shadow on buttons, cards, and modals. No elevation hierarchy.
6. **Border Everything** — Borders used as the default separator when spacing, background color, or box-shadow would be cleaner.
7. **Full-Width Everything** — Content stretched to fill viewport when a max-width constraint would improve readability.
8. **Ignored Empty States** — Blank screens with just "No items found" — no illustration, no guidance, no call-to-action.

If any are detected, load the relevant reference for detailed fixes.

## Reference Files

| File | Contents | Load When |
|------|----------|-----------|
| `references/design-process.md` | Start with features, work low-fidelity, constrain choices, define personality | Starting a new design or asking "where do I begin?" |
| `references/hierarchy-and-emphasis.md` | Emphasize by de-emphasizing, weight + color + size for hierarchy, labels as last resort, semantic vs visual hierarchy | Hierarchy issues detected or reviewing any full interface |
| `references/spacing-and-layout.md` | Non-linear spacing scale, start with too much whitespace, fixed sidebars, avoid ambiguous spacing | Spacing/layout issues or reviewing component/page structure |
| `references/typography.md` | Hand-crafted type scale, proportional line-height, line length, letter-spacing, baseline alignment | Typography issues or text-heavy interfaces |
| `references/color.md` | HSL workflow, 8-10 shades per color, hue rotation, warm/cool greys, accessible contrast | Color issues, palette creation, or contrast problems |
| `references/depth-and-images.md` | 5-level shadow system, two-part shadows, flat depth, text on images, icon sizing | Depth/shadow issues or image-related problems |
| `references/polish-and-finishing.md` | Supercharged defaults, accent borders, fewer borders, empty states, thinking outside the box | "It needs more polish" or finishing a nearly-complete design |