Agent skill

Tailwind UI Refactor

by pproenca in pproenca/dot-skills

Refactoring UI design patterns for Tailwind CSS applications.

MITAuto-check passedFrontend & Design

Install Tailwind UI Refactor

skills CLI
$ npx skills add pproenca/dot-skills --skill tailwind-ui-refactor -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install pproenca/dot-skills tailwind-ui-refactor --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/pproenca/dot-skills.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/.experimental/tailwind-ui-refactor .claude/skills/tailwind-ui-refactor && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
tailwind-ui-refactor
GitHub stars
214
Token cost
~2.6k tokens
SKILL.md length
833 words
Files
56 (incl. references, assets)
Skills in repo
182
Repo updated
First seen
Licence
MIT

At a glance

Refactoring UI design patterns for Tailwind CSS applications.

  • Works in 9 steps: Design Intent (CRITICAL) → Visual Hierarchy (CRITICAL) → Layout & Spacing (CRITICAL) → …
  • Tasks involving UI cleanup
  • SKILL.md covers When to Apply, Rule Categories by Priority, Quick Reference and Scope & Limitations, plus 2 more sections
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

Tailwind UI Refactor is an agent skill from pproenca/dot-skills. 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.

Its SKILL.md is about 2.6k tokens, which your agent loads only when the skill is triggered. The skill folder holds 58 other files, including reference files and assets (for example `assets/templates/_template.md`, `metadata.json` and `references/_sections.md`).

It sits in Frontend & Design, covering CSS and styling, Refactoring and Typography. It works with Tailwind CSS. The repository describes itself as: A collection of AI agent skills following the Agent Skills open format. The licence is MIT.

When your agent uses it

  • Tasks involving UI cleanup
  • Tailwind refactoring
  • Component styling
  • Visual improvements

Example prompts

  • “/tailwind-ui-refactor”

Workflow steps

9 steps, taken from the step headings in SKILL.md.

  1. Design Intent (CRITICAL)
  2. Visual Hierarchy (CRITICAL)
  3. Layout & Spacing (CRITICAL)
  4. Typography (HIGH)
  5. Color Systems (HIGH)
  6. Depth & Shadows (MEDIUM)
  7. Borders & Separation (MEDIUM)
  8. Images & Content (LOW-MEDIUM)
  9. Polish & Details (LOW)

What it can do on your machine

Read from SKILL.md and the folder at commit cf93c57. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md.

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Tailwind UI Refactor loads about 2.6k tokens when it runs, and up to ~22k if it reads all its reference files. Until then it costs about 95 tokens; SKILL.md has 833 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~95
When it runs · the whole SKILL.md, loaded when a task matches
~2.6k
With references · SKILL.md plus every file in references/, read only if the agent opens them
~22k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from pproenca/dot-skills at commit cf93c57, republished under its MIT licence (© pproenca). 833 words, ~2,559 tokens.

Download SKILL.mdSave it as .claude/skills/tailwind-ui-refactor/SKILL.md (or your agent's skills folder). This skill also uses 55 other files; get the full folder from GitHub.
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

PriorityCategoryImpactPrefix
1Design IntentCRITICALintent-
2Visual HierarchyCRITICALhier-
3Layout & SpacingCRITICALspace-
4TypographyHIGHtype-
5Color SystemsHIGHcolor-
6Depth & ShadowsMEDIUMdepth-
7Borders & SeparationMEDIUMsep-
8Images & ContentLOW-MEDIUMimg-
9Polish & DetailsLOWpolish-

Quick Reference

1. Design Intent (CRITICAL)
2. Visual Hierarchy (CRITICAL)
3. Layout & Spacing (CRITICAL)
4. Typography (HIGH)
5. Color Systems (HIGH)
Show full SKILL.md (315 more words)Show less
6. Depth & Shadows (MEDIUM)
7. Borders & Separation (MEDIUM)
8. Images & Content (LOW-MEDIUM)
9. Polish & Details (LOW)

Scope & Limitations

This skill covers layout, hierarchy, spacing, color, and polish based on Refactoring UI principles. It does NOT cover:

  • Font selection & pairing — choosing distinctive typefaces, avoiding generic AI defaults (Inter, Arial, system-ui), or pairing display + body fonts
  • Animation & motion — meaningful transitions, micro-interactions, page load sequences, or scroll-triggered reveals
  • Creative direction — establishing an aesthetic vision, choosing a tone (minimal, maximalist, brutalist, etc.), or differentiating from generic "AI slop" aesthetics
  • Spatial composition — asymmetric layouts, grid-breaking elements, or unconventional visual flow

For these concerns, pair this skill with a design-thinking or frontend-design skill that covers creative direction and aesthetic execution.

How to Use

Read individual reference files for detailed explanations and code examples:

Reference Files

FileDescription
references/_sections.mdCategory definitions and ordering
assets/templates/_template.mdTemplate for new rules
metadata.jsonVersion and reference information

© pproenca, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 55 other files (references, assets) in skills/.experimental/tailwind-ui-refactor of pproenca/dot-skills.

  • SKILL.md
  • assets/templates/_template.md
  • metadata.json
  • references/_sections.md
  • references/color-accessible-contrast.md
  • references/color-dark-gray-not-black.md
  • references/color-define-palette-upfront.md
  • references/color-grayscale-first.md
  • references/color-light-backgrounds-dark-text.md
  • references/color-saturated-grays.md
  • references/depth-interactive-elevation.md
  • references/depth-light-closer-dark-recedes.md
  • references/depth-overlap-layers.md
  • references/depth-shadow-scale.md
  • references/depth-shadow-vertical-offset.md
  • references/hier-button-hierarchy.md
  • references/hier-color-hierarchy-on-dark.md
  • references/hier-deemphasize-secondary.md
  • … and 38 more

Open the folder on GitHubat commit cf93c57

Compare with similar skills

Tailwind UI Refactor next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Tailwind UI Refactor compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Tailwind UI Refactor this skillpproenca/dot-skills214—~2.6kAutomated safety check: PassMIT
Agentos UI UXSapienXai/AgentOS118—~4.4kAutomated safety check: PassMIT
UI UX Pro MaxOhh-889/skyroc79526 repos~3.6kAutomated safety check: NotesMIT
UI UX Pro Maxshobcoder/shob577—~3.7kAutomated safety check: PassMIT
Design Craftkipperacademy/skillpper113—~3.8kAutomated safety check: PassNone
Refactoring UIwondelai/skills2.4k—~3.9kAutomated safety check: PassMIT

Similar skills

  • Agentos UI UX

    SapienXai/AgentOS

    Design, review, or implement AgentOS UI and UX work using the project’s operator-console visual system.

    118 GitHub stars~4.4k tokensUpdated 4 days ago
    Frontend & DesignAuto-check passed
  • UI UX Pro Max

    Ohh-889/skyroc

    UI/UX design intelligence. An agent skill from Ohh-889/skyroc.

    795 GitHub starsUsed in 26 repos~3.6k tokens
    Frontend & DesignAuto-check: notes
  • UI UX Pro Max

    shobcoder/shob

    UI/UX design intelligence expert for web and mobile applications.

    577 GitHub stars~3.7k tokensUpdated 19 days ago
    Frontend & DesignAuto-check passed
  • Design Craft

    kipperacademy/skillpper

    Opinionated product-design skill for building, reviewing, polishing, and iterating on landing pages, apps, dashboards, AI products, design systems, and brand touchpoints.

    113 GitHub stars~3.8k tokensUpdated yesterday
    Frontend & DesignAuto-check passed
  • Refactoring UI

    wondelai/skills

    Audit and fix visual hierarchy, spacing, color, and depth in web UIs.

    2.4k GitHub stars~3.9k tokensUpdated 27 days ago
    Frontend & DesignAuto-check passed
  • Create Website

    wondelai/skills

    Guided journey from a blank page to a live, high-converting website, built message-first, then design, then conversion.

    2.4k GitHub stars~5.7k tokensUpdated 27 days ago
    Frontend & DesignAuto-check passed

More from pproenca/dot-skills

All 182 skills in this repo
  • Audio Voice Recovery

    pproenca/dot-skills

    Audio forensics and voice recovery guidelines for CSI-level audio analysis.

    214 GitHub stars~3.3k tokensUpdated 1 mo ago
    Auto-check passed
  • Codemod React Pipeline

    pproenca/dot-skills

    Guided, scripted pipeline for running JSX/TSX/React codemods safely across large legacy codebases.

    214 GitHub stars~1.6k tokensUpdated 1 mo ago
    Auto-check passed
  • Dev Rfc

    pproenca/dot-skills

    Create well-structured RFCs and technical proposals for software projects.

    214 GitHub stars~3.8k tokensUpdated 1 mo ago
    Auto-check passed
  • Dx Harness

    pproenca/dot-skills

    Developer-experience friction auditing and fixing — slow onboarding, repeated manual setup steps, missing bootstrap/reset/seed scripts, undiscoverable conventions.

    214 GitHub stars~1.5k tokensUpdated 1 mo ago
    Auto-check passed
  • Language Spec Author

    pproenca/dot-skills

    Turn a rough idea for a language into a complete, implementable specification — a DSL, query, config/data, template, or protocol language — by interviewing the author dimension by dimension until…

    214 GitHub stars~2.4k tokensUpdated 1 mo ago
    Auto-check passed
  • Python Pep Author

    pproenca/dot-skills

    Drafting Python Enhancement Proposals (PEPs) — proposing a Python language feature, a standard library change, an interoperability standard, or an informational/process document for the Python…

    214 GitHub stars~2.1k tokensUpdated 1 mo ago
    Auto-check passed

Works with

Questions about Tailwind UI Refactor

What does Tailwind UI Refactor do?

Refactoring UI design patterns for Tailwind CSS applications. Tailwind UI Refactor is an agent skill from pproenca/dot-skills. Refactoring UI design patterns for Tailwind CSS applications.

When should I use Tailwind UI Refactor?

Tailwind UI Refactor fits situations like: tasks involving UI cleanup; tailwind refactoring; component styling; visual improvements.

How do I install Tailwind UI Refactor in Claude Code?

Run `npx skills add pproenca/dot-skills --skill tailwind-ui-refactor -a claude-code`. Or copy the skill folder (skills/.experimental/tailwind-ui-refactor in pproenca/dot-skills) into .claude/skills/tailwind-ui-refactor in your project. Claude Code loads it when a task matches its description.

How do I install Tailwind UI Refactor in Codex?

Run `npx skills add pproenca/dot-skills --skill tailwind-ui-refactor -a codex`. Or copy the skill folder (skills/.experimental/tailwind-ui-refactor in pproenca/dot-skills) into .agents/skills/tailwind-ui-refactor in your project. Codex loads it when a task matches its description.

Can I use Tailwind UI Refactor in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add pproenca/dot-skills --skill tailwind-ui-refactor -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/tailwind-ui-refactor, .gemini/skills/tailwind-ui-refactor, .github/skills/tailwind-ui-refactor and .opencode/skills/tailwind-ui-refactor in your project.

What does Tailwind UI Refactor need to run?

SKILL.md names no scripts, command-line tools or credentials: Tailwind UI Refactor is instructions for the agent only.

Does Tailwind UI Refactor access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Tailwind UI Refactor safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Tailwind UI Refactor use?

Tailwind UI Refactor is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Tailwind UI Refactor use?

About 2.6k tokens (SKILL.md is roughly 10k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 20k tokens, read only when the agent opens those files.

What are the alternatives to Tailwind UI Refactor?

Skills that share tags, products or a category with Tailwind UI Refactor: Agentos UI UX (SapienXai/AgentOS, 118 stars), UI UX Pro Max (Ohh-889/skyroc, 795 stars), UI UX Pro Max (shobcoder/shob, 577 stars) and Design Craft (kipperacademy/skillpper, 113 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Tailwind UI Refactor?

pproenca (a GitHub user) maintains it in pproenca/dot-skills, which has 214 GitHub stars. The repository holds 182 skills in this directory. The repository was last updated on August 15, 2026.

Source: pproenca/dot-skills on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.