refactoring-ui-skill gives coding agents the Refactoring UI book's design rules
refactoring-ui-skill is an MIT-licensed Claude Code skill that encodes the mechanical rules from the Refactoring UI book, so an agent styling a page picks spacing, type, color, and shadow from fixed scales instead of inventing values every time.
Image: GitHub
Why it mattersA named-source skill forces the agent to reuse the same spacing, type, color, and shadow scales across every page, which is what stops AI-generated interfaces from moving toward the vague, generic look reviewers complain about.
The developer s0xDk has published refactoring-ui-skill, a Claude Code skill that teaches an agent the concrete design rules from the book Refactoring UI by Adam Wathan and Steve Schoger. The repository has gained 514 stars in the last 30 days and is released under an MIT licence.
What the agent gains
Loaded as a skill, the rules apply whenever Claude is building or styling UI, picking font sizes, spacing, colours, shadows and radii, designing a palette or design tokens, or when a reviewer says a UI "looks off", "looks amateur", or "feels cluttered". The skill can also be invoked explicitly by naming it.
Four behaviours change once the skill is active. The agent picks spacing, type sizes, weights, colours, shadows and radii from fixed scales rather than ad hoc values. It builds visual hierarchy through weight and colour instead of adding more font sizes. It translates vague complaints, such as "looks off" or "feels cheap", into specific, mechanical fixes. It applies concrete techniques for depth, contrast, images, and changing generic component shapes.
What is in the repo
The skill is one SKILL.md file with three reference documents. systems.md covers building a colour palette from scratch with HSL, saturation, and hue rotation. diagnose.md is a symptom-to-fix table for improving existing UI. techniques.md covers depth and light simulation, typefaces, grids, and images. An assets/tokens.css file provides a complete, contrast-verified starter token set.
The author states that every rule and CSS value was cross-checked page-by-page against the book, and describes the skill as the book's decisions made once, ready to apply. The book itself is not included: only original notes and CSS derived from its concepts.
How it installs
Claude Code loads skills from a folder containing a SKILL.md file. The README describes cloning the repo as either a personal skill available in every project, or a project skill checked into a specific repository and shared with a team. Placing it as a git submodule is offered as a way to track updates. A Claude Code restart loads the new skill.
AI-generated interfaces tend toward a recognisable look: pixel-round margins, one more font size than the last page, a shadow that never quite matches. The cause is that most model output makes each decision again from nothing, so scales that a designer would treat as fixed become suggestions. A skill that encodes a specific, named design system, rather than inviting the agent to reason, is a cheap way to fix that problem without hand-tuning every page. The pattern also works elsewhere: a small file that fixes a design system in place, backed by contrast-verified tokens and a symptom table, is worth building for any in-house style, not only for a widely-known book.
Source
Primary source: s0xDk/refactoring-ui-skill on GitHub.
This item was written by an AI system from the linked source. Reveneau is responsible for what it publishes.
Get AI News in your inbox
New developer tools, model and agent releases, and how teams are actually using them to release software. Short, and only when there is something worth reading.
