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.
Refactoring UI
npx skills add wondelai/skills/refactoring-ui --global This skill is compatible with Claude, Claude Code, Claude Cowork, Codex, Cursor, OpenClaw, Hermes Agent, and other agentskills.io-compatible agents.
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.
Key concepts from Refactoring UI your agent applies
Visual Hierarchy
Control emphasis with size, weight, and color instead of relying on layout position alone.
Spacing & Sizing Systems
Use a constrained spacing scale to keep layouts consistent and avoid arbitrary pixel values.
Color Palette Strategy
Define primary, neutral, and accent palettes with multiple shades for flexibility.
Typography Choices
Pick typefaces that match the personality of your product and pair them effectively.
Depth & Shadows
Layer elements using elevation cues like shadows and overlapping to add realism.
When to use Refactoring UI — and when not to
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.
Example prompts for the Refactoring UI skill
Redesign this settings page to have clearer visual hierarchy using refactoring-ui skill
UI cleanupPick a spacing scale and apply it to my card component using refactoring-ui skill
Design systemImprove the color contrast on my dashboard without changing the brand colors using refactoring-ui skill
AccessibilityMake this form feel more polished and professional using refactoring-ui skill
Form designRefactoring UI vs the other Design & UX skills
All 9 Design & UX skills are free and install the same way — the only question is which framework fits the job in front of you.
| Skill | Based on | Best for |
|---|---|---|
| Refactoring UI | Refactoring UI — Adam Wathan & Steve Schoger | Practical UI design system |
| iOS HIG Design | Human Interface Guidelines — Apple | Native iOS app design guidelines |
| UX Heuristics | Don’t Make Me Think — Steve Krug & Jakob Nielsen | Usability evaluation and principles |
| Web Typography | On Web Typography — Jason Santa Maria | Web typography principles and implementation |
| Design of Everyday Things | The Design of Everyday Things — Don Norman | Foundational design principles: affordances, signifiers, feedback |
| Top Design | Elite Agency Techniques — Locomotive, Studio Freight, AREA 17 | Award-winning 10/10 web design |
| Lean UX | Lean UX — Jeff Gothelf & Josh Seiden | Collaborative, experiment-driven UX design |
| Microinteractions | Microinteractions — Dan Saffer | Designing details that delight users |
| Steve Jobs Design Review | Steve Jobs — Walter Isaacson | Jobs-style reviews: ruthless simplicity, focus, binary verdicts |
Frequently asked questions
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.
Install Refactoring UI
Free, open-source, and ready in 30 seconds.
npx skills add wondelai/skills/refactoring-ui --global MIT Licensed · Works with Claude, Claude Code, Claude Cowork, Codex, Cursor, OpenClaw, Hermes Agent & other agentskills.io agents · No account needed
Don’t guess your AI engineering level.
Measure it.
AI Developer Scorecard
How production-grade is your AI engineering?
Twenty-five questions across the practices that separate vibe-coding from production-grade engineering. Instant score, per-section breakdown, and a 30/60/90-day playbook.
Score 0–75 · 30/60/90-day playbook Score yourself For CTOs & foundersCTO Scorecard
Is your engineering team ready for AI at scale?
Twenty-five questions on how your org adopts AI — adoption, governance, automation, and ROI. See where you sit on the path from Reactive to Strategic Leader.
Score 0–75 · Reactive → Strategic Leader Score your orgWe build the skills you already use. Now we’ll build yours.
Sprints from $3K · shipped to production, or you don’t pay the final milestone.