refactoring-ui-skill: the Refactoring UI rules as a Claude Code skill

The problem: Claude invents a new spacing value every prompt

Ask a language model to style a card and you get a plausible card. Ask it again tomorrow and you get a different plausible card: 13px here, 15px there, a shadow with no relationship to the one on the modal. Nothing is wrong in isolation, and the page still looks assembled from parts. The Refactoring UI argument, as the README restates it, is that this happens because values are chosen ad hoc instead of drawn from a constrained set.

This skill exists to close that gap for one specific tool. It is a Claude Code skill, meaning a folder with a SKILL.md that Claude Code loads, and its job is to make Claude pick spacing, type sizes, weights, colors, shadows and radii from fixed scales, and to build hierarchy through weight and color rather than piling on font-size. The audience is narrow: people who already drive Claude Code to build or review interfaces and want the output to follow a consistent system instead of a fresh aesthetic each session. It is not a design course, and the README is explicit that it does not include the book.

What is actually in the repository

The layout is small and readable, which matters because you can audit the rules before trusting them. SKILL.md holds the skill itself: the systems, the procedure, the hierarchy rules and the hard rules. Three reference files sit beside it. references/systems.md covers building a color palette from scratch using HSL, saturation and hue rotation. references/diagnose.md is a symptom-to-fix table for improving existing UI, which is the file you want when a designer says a screen looks off. references/techniques.md covers depth and light simulation, typefaces, grids and images. assets/tokens.css is a complete, contrast-verified starter token set.

The README claims every rule and CSS value was cross-checked page-by-page against the book, and describes the result as the book's decisions made once, ready to apply, rather than a summary. That claim is the whole value proposition and also the thing you cannot verify from the repository alone. What you can verify is the shape: the skill is a set of constraints and a diagnosis procedure, not a component library. Nothing here renders anything by itself.

Installing the skill and running a first fix

Claude Code loads skills from a folder containing a SKILL.md. The README says to clone the repository into one of the skill directories and to use the folder name refactoring-ui so it matches the skill's declared name. For a personal skill available in every project, the path is under your home directory:

git clone https://github.com/<you>/refactoring-ui-skill.git ~/.claude/skills/refactoring-ui

For a project skill checked into a specific repository and shared with a team, the same clone goes into the project's own skill directory. The README notes that adding it as a git submodule at that path is an option if you want to track updates:

git clone https://github.com/<you>/refactoring-ui-skill.git .claude/skills/refactoring-ui

After installing, restart Claude Code or start a new session so it picks up the skill. There is no build step, no package manager and no configuration file to edit.

The README states the skill activates automatically whenever Claude is building or styling UI, choosing font sizes, spacing, colors or shadows, designing a palette or design tokens, or when you describe a UI as looking off, amateur, cluttered, plain or unfinished. You can also invoke it explicitly:

/refactoring-ui make this dashboard look less amateur

A reasonable first use is not a greenfield page but an existing screen you already dislike, because references/diagnose.md is built around turning a vague complaint into specific fixes. Point Claude at the file, describe the symptom in the same vague terms you would use with a colleague, and compare what it changes against your own taste. If the fixes are mechanical and repeatable, the skill is doing its job. If it starts inventing values, the hard rules in SKILL.md are not being applied and that is worth reading before you rely on it.

Fixed scales are a constraint, and constraints cost you something

The central mechanism is a closed set of allowed values. That is also the main limitation. A designer who needs a 17px heading for one marketing page will find the scale refuses it, and the skill will push toward the nearest step rather than the exact number. This is the point of the approach, but it means the skill is a poor fit for work that intentionally breaks a system: editorial layouts with bespoke type, brand-driven spacing that comes from an existing design language, or any interface where the scale is already decided elsewhere and you need Claude to follow it rather than impose one.

There is a second, quieter risk. The skill encodes one book's opinions as hard rules. Where your team disagrees with those opinions, the skill will keep arguing for them, and you will spend prompts overriding it. That is not a defect in the repository so much as a property of adopting someone else's design system wholesale.

The README also does not document an uninstall or rollback path. Because installation is a git clone into a directory, removal is presumably deleting that directory, but the README does not say so, and it does not describe how to pin a version or what changes between pushes. If you need reproducible behaviour across a team, track the clone as a submodule at a known commit rather than pulling whatever is current.

How this differs from a Tailwind preset or a design-token package

The obvious comparison is a CSS framework or a token package: Tailwind's default theme, for instance, also constrains spacing and type to a scale, and it ships real classes you apply to markup. The difference in approach is where the constraint lives. A framework enforces the scale at build time, in the stylesheet, whether or not anyone is thinking about design. This skill enforces it at generation time, in the model's reasoning, before any CSS exists. It produces decisions and CSS values; the framework produces the CSS that ships.

That makes the two complementary rather than competing, and it also exposes the skill's dependency: it only does anything inside Claude Code. A team that writes CSS by hand, or that uses a different assistant, gets nothing from it. A second comparison is the book itself. Refactoring UI is prose, examples and images that teach a person to see the problem. The repository is the opposite artefact: the same decisions compressed into rules a model can apply without reading the argument behind them. If you want to understand why weight beats size for hierarchy, the book is the source. If you want the rule applied consistently in a session, this is the shorter path, and the README points you to the book for the reasoning.

Maintenance, licensing and what the MIT grant covers

The repository is not archived. The last push was on 2026-08-26, which is recent enough that the code is unlikely to have drifted from current Claude Code skill conventions, though no releases have been published, so there is no version history to read. Upgrading means pulling the clone or updating the submodule; because the skill is markdown and one CSS file, an update can change the rules Claude follows without any visible signal in your project beyond different output.

The licence situation needs care. The README states MIT for the contents of the repository and points to the LICENSE file, while the repository metadata reports NOASSERTION, meaning the licence could not be identified automatically. Read LICENSE yourself rather than relying on either signal. More importantly, the README is explicit that the MIT grant does not extend to the book itself, and that the repository contains only original notes and CSS derived from the book's concepts, not its text or images. That is a deliberate boundary, and it means you cannot treat this repository as a substitute for buying the book. This is not legal advice; if you plan to redistribute the notes or fold them into a product, check the terms with someone qualified.

Editorial conclusion

Adopt it if you already use Claude Code for front-end work and want styling decisions constrained to fixed scales rather than invented per prompt. Skip it if you need a component library, a Figma plugin, or the book's own prose and images, because the repository ships only original notes and CSS and the licence does not extend to the book. Before trusting it, read SKILL.md and references/diagnose.md to confirm the symptom-to-fix table covers the complaints your team actually files, and check assets/tokens.css against your existing palette, since the README describes it as a starter set rather than a drop-in theme.

Frequently asked questions

Official sources

1. Issues
2. README
3. s0xDk/refactoring-ui-skill on GitHub