refactoring-ui-skill README

The project's README from github.com/s0xDk/refactoring-ui-skill. As one markdown file: README.md.

Refactoring UI (Claude Code skill)

A Claude Code skill that teaches Claude the concrete, mechanical rules from the book Refactoring UI by Adam Wathan and Steve Schoger — constrained spacing/type/color/shadow scales, visual hierarchy through weight and color rather than size, and depth through emulated light.

Every rule and CSS value in this skill was cross-checked page-by-page against the book. It's not a summary — it's the book's decisions, made once, ready to apply.

What it does

Load this skill and Claude will, when styling or reviewing UI:

It does not include the book itself — see Credits.

Repo structure

SKILL.md                 the skill: systems, procedure, hierarchy, hard rules
references/
  systems.md              building a color palette from scratch (HSL, saturation, hue rotation)
  diagnose.md              symptom -> fix table, for improving existing UI
  techniques.md            depth/light simulation, typefaces, grids, images
assets/
  tokens.css               a complete, contrast-verified starter token set

Installation

Claude Code loads skills from a folder containing a SKILL.md. Clone this repo into one of the skill directories below — use the folder name refactoring-ui so it matches the skill's declared name.

Personal skill (available in every project)

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

Project skill (checked into a specific repo, shared with your team)

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

(Or add it as a git submodule at that path if you want to track updates.)

Restart Claude Code (or start a new session) after installing so it picks up the new skill.

Usage

The skill activates automatically whenever Claude is building or styling UI, picking font sizes/spacing/colors/shadows, designing a palette or design tokens, or when you say a UI "looks off", "looks amateur", or "feels cluttered/plain/unfinished." You can also invoke it explicitly:

/refactoring-ui make this dashboard look less amateur

Credits

All design rules and reasoning are drawn from Refactoring UI by Adam Wathan and Steve Schoger. This repo does not include the book's text or images — only original notes and CSS derived from its concepts. If you find this useful, buy the book: https://www.refactoringui.com/

License

MIT for the contents of this repo (see LICENSE). Does not extend to the book itself.

refactoring-ui-skill (s0xDk/refactoring-ui-skill)

Searching Database…

What is this?A Claude Code skill that teaches Claude the concrete, mechanical design rules from the book 'Refactoring UI' by Adam Wathan and Steve Schoger — fixed spacing/type/color/shadow scales, hierarchy via weight and color, and depth via emulated light — so Claude applies them when building or fixing interfaces.
Is this a design system or a Claude Code skill file?It is a Claude Code skill: a folder containing a SKILL.md that Claude loads, not a CSS library or component kit you import into an app.
Do I need anything else besides Claude Code?Just Claude Code itself — no API keys, build tools, or extra dependencies are mentioned; it's purely a markdown skill file.
Does this include the actual book content?No — it only contains original notes and CSS values derived from the book's concepts, not the book's text or images, so you still need the actual book for full context.
When does the skill kick in during a session?It activates automatically whenever Claude is building or styling UI — picking font sizes, spacing, colors, shadows, designing a palette or tokens — or when you say a UI 'looks off', 'amateur', or 'cluttered/plain/unfinished'. It can also be invoked explicitly.
What kind of problems can it diagnose?It turns vague feedback like 'looks off' or 'feels cheap' into specific, mechanical fixes covering spacing scales, type hierarchy, color, shadows, depth, and generic component shapes.
Why not just read the book myself?The author cross-checked every rule and CSS value page-by-page against the book so Claude applies the book's decisions directly and consistently, rather than you manually translating prose advice into code each time.
Can I keep the skill updated as the repo changes?Yes, instead of a plain clone you can add the repo as a git submodule at the skill path to track future updates.
Creator
s0xDk
Size
<0.1 MB
Stars
646
Updated
CommitAug 26
Age
1mo
Commits · 90 Days