# refactoring-ui

Adopt this skill: https://proskills.md/skills/other/jaywilburn-refactoring-ui-skill-skills-refactoring-ui

Page: https://proskills.md/skills/other/jaywilburn-refactoring-ui-skill-skills-refactoring-ui
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/refactoring-ui/SKILL.md
size: 8042
upstream: https://github.com/jaywilburn/refactoring-ui-skill/blob/main/skills/refactoring-ui/SKILL.md

```text
---
name: refactoring-ui
description: Comprehensive UI design guidance based on Refactoring UI principles covering design personality, color theory, layout strategy, visual hierarchy, typography, spacing, mobile-first responsive design, and writing copy that doesn't read like AI wrote it. Use this skill whenever the user is creating new pages, building components, making design additions or changes, reviewing UI code, asking about design decisions (colors, fonts, spacing, layout), writing or editing interface copy, or discussing visual improvements. Trigger for any design-related conversation including "how should this look", "what color", "font size", "spacing", "layout", "responsive", "mobile", "this copy", "headline", "button text", "microcopy", or when reviewing/critiquing existing interfaces.
---

# Refactoring UI Design System

## Core Philosophy

Design decisions should be made with intention, not decoration. Every visual choice—color, size, spacing, weight—communicates hierarchy and guides the user's attention. Start with too much whitespace, then remove it. Start with less contrast, then add it where needed.

Before writing any CSS, answer: **what should this feel like?** A financial dashboard and a children's learning app demand completely different visual treatments. The sections below move from strategic thinking (personality, color theory, layout strategy) down to tactical execution (spacing values, shadow syntax, animation timing).

---

# Design Thinking

## Design Personality & Tone

Every interface has a personality whether you choose one or not. Choosing intentionally is the difference between a design that feels right and one that feels generic.

### The Personality Spectrum

Plot your design on two axes:

- **Formal ↔ Casual**: How structured and serious vs relaxed and approachable
- **Reserved ↔ Expressive**: How restrained and minimal vs bold and vibrant

Four quadrants:

| | Reserved | Expressive |
|---|---|---|
| **Formal** | Banking, legal, enterprise, government | Luxury brands, high-end retail, fashion |
| **Casual** | Developer tools, documentation, utilities | Gaming, social apps, children's education |

### Mapping Design Signals to Personality

Each visual lever pushes the design toward a quadrant:

- **Border-radius**: 2-4px (formal) → 8-12px (moderate) → 16px+ (casual). Match to personality—don't default to max.
- **Font choice**: Geometric sans like Inter/Roboto (modern, neutral), humanist sans like Source Sans/Nunito (friendly, approachable), serif like Merriweather/Playfair (traditional, authoritative), monospace accents (technical, developer-oriented)
- **Color saturation**: Low/muted (reserved) → high/vibrant (expressive). See Color Theory section.
- **Whitespace density**: Generous (formal, premium) → tight (casual, energetic, data-dense)
- **Shadow style**: Subtle and diffused (reserved) → dramatic with strong offsets (expressive). Or no shadows at all for minimal/flat designs.
- **Imagery style**: Photography (authentic, serious) → illustration (approachable, playful) → icons only (utilitarian, technical)

### Domain Personality Anchors

Use these as starting points, not rigid rules. The specific product and audience always override.

**Fintech / Banking**: Formal + reserved. Muted blues and greens, small border-radius (4-6px), geometric sans-serif, dense data layouts, minimal decoration. Trust is communicated through restraint.

**Healthcare / Medical**: Formal + reserved. Calming blues, greens, or teals. Generous whitespace, clear section breaks, large touch targets. Accessibility is non-negotiable. Avoid anything that feels playful—patients want confidence.

**E-commerce**: Varies by market segment. Budget/mass-market = casual + expressive (bright colors, large CTAs, energy). Luxury = formal + expressive (muted palette, serif headings, dramatic whitespace, restrained CTAs).

**Creative Tools**: Casual + expressive. Bold accent colors against neutral backgrounds. Asymmetric layouts, personality in empty states and onboarding. The tool should feel inspiring, not corporate.

**Education**: K-12 = casual + expressive (warm colors, rounded shapes, friendly type, illustrations). Professional/adult learning = casual + reserved (clean, focused, minimal distraction from content).

**SaaS Dashboards**: Casual + reserved. Neutral base palette with functional color for data and states. Dense but organized. The interface should disappear—users are here for the data, not the design.

**Media / Content**: News = formal + reserved (classic typography, structured grids, minimal color). Entertainment = casual + expressive (bold imagery, vivid color, immersive layouts).

**Developer Tools**: Casual + reserved. Monospace accents, dark mode preference, minimal decoration. High information density done well. Let the content breathe but don't waste space on decoration.

### The "Who Is This For?" Checklist

Before making any visual choices, answer these:

1. **Who is the primary user?** (Age, technical literacy, context of use)
2. **What emotional response should this evoke?** (Trust, excitement, calm, urgency)
3. **What builds trust in this domain?** (Restraint? Polish? Friendliness? Data density?)
4. **What do competitors look like?** (And how should this differentiate without being alien?)
5. **Which personality quadrant does this land in?**

---

## Color Theory & Psychology

The existing Color section below covers *how* to build palettes with HSL and manage shades. This section covers *which* colors to choose and *why*.

### Color Wheel Fundamentals

Colors divide into warm and cool:

- **Warm side** (red, orange, yellow): These colors advance—they feel closer, more energetic, more urgent. Use them for elements that need attention.
- **Cool side** (blue, green, purple): These recede—they feel farther, calmer, more stable. Use them for backgrounds, containers, and trust signals.

This warm/cool dynamic is a fundamental tool. A dashboard with a cool blue background and warm orange alert badges creates natural visual hierarchy through color temperature alone.

### Color Harmony Schemes

How you combine colors determines the overall feel:

**Analogous** (adjacent hues on the wheel, e.g., blue + blue-green + green):
Cohesive and calm. Low internal contrast. Best for interfaces that should feel unified and serene—content apps, healthcare, meditation. Risk: can feel monotonous without a neutral or accent to break it up.

**Complementary** (opposite hues, e.g., blue + orange):
High energy and contrast. Best for elements that need to pop—CTAs against their background, marketing pages, attention-grabbing moments. Risk: can feel harsh if both colors are at full saturation. Mute one side.

**Split-complementary** (one hue + the two hues adjacent to its complement):
Vibrant but more balanced than straight complementary. Best for designs that need variety without chaos. Gives you a clear primary with two supporting accents.

**Triadic** (three equidistant hues, e.g., red + yellow + blue):
Vibrant and balanced. Best for playful, creative apps. Use with restraint—one dominant, two as accents at lower saturation. Full-strength triadic is overwhelming.

For most product interfaces, **analogous with one complementary accent** is the safest and most professional starting point.

### Color Psychology by Hue

Each hue carries associations. Use these as starting points, then adjust for your specific domain and audience:

**Blue**: Trust, stability, calm, professionalism. The most universally safe choice—which is also why it's overused. Finance, healthcare, enterprise, social media. If you reach for blue, make sure it's because it fits, not because it's default.

**Green**: Growth, health, money, nature, success. Fintech, wellness, sustainability, positive states. Pairs well with blue for trust + growth.

**Red**: Urgency, energy, passion, danger. Food and restaurant apps, entertainment, sale CTAs, error states. Use sparingly in interfaces—a litt
```

## File: README.md
upstream: https://github.com/jaywilburn/refactoring-ui-skill/blob/main/README.md

````text
# Refactoring UI Design Skill

An opinionated agent skill for building professional UI without a designer, based on [Refactoring UI](https://www.refactoringui.com/) principles by Adam Wathan & Steve Schoger.

## What This Skill Covers

### Design Thinking
- **Design Personality & Tone** — Formal/casual, reserved/expressive framework with domain anchors
- **Color Theory & Psychology** — Color wheel, harmony schemes, hue psychology, saturation as a design lever
- **Layout Decision Framework** — Content-first layout selection, density spectrum, domain layout profiles
- **Breaking AI Defaults** — Named anti-patterns (purple gradients, SaaS templates) with concrete alternatives
- **Component Variation** — Same component, different design based on context

### Execution
- **Visual Hierarchy** — Size, weight, and color as tools for emphasis
- **Typography** — Modular scales, line height, letter spacing, weight strategy
- **Color** — HSL palettes, UI states, warm/cool grays, accessibility
- **Spacing** — Consistent scales, proximity relationships
- **Layout** — Max-width constraints, breathing room, alignment
- **Mobile-First** — Breakpoint strategy, touch targets, responsive typography
- **Depth & Shadows** — Elevation systems, natural shadow direction
- **Dark Mode** — Systematic approach (not just inverted colors)
- **Form Patterns** — Input styling, labels, errors, field grouping
- **Accessibility** — Focus states, motion sensitivity, semantic HTML
- **Animation** — Timing, easing, what to animate
- **Design Audit Checklist** — Structured review framework

## Installation

### Claude Code / Warp / Cursor

```bash
# Clone to your skills directory
git clone https://github.com/jaywilburn/refactoring-ui-skill.git ~/.agents/skills/refactoring-ui
```

Or copy `skills/refactoring-ui/SKILL.md` to your preferred skills location:
- Claude Code: `~/.claude/skills/refactoring-ui/`
- Codex CLI: `~/.codex/skills/refactoring-ui/`
- Cursor: `.cursor/skills/refactoring-ui/`

### Via npx (once indexed)

```bash
npx skills add jaywilburn/refactoring-ui-skill/refactoring-ui
```

## When It Triggers

The skill activates when you're:
- Creating new pages or components
- Making design additions or changes
- Asking about colors, fonts, spacing, layout
- Discussing "how should this look"
- Reviewing or critiquing existing interfaces
- Working on responsive/mobile design

## Example Prompts

```
"How should I style this card component?"
"What colors should I use for this dashboard?"
"Make this form look more professional"
"Review this page layout"
"Help me set up a consistent spacing system"
```

## Differentiators

Unlike other UI design skills, this one fights AI-generated sameness head-on:

1. **Design Thinking Layer** — Strategic decisions (personality, color theory, layout strategy) before tactical execution
2. **Anti-AI-Sameness** — Explicitly names and provides alternatives to common AI defaults (purple gradients, SaaS templates, uniform card grids)
3. **Color Theory & Psychology** — Full color wheel, harmony schemes, hue psychology, and saturation strategies — not just "pick a palette"
4. **Domain-Aware Design** — Personality profiles and layout patterns for fintech, healthcare, e-commerce, creative tools, dev tools, and more
5. **Component Variation** — Cards, navs, buttons, and tables styled differently based on context, not copied from a template
6. **Dark Mode Design** — Surface hierarchy, saturation shifts, proper dark palettes
7. **Form Design Patterns** — Complete form styling guidance
8. **Accessibility Section** — Beyond contrast ratios (focus, motion, semantics)
9. **Animation Principles** — Timing, easing, what to animate
10. **Design Audit Checklist** — Structured review process including personality and intent checks

## Credits

Based on [Refactoring UI](https://www.refactoringui.com/) by Adam Wathan & Steve Schoger. 

**This skill does not replace the book.** If you want to truly understand UI design as a developer, buy and read Refactoring UI — it's one of the most practical design resources available.

## License

MIT
````
