UX Audit

Give your AI coding assistant a design eye.

A skill that teaches Claude Code, Cursor, Codex, and Windsurf how to think about UI/UX — so the interfaces they generate aren’t just functional, but well-designed.

12 design principles. 13 reference docs. 7 component checklists. Two modes: guide (build it right) and review (audit what exists).

---

Before / After

Without the skill, AI assistants generate functional but flat UI. With it, they produce interfaces with hierarchy, feedback, accessibility, and intent.

A delete confirmation — without the skill:

  Are you sure you want to delete?
  Yes
  No

No specifics. No consequence framing. “Yes/No” labels. User can’t tell what they’re losing.

With the skill:

<dialog role="dialog" aria-modal="true" aria-labelledby="delete-title"
  class="max-w-md rounded-xl p-6 shadow-lg">
  Delete "Q4 Report"?
  
    This will permanently delete the report and 12 comments. This can't be undone.
  
  

Names what’s being deleted. States the consequence. Action-specific button labels. Accessible markup. Focus styles. Destructive action visually distinct.

A loading state — without the skill:

{loading ?  : }

Spinner replaces all content. Layout jumps when data arrives.

With the skill:

Skeleton preserves layout. No content shift. User sees the page is loading, not broken.

---

Two Modes

flowchart LR
    A["Describe what you're building"] --> B{"UX Audit"}
    C["Share existing UI"] --> B
    B -->|Guide| D["Principles + checklists for your surface"]
    B -->|Review| E["P0/P1/P2 findings with fixes"]

Guide Mode

Tell it what you’re building. Get back tailored principles with do/don’t code examples.

"I'm building a settings page for a SaaS dashboard. Apply the ux-audit skill."

You get: settings grouped by mental model, help text layered by severity, accessible toggles with visible labels, inline validation, and a component checklist for the surface. Full example →

Review Mode

Share a screenshot, mock, HTML, or PR. Get back a structured audit.

"Review this onboarding flow. Use the ux-audit skill in review mode."

You get: prioritized findings (P0/P1/P2), root-cause diagnosis (gulf of execution, cognitive overload, accessibility failure), implementable fixes, and a verification checklist. Full example →

How long does a review take?

Time depends on complexity and the number of findings. Guide mode is faster; review mode is more thorough.

---

Install

Quick install (recommended)

Interactive installer — detects your agent and sets everything up:

curl -sSL https://raw.githubusercontent.com/narenkatakam/ux-audit/main/install.sh | bash

Or clone and run directly:

git clone https://github.com/narenkatakam/ux-audit.git
cd ux-audit && ./install.sh

Per-agent install

Try without installing

Paste these 5 rules into your AI assistant’s system prompt to test the difference:

1. No emoji as UI icons — use a proper icon set.
2. One primary CTA per screen, identifiable in 3 seconds.
3. Cover all states: loading, empty, error, success.
4. WCAG 2.1 AA contrast minimum on all text.
5. Spacing: 4px base unit, tight within groups, loose between.

If that changes how your AI builds UI, install the full skill.

---

Usage

Once installed, just ask naturally:

"I'm building a dashboard for monitoring API usage. Apply the ux-audit skill."
"Review this component for UX issues. Use the ux-audit skill in review mode."
"Check the accessibility of this form against the ux-audit skill."
"Generate a settings page. Follow the ux-audit principles."
"I'm building a modal for user deletion. Apply the ux-audit skill."

---

What’s Inside

Explore the interactive coverage map →

12 core principles (SKILL.md)

13 reference docs (references/)

Deep-dive guidance on: system principles, psychology, accessibility, responsive design, typography, color systems, navigation, data visualization, icons, forms, UI states, overlays, and review templates.

7 component checklists (checklists/)

“Building a [X]? Check these before shipping.” — 12-14 items each for: buttons, cards, tables, forms, modals, navigation, dashboards.

5 non-negotiables

Full coverage breakdown → | Architecture →

---

What’s New (v2)

The original release had solid principles but left developers to interpret paragraphs. v2 closes the gap between “good advice” and “code I can ship.”

• Every principle now has do/don’t code examples — Tailwind + React snippets you can copy-paste, not paragraphs to interpret. (Phase 1)
• 3 new reference docs: forms, UI states, overlays — the most common “what do I do here?” moments now have deep-dive guidance with decision trees. (Phase 2)
• 7 component checklists — building a table? A modal? A dashboard? Start with a 12-14 item checklist that references the right principles and docs. No more guessing which rules apply to your surface. (Phase 3)
• Quick-reference index — “I need help with [X] → read [Y]” lookup table at the top of SKILL.md. Find the right doc in seconds. (Phase 3)
• Review template tightened — verification split into Essential (15 must-pass) and Polish (20 items). 6 example findings across forms, dashboards, and settings — so AI assistants know exactly what good audit output looks like. (Phase 3)
• Core principles sharpened — “modern minimal” vibes replaced with concrete rules: max shadow blur values, max colors per component, whitespace ratios, border-radius scales. (Phase 1)
• Dark mode deepened — elevation strategy, saturation reduction, separate contrast audit. (Phase 1)

The net effect: AI assistants using this skill now produce more specific, more consistent, and more shippable UI — especially for the surfaces developers build most (forms, tables, dashboards, settings).

---

Origin

Forked from oil-oil/oiloil-ui-ux-guide — a well-structured Chinese-language UI/UX skill with strong bones: solid core principles, a smart help-text layering system (L0-L3), Norman-inspired psychology, and clean multi-tool architecture.

This fork rewrote it in English and filled the gaps: accessibility, responsive design, typography, color systems, navigation, data visualization, forms, UI states, overlays, component checklists, and structured review workflows. Every rule traces back to a user outcome, not a style preference. Full origin story →

---

License

Apache License 2.0 — Built by Naren Katakam. Original work by oil-oil.