Four instruction files turn a design book into Claude Code rules
Refactoring UI Skill packages 4 Markdown files and one CSS token asset for Claude Code. The main SKILL.md contains the operating rules; 3 references cover palette construction, diagnosis, and visual techniques. Its source is Adam Wathan and Steve Schoger's Refactoring UI, but the repository says it contains original notes rather than the book or its images. That distinction matters. You are installing an opinionated interpretation designed for an agent, not buying a searchable copy of the source material.
The main instruction file is 267 lines, and the whole supplied set totals 7,432 words across its Markdown and CSS files. That is enough room for concrete choices instead of a thin prompt such as "make this polished." Claude gets rules about hierarchy, line length, action priority, fixed sidebars, photo overlays, icon sizing, dark surfaces, and group spacing. A diagnosis table maps complaints such as a cheap-looking card or unreadable photo headline to proposed changes. The specificity is the main reason to install it.
Sixteen spacing values replace arbitrary CSS choices
The skill defines 16 CSS tokens for spacing and sizing from 4px through 768px, plus 11 type sizes from 12px through 72px. It tells Claude to compare neighboring scale values instead of inventing a number for each component. Font weight is narrowed to two useful bands, colors are organized into ramps, and five shadow elevations correspond to different perceived depths. This can make generated code more internally consistent, especially when several UI edits happen in separate Claude sessions.
Those 5 shadow values sit inside a wider set of rules that narrows the design vocabulary. The skill says to pick one radius, avoid runtime shade generation, start in grayscale, and treat one action as primary on a page. That is useful medicine for random AI styling, though it can become too rigid for an existing design system with different tokens or product conventions. Project instructions should win when they conflict. I would install this as a default for greenfield work, then tell Claude explicitly which local rules it must preserve.
What happened when we ran it
Our sandbox did not run commit 4887214. The lab saw a CSS-classified repository with no supported ecosystem and no Dockerfile, so there was no supported install, build, or test step to execute. The environment was a fresh unprivileged Debian container with 3 CPUs and 8 GB of RAM, but those resources never became relevant. There is no failure log to interpret and no timing, package count, or test result to report.
The 4-file instruction pack fits direct consumption by Claude Code, yet it leaves a verification gap. The repository provides no parser check for the skill frontmatter, no fixture that shows which reference Claude loaded, and no sample UI with before-and-after assertions. A team can inspect the files and try the skill in a real project, but it cannot use an upstream command to detect a malformed edit or behavioral regression.
Both README clone commands need the open PR 1 fix
Installation should be simple: place one folder named refactoring-ui under ~/.claude/skills or a project's .claude/skills, then restart Claude Code. The 2 commands in the README instead point to https://github.com/<you>/refactoring-ui-skill.git. Anyone copying them gets a shell interpretation problem rather than this repository. Pull request 1, opened on 2026-08-28, changes the owner segment to s0xDk; it was still open when we fetched the repository.
No API key, server, database, package manager, or model download is documented. Invocation can be automatic when the description matches a UI task, or explicit through /refactoring-ui. The absence of services keeps the operational cost low. It also means success depends on Claude following prose and on a developer checking the resulting interface. Restarting the client proves that the skill can be discovered; it does not prove that every rule was applied or that the rendered page works.
The CSS asset includes measurable accessibility targets
The 149-line tokens.css file may be the most immediately reusable part of the repository. It defines spacing, type, weights, a cool grey ramp, a primary ramp, accent colors, five shadows, semantic roles, and dark-mode overrides. Comments identify 4.5:1 text contrast targets and 3:1 functional-border targets, including shades reserved for disabled or large text. This is better guidance than asking an agent to pick an attractive blue and hoping every text pairing remains readable.
The values are still a starter set, not proof about your finished product. Contrast changes when components choose different backgrounds, opacity, states, or user content. The skill also covers mobile-first work around a roughly 400px canvas, reduced reliance on proportional breakpoints, and non-color signals for charts and controls. It does not supply browser tests, screenshots, keyboard checks, or a visual regression suite. Keep those checks in the application where the generated CSS actually runs.
A three-day public history cannot establish maturity
The repository was created on 2026-08-26 and the last push was later that day. GitHub showed 416 stars and one combined open issue or pull request on 2026-08-29; the only open item we found was the clone-URL documentation PR. There is no latest release. The activity is current and the early attention is real, but 3 days of public history reveal little about maintenance, compatibility with future Claude Code changes, or how contributors handle disputed design advice.
commit 4887214 anchors a 4-file starting point with an MIT license for the original repository material. The license separately says it grants no rights to the Refactoring UI book. That boundary is clear enough for evaluation, while organizations with stricter derivative-content policies may still want their own review. For everyone else, the practical decision is simpler: use the skill as a compact design rulebook, and keep code review, accessibility testing, and product-specific judgment outside it.