Refactoring UI Skill — Design skill for Claude Code

Refactoring UI (Claude Code skill)

A [Claude Code](https://claude.com/claude-code) skill that teaches Claude the concrete, mechanical rules from the book *[Refactoring UI](https://www.refactoringui.com/)* 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](#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//refactoring-ui-skill.git ~/.claude/skills/refactoring-ui

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

git clone https://github.com/