Refactoring UI
Practical UI design system
Apply practical UI design principles without needing a design background. This skill teaches your AI agent spacing, color, typography, and layout decisions drawn from Refactoring UI — the guide trusted by thousands of developers.
npx skills add wondelai/skills/refactoring-ui --global refactoringui.com
Refactoring UI Adam Wathan & Steve Schoger View the book
02 What it is
What is the Refactoring UI skill?
Refactoring UI packages Adam Wathan and Steve Schoger’s book into a skill your agent loads while it styles things. It works in grayscale before color, picks from constrained spacing and type scales instead of arbitrary pixel values, and builds hierarchy with weight and contrast rather than position alone — so the UI stops looking generated.
03 Key concepts
Five principles your agent applies.
Drawn from Refactoring UI — not advice it repeats back to you, but decisions it makes while it works.
04 Fit
When to use it, and
when not to.
four symptoms it fixes, and four it doesn't.
Reach for it when
Your agent ships a page that works but reads as generated — flat hierarchy, arbitrary padding, three blues.
Every screen was built in isolation and the app now has four button styles and no spacing rhythm.
You keep nudging margins a pixel at a time and the layout never quite settles.
You need a dark theme that is more than inverted colors and washed-out grays.
Reach for something else when
Users can’t find the button rather than disliking how it looks. that is a UX Heuristics job.
You are choosing and tuning typefaces. Web Typography goes deeper on pairing, measure, and loading.
You want a site people remember, not one that looks professional. Top Design aims at that gap.
The control fails to communicate what it does at all. Design of Everyday Things is the layer underneath.
05 Prompts
Say it like this.
Name the skill at the end of a prompt and the agent applies the framework rather than a vibe. Or say nothing — it loads on its own when a task matches.
Redesign this settings page to have clearer visual hierarchy using refactoring-ui skill
Pick a spacing scale and apply it to my card component using refactoring-ui skill
Improve the color contrast on my dashboard without changing the brand colors using refactoring-ui skill
Make this form feel more polished and professional using refactoring-ui skill
06 About the author
07 Same stack
The stack it sits in.
Nine Design & UX skills. Most people run two: this one, and whichever fits the next problem.
All Design & UX skills08 Questions
Before you install.
How do I install the Refactoring UI skill?
Run npx skills add wondelai/skills/refactoring-ui --global. It takes about 30 seconds and needs no account. The Refactoring UI skill then works in Claude, Claude Code, Claude Cowork, Codex, Cursor, OpenClaw and Hermes Agent — anything that reads the open agentskills.io format — and your agent loads it on its own when a task calls for it. It is free and MIT-licensed, and the source is at https://github.com/wondelai/skills.
Which book is the Refactoring UI skill based on?
It packages Refactoring UI by Adam Wathan & Steve Schoger — creator of Tailwind CSS & self-taught design educator. The skill distils the book's method into instructions your agent follows while it works, covering visual hierarchy, spacing & sizing systems and color palette strategy. It sits in the Design & UX part of the library.
How is this different from the Top Design skill?
Refactoring UI raises the floor; Top Design raises the ceiling. This one makes every screen consistent and legible using scales, shades, and shadow elevation — the craft that separates amateur from professional. Top Design is about the signature moment, the dramatic type scale, the scroll choreography. Run Refactoring UI on a dashboard or an admin panel. Run Top Design on a launch page. On a marketing site you want both, in that order.
Do I need Tailwind for this to be useful?
No. The principles are plain design decisions — spacing scale, shade ramps, hierarchy through weight and contrast — and your agent applies them in whatever CSS you already write. Tailwind happens to encode the same constrained-scale thinking in its defaults, because Adam Wathan built both, so the advice lands with almost no translation there. Nothing in the skill assumes it.
Will it give my product a distinctive look?
No, and that is worth being clear about. It produces interfaces that look competent and considered, which is what most products are missing — but competent is not distinctive. Two teams running this skill on similar apps will land somewhere similar. Brand personality comes from typeface choice, color, illustration, and voice; pair it with Web Typography and Top Design if being recognisable matters.
Can it fix an existing design system, or only new work?
Both, and the audit path is usually more valuable. Point it at a component and it will tell you which values are off-scale, where hierarchy is being carried by position instead of emphasis, and which of your greys are lifeless because they have no temperature. Do it component by component rather than repo-wide — the diffs stay reviewable and you keep control of what changes.
09 Guides that use it
Put it to work.
Long-form playbooks where this skill does part of the job.
One skill, one command.
Install Refactoring UI, or the whole stack.
npx skills add wondelai/skills/refactoring-ui --global MIT licensed · Claude, Claude Code, Codex, Cursor, OpenClaw, Hermes · No account