iuryescano/refactoring-ui

This project packages up an unofficial Agent Skill inspired by the book Refactoring UI by Steve Schoger and Adam Wathan. It is meant to be used by AI coding agents, such as Codex, Claude Code, Cursor, or Kilo Code, to help them improve the visual design of web apps, dashboards, forms, product screens, landing pages, and component libraries. The project is clear that it is not affiliated with the book's authors and does not copy the book's text, it turns that general visual refactoring mindset into its own original, Markdown-based instructions for AI agents. The skill focuses on diagnosing a UI's visual communication first, then making targeted improvements to things like hierarchy, spacing, grouping, typography, which actions get visual priority, color, depth, use of imagery, interface states, and general finishing polish. The repository is organized into a main playbook file that an agent reads before doing UI work, a detailed checklist of visual design heuristics, a set of concrete recipes for fixing common UI problems, and an optional metadata file for OpenAI or Codex-style skill interfaces. Installing it mostly means copying this folder into whichever directory your coding agent uses for skills, or simply pointing any capable agent at the main playbook file and asking it to follow those instructions while working on a UI task. The stated design philosophy behind the skill favors improving clarity before adding decoration, reusing whatever design system already exists in a project rather than inventing new styles, making the primary action and main object of a screen obvious, preferring small targeted visual changes over full rewrites, and checking that the result still works responsively with good contrast and interaction states. The project is released under the MIT license.