Refactoring UI Skill for Claude: Audit and Fix Visual Hierarchy, Spacing and Color

Makes Claude audit a web interface for hierarchy, spacing, color and depth, score it out of 10 and fix what is off.

Installs: 9.6K; on skills.sh
Stars: 2.6K; on GitHub
Files: 5; besides SKILL.md
Updated: Sep 2026; last repo commit

Claude applies 7 principles to your UI or code: visual hierarchy, spacing and sizing, typography, color, depth and shadows, images and icons, and layout. It scores the result with an 8-question diagnostic (score is satisfied checks divided by 8, times 10) and names the rows to fix to reach 10.

SKILL.md lists wondelai as author and says it is based on the book Refactoring UI by Adam Wathan and Steve Schoger. It does not say the book's authors wrote or endorsed it. It is guidance with 5 extra reference files and no scripts. For typeface selection it points to web-typography and for usability audits to ux-heuristics.

Good for

Developers who build interfaces without a designer
Anyone whose UI 'looks off' or amateur and wants a concrete fix list
Teams setting design tokens, spacing scales or a dark theme

Install refactoring-ui

Claude Code

Copy this prompt.

Install the refactoring-ui skill in Claude Code. Run this command:

/plugin marketplace add wondelai/skills
/plugin install ux-design@wondelai-skills

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Pick one route, not both. The ux-design plugin installs 11 design skills, including refactoring-ui, web-typography and ux-heuristics. The marketplace manifest lists no hooks or MCP servers for it. Claude Code names plugin skills /plugin-name:skill-name, so after the plugin install the full name is /ux-design:refactoring-ui.

From the project README. Source.

What's in the skill

When it loads

Audit and fix visual hierarchy, spacing, color, and depth in web UIs. Use when the user mentions "my UI looks off" (or amateur/unprofessional), "fix the design", "Tailwind styling", "color palette", "visual hierarchy", "design system", "spacing scale", or "component styling". Also trigger when building consistent design tokens, creating dark mode themes, improving data-visualization clarity, or polishing UI details before launch. Covers grayscale-first workflow, constrained design scales, shadows, and component styling. For typeface selection, see web-typography. For usability audits, see ux-heuristics.

Sections in SKILL.md

Core Principle
Scoring
The Refactoring UI Framework
1. Visual Hierarchy
2. Spacing & Sizing
3. Typography
4. Color
5. Depth & Shadows
6. Images & Icons
7. Layout & Composition
Common Mistakes
Quick Diagnostic
Further Reading
About the Authors

Key facts

Author: wondelai (metadata.author in SKILL.md), based on the book by Adam Wathan and Steve Schoger
Skill version: 1.5.1
License: MIT (SKILL.md frontmatter, plugin manifest and LICENSE agree)
Folder: 6 files including SKILL.md (5 reference files)
Works in: Claude, Claude Code, Claude Cowork, Codex, Cursor, OpenClaw, Hermes Agent and other agentskills.io agents
Installs on skills.sh: 9,639 (Nov 2, 2026)
GitHub stars: 2,552 (Nov 2, 2026)
Last repo commit: Sep 10, 2026

What it includes

Create hierarchy with size, weight and color; make labels secondary.
Primary text is large or bold or dark, not all three, and 'all three' is kept for the one most important element.
1. Visual Hierarchy
Use a fixed scale of 4, 8, 16, 24, 32, 48 and 64 px.
Start with too much white space, keep text 45 to 75 characters wide, and keep space between groups bigger than within them.
2. Spacing & Sizing
A type scale from 12 to 36 px, tight headings, relaxed body, two fonts at most.
Body line height 1.5 to 1.75; headings 1.0 to 1.25.
3. Typography
5 to 9 shades per color, tinted grays and minimum contrast ratios.
Contrast minimums are 4.5:1 for body text and 3:1 for large text. The skill says to design in grayscale first.
4. Color
A shadow scale where small means slightly raised and large means floating.
Four levels are listed, sm, md, lg and xl, with CSS values.
5. Depth & Shadows
Size icons by context, keep images undistorted, add overlays under text.
Empty states get an illustration and a clear call to action.
6. Images & Icons
Left-align by default and vary treatment in lists and feeds.
Center only short headlines, heroes, single-action calls to action and empty states.
7. Layout & Composition
8 yes-or-no checks; score = satisfied / 8 x 10, with bands from 10 down to 5 or less.
Claude states the current score and the exact rows to fix to reach 10 out of 10. SKILL.md also lists 8 common mistakes with fixes.
Try: “Audit this pricing page with the refactoring-ui skill and tell me the score and what to fix.”
Scoring and Quick Diagnostic
5 files: accessibility, advanced patterns, animation, data viz, dark mode.
Claude opens them when the task needs them, such as dark theme work or charts and dashboards.
Read · Reference files

From the official docs

Permissions

Low risk

Claude may edit your styling code when you ask for fixes. Use git and review the diff before you commit.

What it can do

Read your data
Create and change things
Delete things
Read-only mode

Watch out for

It can rewrite your styling code
SKILL.md says to apply the principles when generating frontend code. Use git and review the diff before you commit.
The plugin route adds 10 more skills
The ux-design plugin installs 11 skills. The wondelai marketplace manifest lists no hooks or MCP servers for it. Use the single-skill command if you only want this one. github.com

Technical details

Scopes	Reads your UI code or screenshots you share Edits CSS, Tailwind classes or components when you ask for a fix

Questions

What does the Refactoring UI skill do?

It makes Claude review a web UI, or the code that builds it, against 7 design principles. It scores the result out of 10 and names which checks to fix.

Is this by the authors of the Refactoring UI book?

It lists wondelai as its author (metadata.author in SKILL.md). It is based on the book by Adam Wathan and Steve Schoger and credits them in its closing section, but SKILL.md does not say they wrote or endorsed it. The book's own site is refactoringui.com.

How do I install it?

In Claude Code, the install box offers the ux-design plugin, which installs 11 skills, or one command for this skill alone. The Claude tab shows the ZIP upload for the Claude app.

Does it need an API key or any tools?

SKILL.md names none, and the folder holds only Markdown files.

Is it safe to use?

It bundles no scripts. When you ask Claude to fix your UI, it edits your CSS, Tailwind classes or components, so review the diff before you commit.

How is it different from web-typography or ux-heuristics?

SKILL.md sends typeface selection to web-typography and usability audits to ux-heuristics. This skill covers hierarchy, spacing, color, depth and layout. Both are in the ux-design plugin.

Information

updated Nov 2, 2026

Repository: wondelai/skills
Folder: refactoring-ui

wondelai/skills skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 3