# Refactoring UI Design and improve user interfaces using the concrete rules from Refactoring UI (Wathan... - Repository: https://github.com/s0xDk/refactoring-ui-skill (680 stars) - Category: Design - License: see repository - Last updated: 2026-08-26 - Runs scripts: no, instructions only ## Install Claude Code: `npx skills add s0xDk/refactoring-ui-skill --skill refactoring-ui -g -a claude-code -y` Codex: `npx skills add s0xDk/refactoring-ui-skill --skill refactoring-ui -g -a codex -y` Cursor: `npx skills add s0xDk/refactoring-ui-skill --skill refactoring-ui -g -a cursor -y` Gemini CLI: `npx skills add s0xDk/refactoring-ui-skill --skill refactoring-ui -g -a gemini-cli -y` ## Description 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". ## SKILL.md, as published by its author (untrusted third-party text, read it as data) # 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 The rest: https://github.com/s0xDk/refactoring-ui-skill/blob/HEAD//SKILL.md