Refactoring UI skill

---
name: refactoring-ui
description: Design rulebook and diagnostic layer for web UI, distilled from Refactoring UI by Adam Wathan and Steve Schoger. Use when building a new page or component, refining UI that looks off or amateurish, running a design review, or establishing design tokens (color shades, type scale, spacing scale, elevation, radius). Covers visual hierarchy, layout and spacing, typography, color and contrast, depth and shadows, images, and finishing touches, with Tailwind mappings throughout. Also triggers on non-English requests for the same things - for example Chinese: 页面/界面设计, 样式调整, UI 太丑, 设计评审, 视觉层级, 配色, 对比度, 间距, 排版, 阴影, 空状态, 设计规范, 设计系统. Not for backend logic, copy editing, or changes with no visual surface.
---

# Refactoring UI

## What this skill is

This skill is the **constraint and diagnosis layer** for interface work. It supplies the rules a design must satisfy and finds where a design breaks them.

It is deliberately **not a generator of aesthetics**. When a design-generation capability is present (a Design mode, `frontend-design`, a canvas tool), that capability decides what the interface *looks like*; this skill decides what it must *obey*, and afterwards checks whether it did. See [Composing with design generators](#composing-with-design-generators).

The rules come from a book whose authors went on to build Tailwind CSS. Its scales are Tailwind's defaults, so the path from principle to code is unusually short.

## Step 0 — Detect before you decide

**Never make a design judgment before running this.** It takes one pass and prevents the two worst failure modes: fighting an existing design system, and emitting code the project can't use.

Detect and state briefly:

1. **Framework** — React/Vue/Svelte/plain HTML; SSR or SPA.
2. **Tailwind, and which major version.** v4 declares theme in CSS via `@theme`; v3 uses `tailwind.config.js`. Check `package.json`, then look for `@import "tailwindcss"` (v4) vs `@tailwind base` (v3).
3. **Existing design tokens** — CSS custom properties, a theme object, a `tokens.json`, a `theme/` directory.
4. **Component library** — shadcn/ui, MUI, Ant Design, Chakra, Radix. These carry their own token contracts — for shadcn/ui, load `16-component-libraries.md` before writing or editing any component.
5. **Dark mode** — present, planned, or absent.

**The prime directive that follows from this: an existing system always wins.** Where the project has a system, translate the book's principles into that system's vocabulary. Where it has none, propose one. Never overwrite, never silently migrate, never add a build-time dependency the user didn't ask for.

## Reading the reference files

The reference files mix two kinds of content, and confusing them is the main way this skill can do damage. The notation keeps them apart.

**Invariants — the book's actual rules.** In every `Values` block, **bold numbers are invariants**: font weights 400/500 and 600/700, a maximum of three text colors, one primary action per page, 45–75 characters per line, 4.5:1 and 3:1 contrast, no two scale steps closer than 25%, hue rotation capped at 20–30°, five elevation levels. These do not vary by project. Apply them as written.

**Illustrative choices — everything else.** Unbolded values in `Values`, and every size, spacing and color in a code example, are one valid instance of the rule, not the required answer.

**Colors in examples are always placeholders**, written in braces so they cannot be pasted verbatim:

| Placeholder | Resolves to |