⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

version unknown

refactoring-ui

jaywilburn@jaywilburn⭐ 108 stars· last commit 5mo ago· 0 open issues

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.

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

—/10

// RATINGS

⭐GitHub Stars
⭐⭐⭐ 108 on GitHubGitHub ↗

Popular

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// README

Refactoring UI Design Skill

An opinionated agent skill for building professional UI without a designer, based on Refactoring UI 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

# 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)

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 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

// HOW IT'S BUILT

// FILES

2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • skills/refactoring-ui/SKILL.md7.9 KBupstream ↗
    ---
    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
  • README.mdupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/jaywilburn-refactoring-ui-skill-skills-refactoring-ui.md

// REPO STATS

108 stars
0 open issues
Last commit: 5mo ago