Refactoring UI

Refactoring UI (Claude Code skill)

A Claude Code skill that teaches Claude the concrete, mechanical rules from the book Refactoring UI by Adam Wathan and Steve Schoger — constrained spacing/type/color/shadow scales, visual hierarchy through weight and color rather than size, and depth through emulated light.

Every rule and CSS value in this skill was cross-checked page-by-page against the book. It's not a summary — it's the book's decisions, made once, ready to apply.

What it does

Load this skill and Claude will, when styling or reviewing UI:

• Pick spacing, type sizes, weights, colors, shadows and radii from fixed scales instead of ad hoc values
• Build hierarchy through weight/color rather than piling on font-size
• Diagnose vague complaints ("looks off", "feels cheap") into specific, mechanical fixes
• Apply concrete techniques for depth, contrast, images, and breaking generic component shapes

It does not include the book itself — see Credits.

Repo structure

SKILL.md                 the skill: systems, procedure, hierarchy, hard rules
references/
  systems.md              building a color palette from scratch (HSL, saturation, hue rotation)
  diagnose.md              symptom -> fix table, for improving existing UI
  techniques.md            depth/light simulation, typefaces, grids, images
assets/
  tokens.css               a complete, contrast-verified starter token set

Installation

Claude Code loads skills from a folder containing a SKILL.md. Clone this repo into one of the skill directories below — use the folder name refactoring-ui so it matches the skill's declared name.

Personal skill (available in every project)

git clone https://github.com/<you>/refactoring-ui-skill.git ~/.claude/skills/refactoring-ui

Project skill (checked into a specific repo, shared with your team)

git clone https://github.com/<you>/refactoring-ui-skill.git .claude/skills/refactoring-ui

(Or add it as a git submodule at that path if you want to track updates.)

Restart Claude Code (or start a new session) after installing so it picks up the new skill.

Usage

The skill activates automatically whenever Claude is building or styling UI, picking font sizes/spacing/colors/shadows, designing a palette or design tokens, or when you say a UI "looks off", "looks amateur", or "feels cluttered/plain/unfinished." You can also invoke it explicitly:

/refactoring-ui make this dashboard look less amateur

Credits

All design rules and reasoning are drawn from Refactoring UI by Adam Wathan and Steve Schoger. This repo does not include the book's text or images — only original notes and CSS derived from its concepts. If you find this useful, buy the book: https://www.refactoringui.com/

License

MIT for the contents of this repo (see LICENSE). Does not extend to the book itself.