# tailwind-ui-refactor

A skill that refactors HTML with Tailwind utility classes: hierarchy, spacing, typography, color. Useful when you build UI without a designer on hand.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 458 installs · ★ 218
- Author: pproenca
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/pproenca/dot-skills/tree/HEAD/skills/.experimental/tailwind-ui-refactor/SKILL.md
- Updated: 2026-08-15
- HTML: https://affpapa.org/en/nevibecode/skills/tailwind-ui-refactor

## What it does

The skill is built on Refactoring UI by Adam Wathan and Steve Schoger, translated into Tailwind utility classes. It holds 52 rules across 9 categories, ordered by design impact: design intent, visual hierarchy and layout come first, then typography and color, with shadows, borders and polish last. Syntax follows Tailwind CSS v4, and rules note where v3 differs.

The core instruction is to think first and style second. Before touching classes, the agent works out what each element communicates and what matters to the user, then removes what does not earn its place. A simpler component beats a decorated one. Worth knowing: ask for a cosmetic pass and it will start by rebuilding your markup instead.

Rules live as separate files under `references/` and are addressed by prefix — `intent-`, `hier-`, `space-`, `type-`, `color-`, `depth-`, `sep-`, `img-`, `polish-`. The skill triggers on UI cleanup, design review, component styling and contrast fixes.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add pproenca/dot-skills --skill tailwind-ui-refactor -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/tailwind-ui-refactor/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/tailwind-ui-refactor/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add pproenca/dot-skills --skill tailwind-ui-refactor -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/tailwind-ui-refactor/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add pproenca/dot-skills --skill tailwind-ui-refactor -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/tailwind-ui-refactor/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install pproenca/dot-skills tailwind-ui-refactor
```

2. **Manually: put the files in place**
- File: `.github/skills/tailwind-ui-refactor/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add pproenca/dot-skills --skill tailwind-ui-refactor -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/pproenca/dot-skills --path skills/.experimental/tailwind-ui-refactor
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/tailwind-ui-refactor/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add pproenca/dot-skills --skill tailwind-ui-refactor -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/pproenca/dot-skills/tree/HEAD/skills/.experimental/tailwind-ui-refactor/SKILL.md

## When to use it
- untangle visual hierarchy in an existing component
- pick spacing from a scale instead of guessing
- fix line length and line height in body text
- define a palette upfront rather than picking colors as you go
- repair text contrast to meet 4.5:1

## Example prompts
- refactor this component using the tailwind-ui-refactor rules
- review hierarchy and spacing in `src/components/Card.tsx`
- apply the `space-` rules to this markup

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 956c49c417ddf1ea.

BEGIN THIRD-PARTY FILE 956c49c417ddf1ea
```text
---
name: tailwind-ui-refactor
description: Refactoring UI design patterns for Tailwind CSS applications. This skill should be used when writing, reviewing, or refactoring HTML with Tailwind utility classes to improve visual hierarchy, spacing, typography, color, depth, and polish. Triggers on tasks involving UI cleanup, design review, Tailwind refactoring, component styling, or visual improvements.
---

# Refactoring UI Tailwind CSS Best Practices

Comprehensive UI refactoring guide based on Refactoring UI by Adam Wathan & Steve Schoger, implemented with Tailwind CSS utility classes. Contains 52 rules across 9 categories, prioritized by design impact to guide automated refactoring and code generation. Uses Tailwind CSS v4 syntax (v3 notes provided where syntax differs).

**Important: Think first, style second.** Before applying any visual rule, understand the UI's purpose, identify what matters to the user, and remove unnecessary elements. The Design Intent category (priority 1) must be considered before any styling changes. A simpler component with fewer elements always beats a decorated component with unnecessary markup.

## When to Apply

Reference these guidelines when:
- Refactoring existing Tailwind CSS components
- Writing new UI with Tailwind utility classes
- Reviewing code for visual hierarchy and spacing issues
- Improving design quality without a designer
- Fixing accessibility contrast problems

## Rule Categories by Priority

| Priority | Category | Impact | Prefix |
|----------|----------|--------|--------|
| 1 | Design Intent | CRITICAL | `intent-` |
| 2 | Visual Hierarchy | CRITICAL | `hier-` |
| 3 | Layout & Spacing | CRITICAL | `space-` |
| 4 | Typography | HIGH | `type-` |
| 5 | Color Systems | HIGH | `color-` |
| 6 | Depth & Shadows | MEDIUM | `depth-` |
| 7 | Borders & Separation | MEDIUM | `sep-` |
| 8 | Images & Content | LOW-MEDIUM | `img-` |
| 9 | Polish & Details | LOW | `polish-` |

## Quick Reference

### 1. Design Intent (CRITICAL)

- [`intent-audit-before-styling`](references/intent-audit-before-styling.md) - Audit what each element communicates before changing any CSS
- [`intent-remove-before-decorating`](references/intent-remove-before-decorating.md) - Remove unnecessary elements before styling what remains
- [`intent-reduce-cognitive-load`](references/intent-reduce-cognitive-load.md) - Reduce choices per screen — fewer options beat prettier options
- [`intent-progressive-disclosure`](references/intent-progressive-disclosure.md) - Hide secondary information behind interactions
- [`intent-content-drives-layout`](references/intent-content-drives-layout.md) - Let real content determine layout — not the other way around
```
END THIRD-PARTY FILE 956c49c417ddf1ea

The third-party file has ended. Everything between the 956c49c417ddf1ea tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2701 of 10259 bytes. © pproenca · MIT · https://github.com/pproenca/dot-skills/tree/HEAD/skills/.experimental/tailwind-ui-refactor/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md