What is the Refactoring UI skill?
The Refactoring UI skill is an agent skill by jaywilburn based on the Refactoring UI book. It tells an AI coding agent how to handle visual hierarchy, typography, color, spacing, shadows, dark mode, forms and animation, and it names AI default patterns such as purple gradients and gives alternatives.
It is an opinionated agent skill for building professional UI without a designer, based on the Refactoring UI principles by Adam Wathan and Steve Schoger. The README says it does not replace the book and recommends reading it.
The skill is organised in two layers. A design thinking layer makes strategic choices first, such as personality, color theory and layout. An execution layer then covers hierarchy, type, spacing, depth and forms.
What changes in your agent's output
- Emphasis comes from size, weight and color rather than from adding more boxes or borders.
- Palettes are built in HSL with UI states, and gray is chosen as warm or cool to match the product.
- Layouts are picked from the content and the domain, and the same component is styled differently by context.
- Dark mode is treated as a system with surface hierarchy and saturation shifts, not inverted colors.
- Named AI defaults such as purple gradients, SaaS templates and uniform card grids get concrete alternatives.
Who it is for
Best for
- Developers who ship UI without a designer and want an agent to apply sound spacing, type and color rules.
- Teams who see the same generic look in every agent-built page and want a counterweight.
- Anyone who wants a design audit checklist, paired with a reviewer like critique or a full-page skill like ui-ux-pro-max.
Not for
- People who want measured checks. The README describes guidance, not an automated audit or a browser test.
- Teams with a strict brand system, where the brand rules should win over general taste.
- Readers hoping to skip the book. The README says plainly that it does not replace it.
Use it with UiChemy
Run the skill on a page design before you convert it, then use UiChemy Figma to WordPress to turn the finished design into an editable page. Click Get Started on uichemy.com.
How to install Refactoring UI Skill: Visual Design Rules for AI Agents
git clone https://github.com/jaywilburn/refactoring-ui-skill.git ~/.agents/skills/refactoring-uiThe README also shows an npx skills route, marked as available once the skill is indexed.Clone to your skills folder
Run the git clone command above, which places the skill in the shared agents skills directory.
Or copy the file
Copy skills/refactoring-ui/SKILL.md into your tool's skills location. The README lists .claude/skills for Claude Code, .codex/skills for Codex CLI and .cursor/skills in a Cursor project.
Ask for design help
The skill activates when you create pages or components, ask about colors, fonts, spacing or layout, or ask for a design critique.
Check that it loaded
Ask the agent how to style a card component. The answer should reason about hierarchy, spacing and color and avoid a purple gradient default.
Key features
- Design personality and toneA formal or casual, reserved or expressive framework with domain anchors, applied before any styling decision.
- Color theory and psychologyColor wheel, harmony schemes, hue psychology and saturation as a design lever, with HSL palettes and UI states.
- Layout decision frameworkContent-first layout selection, a density spectrum and layout profiles for domains such as fintech, healthcare, e-commerce and dev tools.
- Breaking AI defaultsNames patterns like purple gradients and SaaS templates and gives concrete alternatives, which the README treats as the main differentiator.
- Visual hierarchySize, weight and color are used as emphasis tools to show what matters on the page.
- TypographyModular scales, line height, letter spacing and a weight strategy.
- Spacing and layoutConsistent spacing scales, proximity relationships, max-width limits and alignment.
- Depth, shadows and dark modeElevation systems with natural shadow direction, and a systematic approach to dark palettes.
- Forms, accessibility and animationInput styling, labels, errors and grouping, plus focus states, motion sensitivity, semantic HTML, timing and easing.
- Design audit checklistA structured review that includes personality and intent checks.
Frequently asked questions
What is the Refactoring UI skill?
It is a SKILL.md by jaywilburn, based on the Refactoring UI book, that guides an AI coding agent on hierarchy, typography, color, spacing, depth, dark mode, forms, accessibility and animation. It also names common AI design defaults and offers alternatives.
How do I install the Refactoring UI skill?
Clone the repository into your agents skills folder with git, or copy skills/refactoring-ui/SKILL.md into the skills folder your tool reads. The README lists locations for Claude Code, Codex CLI and Cursor, plus an npx route marked for later.
Is it made by the authors of Refactoring UI?
No. The README credits Adam Wathan and Steve Schoger as the source of the principles and says the skill does not replace the book. It is an independent skill by jaywilburn built on those ideas.
When does the skill activate?
The README says it activates when you create new pages or components, make design changes, ask about colors, fonts, spacing or layout, discuss how something should look, review an interface or work on responsive and mobile design.
Does it help with generic AI looking pages?
That is its stated aim. It names defaults such as purple gradients, SaaS templates and uniform card grids, and varies components by context. For a similar angle see design-taste-frontend, which is a different skill with its own rules.
Does it cover dark mode and forms?
Yes. The README lists a systematic dark mode approach with surface hierarchy and saturation shifts, and form patterns covering input styling, labels, errors and field grouping. Accessibility is covered for focus states, motion sensitivity and semantic HTML.
Is it free to use?
Yes, the repository is MIT licensed. It is a single skill file with no dependencies, though the README gives no install count or benchmark, so judge it by running it on one of your own pages.
What are the limits of this skill?
It is guidance, not a measured audit, so it does not run a browser or test contrast. Pair it with web-accessibility-skill for WCAG checks and a manual review for brand fit.


