Skills

Refactoring UI

Design and improve user interfaces using the concrete rules from Refactoring UI (Wathan...

Install

npx skills add s0xDk/refactoring-ui-skill --skill refactoring-ui -g -a claude-code -y
Category
Design
Updated
2mo ago
License
See repository
Context cost
Mediumabout 3,000 tokens
Runs scripts
No, instructions only

What it does

Design and improve user interfaces using the concrete rules from Refactoring UI (Wathan & Schoger), constrained spacing/type/color/shadow scales, visual hierarchy through weight and color rather than size, and depth through emulated light. Use when building or styling any UI (web, app, dashboard, landing page, component), when picking font sizes, spacing, colors, shadows or border radius, when designing a color palette or design tokens, and whenever someone says a UI "looks off", "looks amateur", "feels cluttered/plain/unfinished", or asks to "make this look better".

Refactoring UI

Visual design is not talent. It is a small set of systems decisions made once, plus a handful of techniques for creating hierarchy. This skill is those systems and those techniques.

The single biggest cause of amateur-looking UI is picking values ad hoc, 17px here, #3B82F6 there, lighten(5%) for a hover state. Design from a scale, always.


The systems, use these, do not re-derive them

Pick from these lists. Never invent a value that isn't on one.

Spacing and sizing

Base 16px, built from factors and multiples of it:

4  8  12  16  24  32  48  64  96  128  192  256  384  512  640  768

Tight at the small end, spreading out at the large end. No two adjacent values may be closer than ~25%, that is what makes the choice obvious. A linear "multiples of 4" scale fails: it does not help you decide between 120px and 124px.

Use it for margin, padding, width, height, icon sizes, border width, everything spatial. Fix a small set of opacity values too (e.g. .05 .1 .2 .4 .6 .8) for disabled states, overlays and hover tints, rather than eyeballing a slider each time. Same logic as the other scales: decide once, reuse everywhere.

Type scale

12  14  16  18  20  24  30  36  48  60  72

Not a modular scale built from a ratio (4:5, 2:3, golden ratio). Those produce fractional pixel values that round inconsistently across browsers and are too sparse for interface density, hand-picked values, chosen for how they feel, win instead.

Units: px or rem only. Never em. em is relative to the current font size, so a .875em inside a 1.25em parent computes to 17.5px, a value not in your scale. The scale silently stops existing.

Font weight

Two weights is enough:

  • 400 or 500, body and most UI text
  • 600 or 700, anything emphasized

Nothing below 400 in UI. To de-emphasize, use a lighter color or smaller size, never a lighter weight.

Color

Read the whole SKILL.md on GitHub

More in Design