Mmcp.market

refactoring-ui skill

by wondelai·wondelai/skills·2.3k stars·MIT

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.

A100/100content scan

Is the refactoring-ui skill safe?

Clean: nothing in its files matched our rules. We read 6 files in the folder on 2026-09-28.

No findings.

Install the refactoring-ui skill

A skill is a folder. Copy it into your agent's skills folder and the agent loads it when the task matches its description. 

git clone --depth 1 https://github.com/wondelai/skills.git /tmp/skills
mkdir -p ~/.claude/skills
cp -r /tmp/skills/plugins/ux-design/skills/refactoring-ui ~/.claude/skills/refactoring-ui
available in every project

In the Claude apps, zip the folder and upload it from the Skills settings. The folder on GitHub

The instructions your agent would load

SKILL.md as published, without the frontmatter. Read it on GitHub

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:

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:

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-2 for related items, gap-6 for 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:

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:

CSS patterns:

  • text-gray-900(dark) text-gray-600(medium) text-gray-400(light)
  • bg-blue-50 for subtle backgrounds, bg-blue-500 for primary actions
  • border-gray-200 for subtle borders, border-gray-300 for 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:

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: cover with 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:

CSS patterns:

More skills from wondelai/skills

  • A37signals-wayBuild lean, opinionated products using the 37signals philosophy from "Getting Real", "Rework", and "Shape Up". Use when the user mentions "Getting Real", "Rework", "Shape Up", "37signals", "Basecamp method", "six-week cycles", "fixed time variable scope", "appetite vs estimates", "betting table", "breadboarding", "fat marker sketch", "build less", "underdo the competition", "opinionated software", "we have too many meetings", "how do we ship faster", or "stop overbuilding". Also trigger when cutting scope to ship sooner, running a small team, or avoiding long-term roadmaps. Covers shaping, betting, building, and the art of saying no. For MVP validation, see lean-startup. For design sprints, see design-sprint.
  • A37signals-wayBuild lean, opinionated products using the 37signals philosophy from "Getting Real", "Rework", and "Shape Up". Use when the user mentions "Getting Real", "Rework", "Shape Up", "37signals", "Basecamp method", "six-week cycles", "fixed time variable scope", "appetite vs estimates", "betting table", "breadboarding", "fat marker sketch", "build less", "underdo the competition", "opinionated software", "we have too many meetings", "how do we ship faster", or "stop overbuilding". Also trigger when cutting scope to ship sooner, running a small team, or avoiding long-term roadmaps. Covers shaping, betting, building, and the art of saying no. For MVP validation, see lean-startup. For design sprints, see design-sprint.
  • A37signals-wayBuild lean, opinionated products using the 37signals philosophy from "Getting Real", "Rework", and "Shape Up". Use when the user mentions "Getting Real", "Rework", "Shape Up", "37signals", "Basecamp method", "six-week cycles", "fixed time variable scope", "appetite vs estimates", "betting table", "breadboarding", "fat marker sketch", "build less", "underdo the competition", "opinionated software", "we have too many meetings", "how do we ship faster", or "stop overbuilding". Also trigger when cutting scope to ship sooner, running a small team, or avoiding long-term roadmaps. Covers shaping, betting, building, and the art of saying no. For MVP validation, see lean-startup. For design sprints, see design-sprint.
  • Aarchitecture-optimizationGuided journey from a working codebase grown slow and tangled to one measurably fast, cleanly bounded, and readable. Orchestrates eight skills phase by phase - working-with-legacy-code, clean-architecture, software-design-philosophy, refactoring-patterns, system-design, ddia-systems, release-it, pragmatic-programmer - every phase carries its method inline so it runs standalone, asking the user questions at every decision point and recording results in the project docs/ folder (PERFORMANCE.md, ARCHITECTURE.md, ARCHITECTURE-OPTIMIZATION-PLAN.md) so the journey resumes across sessions. Use when the user wants to make an app faster, untangle drifted boundaries, fix slow endpoints and queries, or says ''it works but it is slow and getting worse''. For an untested prototype, improve-code-quality; for an aged codebase you fear to touch, remove-technical-debt; for greenfield structure, design-code-architecture; for marketing-site page speed, improve-website. For one framework in isolation, invoke that skill directly.
  • Aarchitecture-optimizationGuided journey from a working codebase grown slow and tangled to one measurably fast, cleanly bounded, and readable. Orchestrates eight skills phase by phase - working-with-legacy-code, clean-architecture, software-design-philosophy, refactoring-patterns, system-design, ddia-systems, release-it, pragmatic-programmer - every phase carries its method inline so it runs standalone, asking the user questions at every decision point and recording results in the project docs/ folder (PERFORMANCE.md, ARCHITECTURE.md, ARCHITECTURE-OPTIMIZATION-PLAN.md) so the journey resumes across sessions. Use when the user wants to make an app faster, untangle drifted boundaries, fix slow endpoints and queries, or says ''it works but it is slow and getting worse''. For an untested prototype, improve-code-quality; for an aged codebase you fear to touch, remove-technical-debt; for greenfield structure, design-code-architecture; for marketing-site page speed, improve-website. For one framework in isolation, invoke that skill directly.
  • Aarchitecture-optimizationGuided journey from a working codebase grown slow and tangled to one measurably fast, cleanly bounded, and readable. Orchestrates eight skills phase by phase - working-with-legacy-code, clean-architecture, software-design-philosophy, refactoring-patterns, system-design, ddia-systems, release-it, pragmatic-programmer - every phase carries its method inline so it runs standalone, asking the user questions at every decision point and recording results in the project docs/ folder (PERFORMANCE.md, ARCHITECTURE.md, ARCHITECTURE-OPTIMIZATION-PLAN.md) so the journey resumes across sessions. Use when the user wants to make an app faster, untangle drifted boundaries, fix slow endpoints and queries, or says ''it works but it is slow and getting worse''. For an untested prototype, improve-code-quality; for an aged codebase you fear to touch, remove-technical-debt; for greenfield structure, design-code-architecture; for marketing-site page speed, improve-website. For one framework in isolation, invoke that skill directly.
  • Ablue-ocean-strategyCreate uncontested market space using value innovation instead of competing head-to-head. Use when the user mentions "blue ocean", "red ocean", "strategy canvas", "ERRC framework", "value innovation", "non-customers", "buyer utility map", "the market is too crowded", "how do we stand out", or "escape the price war". Also trigger when exploring a new market category, or finding underserved or non-customers. Covers the Four Actions Framework, Six Paths, buyer utility map, and value-cost trade-offs. For real strategy formulation and bad-strategy detection, see good-strategy-bad-strategy. For tech adoption strategy, see crossing-the-chasm. For product positioning, see obviously-awesome.
  • Ablue-ocean-strategyCreate uncontested market space using value innovation instead of competing head-to-head. Use when the user mentions "blue ocean", "red ocean", "strategy canvas", "ERRC framework", "value innovation", "non-customers", "buyer utility map", "the market is too crowded", "how do we stand out", or "escape the price war". Also trigger when exploring a new market category, or finding underserved or non-customers. Covers the Four Actions Framework, Six Paths, buyer utility map, and value-cost trade-offs. For real strategy formulation and bad-strategy detection, see good-strategy-bad-strategy. For tech adoption strategy, see crossing-the-chasm. For product positioning, see obviously-awesome.
  • Ablue-ocean-strategyCreate uncontested market space using value innovation instead of competing head-to-head. Use when the user mentions "blue ocean", "red ocean", "strategy canvas", "ERRC framework", "value innovation", "non-customers", "buyer utility map", "the market is too crowded", "how do we stand out", or "escape the price war". Also trigger when exploring a new market category, or finding underserved or non-customers. Covers the Four Actions Framework, Six Paths, buyer utility map, and value-cost trade-offs. For real strategy formulation and bad-strategy detection, see good-strategy-bad-strategy. For tech adoption strategy, see crossing-the-chasm. For product positioning, see obviously-awesome.
  • Aclean-architectureStructure software around the Dependency Rule: source code dependencies point inward from frameworks to use cases to entities. Use when the user mentions "architecture layers", "dependency rule", "ports and adapters (hexagonal)", "onion architecture", "screaming architecture", "where should business logic go", "decouple from the database", "swap the framework without a rewrite", or "keep business rules independent". Also trigger when deciding which layer code belongs in, isolating core logic from infrastructure, defining module boundaries, or debating whether the framework should call your code or the reverse. Covers component principles, boundaries, and SOLID. For code-level quality, see clean-code. For domain modeling, see domain-driven-design.
  • Aclean-architectureStructure software around the Dependency Rule: source code dependencies point inward from frameworks to use cases to entities. Use when the user mentions "architecture layers", "dependency rule", "ports and adapters (hexagonal)", "onion architecture", "screaming architecture", "where should business logic go", "decouple from the database", "swap the framework without a rewrite", or "keep business rules independent". Also trigger when deciding which layer code belongs in, isolating core logic from infrastructure, defining module boundaries, or debating whether the framework should call your code or the reverse. Covers component principles, boundaries, and SOLID. For code-level quality, see clean-code. For domain modeling, see domain-driven-design.
  • Aclean-architectureStructure software around the Dependency Rule: source code dependencies point inward from frameworks to use cases to entities. Use when the user mentions "architecture layers", "dependency rule", "ports and adapters (hexagonal)", "onion architecture", "screaming architecture", "where should business logic go", "decouple from the database", "swap the framework without a rewrite", or "keep business rules independent". Also trigger when deciding which layer code belongs in, isolating core logic from infrastructure, defining module boundaries, or debating whether the framework should call your code or the reverse. Covers component principles, boundaries, and SOLID. For code-level quality, see clean-code. For domain modeling, see domain-driven-design.

All agent skills → · MCP servers