refactoring-ui
Audit and fix visual hierarchy, spacing, color, and depth in web UIs
Install / Use
npx skills add wondelai/skills --skill refactoring-uiInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
AutomationSupported Platforms
Our assessment of refactoring-ui
refactoring-ui scores 84/100 on our quality scale, 2062nd of 2,790 Automation skills we index.
Its SKILL.md is 15 KB long, well organised into 15 sections and no code examples: a thorough specification that gives an agent plenty to work with.
With 2,248 GitHub stars, it is one of the more widely adopted skills in the catalogue.
Maintenance, license and trust
- The repository was last updated about 2 months ago, so refactoring-ui is actively maintained.
- Our last check on 2026-11-05 found the source still online.
- It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-10-01. Automated pattern scan on 2026-10-01. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
refactoring-ui compared with similar skills
All 4 of these similar skills score higher than refactoring-ui; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| refactoring-ui (this skill)by wondelai | 84 | 2.2k | 2mo ago | SKILL.md |
| taste-skillby Leonxlnx | 100 | 116.8k | 8d ago | CLAUDE.md |
| Agent-Reachby Panniantong | 100 | 112.3k | 8d ago | CLAUDE.md |
| rufloby ruvnet | 100 | 81.9k | today | CLAUDE.md |
| Claude-Code-Game-Studiosby Donchitos | 100 | 39.7k | 7d ago | CLAUDE.md |
Frequently asked questions
- How do I install refactoring-ui?
- Run
npx skills add wondelai/skills --skill refactoring-ui. The install tabs above show the steps for each supported agent. - Which AI agents does refactoring-ui work with?
- It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is refactoring-ui safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is MIT-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is refactoring-ui still maintained?
- The repository was last updated about 2 months ago, so refactoring-ui is actively maintained.
Skill content
View source on GitHubname: refactoring-ui description: 'Audit and fix visual hierarchy, spacing, color, and depth in web UIs. Use when the user mentions "my UI looks off" (or amateur/unprofessional), "fix the design", "Tailwind styling", "color palette", "visual hierarchy", "design system", "spacing scale", or "component styling". Also trigger when building consistent design tokens, creating dark mode themes, improving data-visualization clarity, or polishing UI details before launch. Covers grayscale-first workflow, constrained design scales, shadows, and component styling. For typeface selection, see web-typography. For usability audits, see ux-heuristics.' license: MIT metadata: author: wondelai version: "1.5.1"
Refactoring UI Design System
A practical, opinionated approach to UI design. Apply these principles when generating frontend code, reviewing designs, or advising on visual improvements.
Core Principle
Design in grayscale first. Add color last. This forces proper hierarchy through spacing, contrast, and typography before relying on color as a crutch.
The foundation: Great UI isn't about talent — it's about systems. Constrained scales for spacing, type, color, and shadows produce consistently professional results. Start with too much white space and remove; leave details (icons, shadows, micro-interactions) until layout and hierarchy work.
Scoring
Goal: 10/10. Score by counting satisfied rows in the Quick Diagnostic (8 yes/no checks): score = round(satisfied / 8 × 10). Bands follow directly: 10 = all 8 pass (hierarchy reads blurred and in grayscale, every value on a scale); 9 = exactly 1 gap (usually weak hierarchy or thin white space); 6-8 = 2-3 gaps; <=5 = 4+ gaps (arbitrary spacing, color doing the work hierarchy should, or failing contrast). Always state the current score and the specific diagnostic rows to fix to reach 10/10.
The Refactoring UI Framework
Seven principles for building professional interfaces without a designer:
1. Visual Hierarchy
Core concept: Not everything can be important. Create hierarchy through three levers: size, weight, and color.
Why it works: When every element competes for attention, nothing stands out; deliberately de-emphasizing secondary content makes primary content powerful by contrast.
Key insights:
- Combine levers, don't multiply — primary text = large OR bold OR dark, not all three; save "all three" for the single most important element
- Labels are secondary — form labels, table headers, and metadata support the data, not compete with it; make them smaller, lighter, or uppercase-small
- Semantic color ≠ visual weight — a muted secondary button often beats screaming red for routine destructive actions
Product applications:
| Context | Hierarchy Technique | Example | |---------|---------------------|---------| | Form fields | De-emphasize labels, emphasize values | Small uppercase label above large value | | Dashboards | Key metric large, context small | "$42,300" large, "vs last month" small | | Tables | De-emphasize headers, emphasize data | Headers uppercase small gray, data normal |
Design patterns:
- Three-level hierarchy: Size (large/base/small), Weight (bold/medium/normal), Color (dark/medium/light gray)
- Button hierarchy: primary (filled), secondary (outlined or muted), tertiary (text only)
Ethical boundary: Don't use hierarchy tricks to hide important information like pricing, terms, or cancellation options.
See references/advanced-patterns.md when designing components beyond static layout — interaction/hover/focus states, form design, empty states, border-radius systems, text truncation, and responsive breakpoints.
2. Spacing & Sizing
Core concept: Use a constrained spacing scale, not arbitrary values. Spacing defines relationships — closer elements read as more related.
Why it works: Arbitrary spacing (padding: 13px) creates inconsistency; a fixed scale forces deliberate decisions and harmonious layouts. Generous spacing feels premium; dense feels overwhelming.
Key insights:
- Use the scale: 4, 8, 16, 24, 32, 48, 64px
- Start with too much white space, then remove — you'll almost never remove enough
- Spacing between groups must exceed spacing within groups
- Constrain widths: text to 45-75 characters (
max-w-prose), forms to 300-500px; full-width is almost never right
Product applications:
| Context | Spacing Strategy | Example | |---------|-----------------|---------| | Icon + label | Tight coupling (4px) | Small gap keeps them connected | | Card sections | Section separation (24px) | Title, content, footer blocks | | Page sections | Major sections (48-64px) | Hero, features, testimonials |
CSS patterns:
p-1(4px)p-2(8px)p-4(16px)p-6(24px)p-8(32px)p-12(48px)p-16(64px)max-w-prose(65ch)max-w-md(28rem)max-w-lg(32rem)max-w-xl(36rem)gap-2for related items,gap-6for section separation
3. Typography
Core concept: Use a modular type scale, constrain line heights by context, and limit to two font families maximum.
Why it works: A modular scale (steps growing ~1.2× each) creates natural visual rhythm; tight line heights on headings and relaxed on body text improve readability in each context.
Key insights:
- Scale: 12, 14, 16, 18, 20, 24, 30, 36px (~1.2 modular, hand-tuned)
- Headings: tight line height (1.0-1.25); body: relaxed (1.5-1.75); wider text needs more line height
- Avoid weights below 400 for body text; use bold (600-700) for emphasis, not everything
- Two fonts max: one for headings, one for body (or one family with weight variation)
Product applications:
| Context | Typography Rule | Example | |---------|----------------|---------| | Hero headline | 36px, line-height 1.1, bold | Large impactful statement | | Body text | 16px, line-height 1.75, normal | Comfortable reading | | Captions/labels | 12-14px, line-height 1.5, medium gray | Secondary information |
CSS patterns:
text-xs(12px)text-sm(14px)text-base(16px)text-lg(18px)text-xl(20px)font-normal(400)font-medium(500)font-semibold(600)font-bold(700)leading-tight(1.25)leading-normal(1.5)leading-relaxed(1.75)
4. Color
Core concept: Build a systematic palette with 5-9 shades per color, add subtle saturation to grays, and design in grayscale first.
Why it works: Random colors clash; a predefined shade system ensures consistency, and HSL adjustments create natural-feeling lighter and darker variants.
Key insights:
- Each color needs 5-9 shades from near-white to near-black (50-900); darkest is not pure black — use
#111827, not#000000 - Pure grays look lifeless — tint them (cool UI: blue like
#64748b; warm UI: yellow/brown like#78716c) - HSL: lighter = raise lightness, lower saturation, hue toward 60°; darker = the reverse, hue toward 0°/240°
- Contrast minimums: 4.5:1 body text, 3:1 large text (18px+); use
#374151(gray-700) on white, not lighter grays
Product applications:
| Context | Color Strategy | Example |
|---------|---------------|---------|
| Primary palette | 9 shades (50-900) of brand color | Blue-500 buttons, Blue-100 backgrounds |
| Semantic colors | Success/warning/error with shade ranges | Green-500 success, Red-500 errors |
| Text colors | Three levels: dark, medium, light | text-gray-900, text-gray-600, text-gray-400 |
CSS patterns:
text-gray-900(dark)text-gray-600(medium)text-gray-400(light)bg-blue-50for subtle backgrounds,bg-blue-500for primary actionsborder-gray-200for subtle borders,border-gray-300for stronger
See references/theming-dark-mode.md when building a dark theme — hex shade scales, why darkest is #111827 not black (halation), and conveying elevation via lightness instead of shadow. See references/accessibility-depth.md when contrast, focus rings, keyboard nav, or screen-reader support is in scope — full WCAG 2.1 AA checklist and fixes.
5. Depth & Shadows
Core concept: Use a shadow scale to convey elevation — small shadows for slightly raised elements, large shadows for floating ones.
Why it works: The eye reads shadow size as height above the page; a consistent scale makes elevation legible, so users intuit what's interactive, floating, or background.
Key insights:
- Small shadows = raised slightly (buttons, cards); large = floating (modals, dropdowns)
- Good shadows have two parts: a tight dark shadow for crispness plus a larger soft one for atmosphere
- Depth without shadows: lighter top border + darker bottom border, subtle gradients, overlapping elements
- Don't overuse — if everything floats, nothing has depth; shadow color is transparent dark, never opaque gray
Product applications:
| Context | Shadow Level | Example |
|---------|-------------|---------|
| Buttons | shadow-sm (subtle raise) | Slightly elevated above surface |
| Dropdowns | shadow-lg (floating) | Menu clearly above content |
| Modals | shadow-xl (highest) | Overlay detached from page |
CSS patterns:
shadow-sm:0 1px 2px rgba(0,0,0,0.05)shadow-md:0 4px 6px rgba(0,0,0,0.1)shadow-lg:0 10px 15px rgba(0,0,0,0.1)shadow-xl:0 20px 25px rgba(0,0,0,0.15)
See references/animation-microinteractions.md when adding motion to interactive elements — durations, easing curves, loading states, and the prefers-reduced-motion rule.
6. Images & Icons
Core concept: Treat images as design elements, not afterthoughts. Size icons deliberately and use overlays to keep text readable on images.
Why it works: Poorly sized icons look awkward and unstyled images break consistency; deliberate treatment (overlays, object-fit, radius) makes interfaces feel polished.
Key insights:
- Size icons relative to context; use sets with consistent stroke width and style
- Never stretch or distort — use
object-fit: coverwith fixed aspect ratios and crop deliberately - Text over images needs an overlay (semi-transparent gradient)
- Empty states are an opportunity — use illustrations plus a clear CTA, not just text
Product applications:
| Context | Image/Icon Technique | Example | |---------|---------------------|---------| | Hero images | Semi-transparent gradient overlay | Text readable over any photo | | Avatars | Consistent size, rounded, fallback initials | 40px circle, object-fit cover | | Empty states | Custom illustration + CTA | Friendly illustration with "Get started" |
CSS patterns:
object-fit: coverwith fixedaspect-ratiofor consistent display- Icon sizing:
w-4 h-4inline,w-6 h-6navigation,w-8 h-8feature icons - Overlay:
bg-gradient-to-t from-black/60 to-transparentfor text on images
7. Layout & Composition
Core concept: Don't center everything. Use alignment, overlap, and emphasis variation to create engaging compositions.
Why it works: A consistent left edge gives the eye a fixed return point per line, so it costs less to scan; centered multi-line text moves that edge every line and slows reading.
Key insights:
- Left-align by default; center only short headlines, heroes, single-action CTAs, and empty states
- Cards don't need to contain everything — let images bleed to edges or overlap containers
- Vary visual treatment in lists and feeds — feature some items, minimize others
- Use alignment to create relationships between unrelated elements
Product applications:
| Context | Layout Strategy | Example | |---------|----------------|---------| | Hero sections | Centered text, generous spacing | Short headline + subtext + single CTA | | Blog feeds | Varied card sizes for emphasis | First post l
Truncated for display — read the full file on GitHub.
Related Skills
taste-skill
116.8kAgent skills that give coding agents taste: art direction, reference images and a browser check instead of generic AI pages
Agent-Reach
112.3kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
ruflo
81.9k🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
Claude-Code-Game-Studios
39.7kTurn Claude Code into a full game dev studio — 49 AI agents, 72 workflow skills, and a complete coordination system mirroring real studio hierarchy.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
