Individual skill

tailwind-ui-refactor

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.

skills/.experimental/tailwind-ui-refactor/SKILL.md

Read pinned source

Source commit cf93c57cac89d6fc3e4194686000411567f5caf3

What was checked

Matches the observed repository HEAD: Yes
Scanner rules are current: No
Repository scan complete: No
Skill scan complete: Yes
Observed behavior: Not checked yet
Last checked: Nov 5, 2026

These are observations at the recorded commit, not a guarantee of safety. Review the source before running it.

Install this skill

Choose an agent in your Stack or copy a command below. Commands fetch the pinned commit and copy only this skill directory. Existing destinations are refused. Copying a command does not install anything.

An install command is unavailable: current rules, complete repository and skill scans, an eligible behavior level and a permitted license are required.

Repository context

Repository stars (not skill ratings): 222
Repository last updated: Aug 15, 2026
License: MIT

Observed agent integration: No specific integration evidence. Standard SKILL.md installation does not imply verified compatibility.

design Derived category
engineering Derived category
writing Derived category
design-interface Derived category

Files and excerpt

File metadata and permitted, redacted excerpts come from the recorded scan. Source links are pinned to that commit.

Browse files

SKILL.mdcore · 10,259 bytes
assets/templates/_template.mddoc · 666 bytes
metadata.jsonasset · 716 bytes
references/_sections.mddoc · 2,333 bytes
references/color-accessible-contrast.mddoc · 1,414 bytes
references/color-dark-gray-not-black.mddoc · 990 bytes
references/color-define-palette-upfront.mddoc · 1,068 bytes
references/color-grayscale-first.mddoc · 1,879 bytes
references/color-light-backgrounds-dark-text.mddoc · 1,308 bytes
references/color-saturated-grays.mddoc · 1,363 bytes
references/depth-interactive-elevation.mddoc · 1,048 bytes
references/depth-light-closer-dark-recedes.mddoc · 1,313 bytes
references/depth-overlap-layers.mddoc · 1,419 bytes
references/depth-shadow-scale.mddoc · 1,314 bytes
references/depth-shadow-vertical-offset.mddoc · 994 bytes
references/hier-button-hierarchy.mddoc · 1,260 bytes
references/hier-color-hierarchy-on-dark.mddoc · 1,402 bytes
references/hier-deemphasize-secondary.mddoc · 1,563 bytes
references/hier-icon-sizing.mddoc · 951 bytes
references/hier-label-value-pairs.mddoc · 1,972 bytes
references/hier-semantic-vs-visual.mddoc · 1,188 bytes
references/hier-size-weight-color.mddoc · 1,149 bytes
references/img-control-user-content.mddoc · 1,012 bytes
references/img-dont-scale-up-icons.mddoc · 1,301 bytes
references/img-empty-states.mddoc · 1,259 bytes
references/img-text-overlay.mddoc · 1,145 bytes
references/intent-audit-before-styling.mddoc · 2,174 bytes
references/intent-content-drives-layout.mddoc · 2,167 bytes
references/intent-match-context-fidelity.mddoc · 2,786 bytes
references/intent-match-existing-patterns.mddoc · 2,497 bytes
references/intent-progressive-disclosure.mddoc · 2,144 bytes
references/intent-reduce-cognitive-load.mddoc · 1,812 bytes
references/intent-remove-before-decorating.mddoc · 1,816 bytes
references/intent-simplify-over-decorate.mddoc · 2,214 bytes
references/polish-accent-borders.mddoc · 1,007 bytes
references/polish-border-radius-personality.mddoc · 1,272 bytes
references/polish-custom-bullets.mddoc · 1,256 bytes
references/polish-gradient-close-hues.mddoc · 1,190 bytes
references/polish-inner-shadow-images.mddoc · 1,095 bytes
references/sep-background-color-separation.mddoc · 1,233 bytes
references/sep-card-radio-buttons.mddoc · 2,280 bytes
references/sep-fewer-borders.mddoc · 1,330 bytes
references/sep-table-spacing-not-lines.mddoc · 2,133 bytes
references/space-dont-fill-screen.mddoc · 1,305 bytes
references/space-grids-not-required.mddoc · 1,335 bytes
references/space-mobile-first.mddoc · 1,888 bytes
references/space-relationship-proximity.mddoc · 1,615 bytes
references/space-relative-sizing-fails.mddoc · 1,466 bytes
references/space-start-generous.mddoc · 1,310 bytes
references/space-systematic-scale.mddoc · 1,120 bytes
references/type-align-numbers-right.mddoc · 1,953 bytes
references/type-font-weight-variety.mddoc · 1,194 bytes
references/type-letter-spacing.mddoc · 1,044 bytes
references/type-line-height-inverse.mddoc · 1,314 bytes
references/type-line-length.mddoc · 1,256 bytes
references/type-no-center-long-text.mddoc · 1,337 bytes

Read excerpt


# 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