# Refactoring UI > Practical UI design system — an AI agent skill based on *Refactoring UI* by Adam Wathan & Steve Schoger. Published 2026-02-19 · Updated 2026-08-17 · Design & UX · Free and MIT-licensed Canonical: https://skills.wondel.ai/skills/refactoring-ui/ Source: https://github.com/wondelai/skills/tree/main/refactoring-ui **Install:** `npx skills add wondelai/skills/refactoring-ui --global` ## 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. ## About Adam Wathan & Steve Schoger Creator of Tailwind CSS & self-taught design educator. Adam Wathan is the creator of Tailwind CSS, used by millions of developers worldwide. Steve Schoger is a self-taught designer whose visual tips went viral and changed how developers approach UI design. ## Example prompts - Redesign this settings page to have clearer visual hierarchy using refactoring-ui skill _(UI cleanup)_ - Pick a spacing scale and apply it to my card component using refactoring-ui skill _(Design system)_ - Improve the color contrast on my dashboard without changing the brand colors using refactoring-ui skill _(Accessibility)_ - Make this form feel more polished and professional using refactoring-ui skill _(Form design)_ ## 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. ## Related - All Design & UX skills: https://skills.wondel.ai/skills/design/ - iOS HIG Design: https://skills.wondel.ai/skills/ios-hig-design/ - UX Heuristics: https://skills.wondel.ai/skills/ux-heuristics/ - Web Typography: https://skills.wondel.ai/skills/web-typography/ - Design of Everyday Things: https://skills.wondel.ai/skills/design-everyday-things/ - Top Design: https://skills.wondel.ai/skills/top-design/ - Lean UX: https://skills.wondel.ai/skills/lean-ux/ - Microinteractions: https://skills.wondel.ai/skills/microinteractions/ - Steve Jobs Design Review: https://skills.wondel.ai/skills/steve-jobs-design-review/