agentleFS
drvossdrvoss/everything-copilot-cli/skills/testing/ux-audit/SKILL.md

ux-audit

Skill48 starsChanged 17 days agoMITView on GitHub

Use when a page or component needs a structured UX audit — quick scan applies 6 Krug-inspired usability checks; deep audit covers 15 design dimensions with Jobs/Ive philosophy

26 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use ecosystem-reference, fractal-delegation and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • naman10parikhSkill

    ecosystem-reference

    Quick-access directory of Claude Code ecosystem repos, skills, plugins, MCPs, and patterns. Use when improving the harness.

    Also in 5 projects that use this

  • naman10parikhSkill

    fractal-delegation

    Also in 5 projects that use this

  • KirchliveSkill

    skill-routing

    Decides which of the installed skills a task needs and loads them before the work starts. This skill should be used at the beginning of any multi-step task — build, fix, refactor, migrate, review, plan, release, research, write, design, video — and again at every phase change, after context compaction, and when work moves into a different part of the codebase. Use it for requests like "let's build X", "fix this bug", "refactor Y", "plan the migration", "review this", and also when the user asks which skill applies, why a skill did not fire, or asks to check what is available.

    Also in 5 projects that use this

  • sublimotionSkill

    agent-runtime

    Launch and manage detached agent runs on EKS via the agent-runner CLI. Use when the user says "launch an agent run", "agent runtime", "agent-runner", "run this spec on the cluster", "check run status", "agent run logs", or "stop a run". Do NOT use for writing the agent-runner code itself (edit the sibling ../agent-runner repo), Terraform of the foundation (use terraform-automation), or GPU serving deployments (use infra-deployer).

    Also in 5 projects that use this

  • GoZippySkill

    repo-scout

    Also in 5 projects that use this

  • BenjaminGSkill

    harness-review

    Turn one PR's review comments into harness fixes — classify each cause by the most solid place it can live (codebase, lint, rules, skill), then draft the fixes in a separate PR.

    Also in 5 projects that use this

  • +6 more from naman10parikh

The file

Show its rules and text

We split this skill into the rules it gives an agent

17 rules. 0 are common, 15 are distinctive, and 2 are very specific to this project.

  • 0

    Common

    Most of the 23 edited versions we read keep these.

  • 15

    Distinctive

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Run a structured usability review based on Steve Krug's *Don't Make Me Think*.

    line 13
  2. Distinctive:

    Use it to inspect page structure, copy, navigation, and interaction friction before or alongside design review.

    line 14
  3. Distinctive:

    Before a design review or frontend handoff

    line 20
  4. Distinctive:

    When users report confusion but the failure mode is still unclear

    line 21
  5. Distinctive:

    When navigation, headings, or calls to action feel noisy or ambiguous

    line 22
  6. Distinctive:

    Before implementation starts, write a short contract for the screen so the later audit has something concrete to enforce.

    line 46
  7. Distinctive:

    Use the existing audit checks as the contract's enforcement points:

    line 66
  8. Distinctive:

    Run all six checks in sequence.

    line 74
  9. Very specific:

    If runtime inspection is needed, pair this skill with browser-devtools.

    line 158
  10. Distinctive:

    Default to a short human-readable report:

    line 162
  11. Distinctive:

    If another workflow needs structured output, you may additionally emit JSON, but human-readable findings remain the primary deliverable.

    line 183
  12. Distinctive:

    Do not accept vague self-congratulation as a design decision.

    line 190
  13. Distinctive:

    Prefer concrete evidence ("two CTAs compete above the fold") over taste-based critique

    line 197
  14. Distinctive:

    Use for major redesigns, premium quality assessment, or when the quick scan surfaces systemic issues.

    line 203
  15. Distinctive:

    The test: Remove until it breaks. Then add back the last thing.

    line 234
  16. Distinctive:

    After completing all 15 dimensions, compile a phased plan before making any changes:

    line 238
  17. Very specific:

    If the audit surfaces a control that is broken, dead, or behaves incorrectly, record it as a UX-impacting finding but hand off functional …

    line 264

“Common” is measured: kept by at least 6 in 10 of the 23 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

UX Audit

Run a structured usability review based on Steve Krug's Don't Make Me Think. Use it to inspect page structure, copy, navigation, and interaction friction before or alongside design review.

When to Use

  • UI를 만들기 전에 화면의 목적과 품질 기준을 먼저 못 박아야 할 때
  • Before a design review or frontend handoff
  • When users report confusion but the failure mode is still unclear
  • When navigation, headings, or calls to action feel noisy or ambiguous
  • During UI quality sweeps after major layout or copy changes

When NOT to Use

Instead of ux-auditUse
Accessibility conformance or ARIA debuggingbrowser-devtools
End-to-end flow automatione2e-testing
Broken or non-functional controls discovered during a UX passflag in the audit, then hand off to e2e-testing for functional verification
Performance bottleneck analysisbrowser-devtools or performance-optimization
Pure visual polish critiquemanual design review

Audit Modes

Choose the depth of review based on what you need:

ModeChecksBest for
Quick scan (default)6 Krug usability checksNavigation/copy confusion, pre-handoff spot checks
Deep audit15-dimension Jobs/Ive frameworkMajor redesigns, premium quality bar, comprehensive UI review

Design Contract — Before Building

Before implementation starts, write a short contract for the screen so the later audit has something concrete to enforce.

Capture only three things:

  1. Purpose — one sentence for what this screen is for
  2. Primary action — the one action that must win attention first
  3. Forbidden defaults/patterns — shortcuts the screen is not allowed to fall back to

Keep it short:

## Design Contract: [screen]

- Purpose: [one sentence]
- Primary action: [the main CTA or task]
- Forbidden defaults:
  - [generic welcome copy / dashboard filler / placeholder layout / competing CTAs / etc.]

Use the existing audit checks as the contract's enforcement points:

  • Trunk Test / Page Area Test verify that purpose is obvious
  • 3-Second Scan verifies that the primary action wins quickly
  • Happy Talk Detection verifies that forbidden generic copy did not creep back in

The 6 Usability Checks

Run all six checks in sequence. A page with repeated failures across these categories needs structural revision, not copy-only cleanup.

1. Trunk Test

"If I dropped you in the middle of this page with no context, where are you?"

Check:

  • Site or product identity is visible quickly
  • A page-level heading makes the purpose obvious
  • Navigation exists and is easy to locate
  • Current location is indicated with active nav or breadcrumbs

2. 3-Second Scan

"What does this page do?"

Check:

  • The primary action or value proposition is visible without hunting
  • Heading hierarchy is scannable
  • One primary call to action clearly wins attention

3. Page Area Test

"Can you tell what each part of this page is for?"

Check:

  • Major regions such as header, main content, sidebar, and footer are distinct
  • Headings introduce real content instead of stacking without explanation
  • Section purpose is clear before reading full paragraphs

4. Happy Talk Detection

"Is the page making me read obvious or low-value copy?"

Look for:

  • Generic welcome copy that says little
  • Repetitive marketing filler above the real action
  • Links or buttons with vague labels like Click here or Learn more

5. Mindless Choice Audit

"Does every click require extra thought?"

Check:

  • Links describe destinations clearly
  • Form fields use real labels, not placeholder-only hints
  • Options are named so users can choose quickly

6. Goodwill Reservoir

"Is the page wasting the user's time or patience?"

Check:

  • Body text is comfortably readable
  • Errors explain how to recover
  • Media or overlays do not interrupt the task unexpectedly

Hard Fail Signals

Escalate findings when any of these appear:

  • Placeholder text used as the only field label
  • Missing, generic, or low-signal primary heading
  • Floating headings with no supporting content
  • Visited and unvisited links are visually indistinguishable
  • Body text is too small to read comfortably

Suggested Workflow

  1. Before building, write the Design Contract: purpose, primary action, forbidden defaults/patterns.
  2. Choose your audit mode: Quick Scan (6 checks, default) or Deep Audit (15 dimensions) — see Audit Modes table above.
  3. Inspect the live page or rendered component
  4. Record evidence for each check (Quick Scan) or each dimension (Deep Audit)
  5. Mark each check/dimension as pass, concern, or fail
  6. Separate structural issues from copy polish
  7. Prioritize fixes that reduce confusion on the main user path

If runtime inspection is needed, pair this skill with browser-devtools.

Output Format — Quick Scan

Default to a short human-readable report:

## UX Audit: [page or component]

- **Trunk Test**: Pass | Concern | Fail - [reason]
- **3-Second Scan**: Pass | Concern | Fail - [reason]
- **Page Area Test**: Pass | Concern | Fail - [reason]
- **Happy Talk**: Pass | Concern | Fail - [reason]
- **Mindless Choice**: Pass | Concern | Fail - [reason]
- **Goodwill Reservoir**: Pass | Concern | Fail - [reason]

**Hard Fail Signals**
- [issue or "None"]

**Top Fixes**
1. [highest-priority change]
2. [next change]
3. [next change]

If another workflow needs structured output, you may additionally emit JSON, but human-readable findings remain the primary deliverable.

For Deep Audit output, see the Phased Plan Output template in the Deep Audit section below.

Finish Gate

Do not accept vague self-congratulation as a design decision. Terms like "clean," "modern," "intuitive," or "premium" are non-answers unless they resolve into specific choices visible on the screen.

Reject the screen if its copy and layout feel generic enough that they could be bolted onto a completely unrelated product without anyone noticing. Passing requires product-specific purpose, language, and emphasis — not interchangeable SaaS wallpaper.

Tips

  • Judge the page from a first-visit perspective, not from implementation knowledge
  • Prefer concrete evidence ("two CTAs compete above the fold") over taste-based critique
  • Fix structural confusion before refining tone or visual polish
  • Re-run the audit after major IA, copy, or navigation changes

Deep Audit — Jobs/Ive 15 Dimensions

Use for major redesigns, premium quality assessment, or when the quick scan surfaces systemic issues. Review every screen across all 15 dimensions before writing any recommendations.

The 15 Dimensions

DimensionKey Questions
Visual HierarchyDoes the eye land where it should? Most important = most prominent? Understandable in 2 seconds?
Spacing & RhythmWhitespace consistent and intentional? Elements breathe or cramped? Vertical rhythm harmonious?
TypographyClear size hierarchy? Too many competing weights/sizes? Calm or chaotic?
ColorUsed with restraint and purpose? Guides attention or scatters it? Sufficient contrast?
Alignment & GridConsistent grid? Anything off by 1–2px? Every element locked into layout?
ComponentsSimilar elements styled identically? Interactive elements obviously interactive? All states covered?
IconographyConsistent style, weight, size? From one cohesive set or mixed? Support meaning or just decorate?
MotionTransitions natural and purposeful? Motion that exists for no reason? Feels responsive?
Empty StatesEvery screen with no data — intentional or broken? User guided toward first action?
Loading StatesSkeletons/spinners consistent? App feels alive while waiting or frozen?
Error StatesStyled consistently? Helpful and clear or hostile and technical?
Dark ModeActually designed or just inverted? Tokens, shadows, contrast hold up?
DensityAnything removable without losing meaning? Redundant elements? Every element earning its place?
ResponsivenessWorks at mobile/tablet/desktop? Touch targets sized for thumbs? Adapts fluidly, not just at breakpoints?
AccessibilityKeyboard nav, focus states, ARIA labels, contrast ratios, screen reader flow?

Jobs Filter — Apply to Every Element

For each screen element, ask:

  1. "Would a user need to be told this exists?" → If yes, redesign until obvious
  2. "Can this be removed without losing meaning?" → If yes, remove it
  3. "Does this feel inevitable, like no other design was possible?" → If no, it is not done
  4. "Is this detail as refined as the details users will never see?" → The back of the fence must be painted too

The test: Remove until it breaks. Then add back the last thing.

Phased Plan Output

After completing all 15 dimensions, compile a phased plan before making any changes:

DEEP AUDIT RESULTS:

Overall Assessment: [1–2 sentences on current state]

PHASE 1 — Critical (hierarchy, usability, responsiveness issues that actively hurt UX)
- [Screen/Component]: [what's wrong] → [what it should be] → [why this matters]

PHASE 2 — Refinement (spacing, typography, color, alignment that elevate quality)
- [Screen/Component]: [what's wrong] → [what it should be] → [why this matters]

PHASE 3 — Polish (micro-interactions, empty/loading/error states, dark mode, subtle details)
- [Screen/Component]: [what's wrong] → [what it should be] → [why this matters]

DESIGN SYSTEM UPDATES:
- [New tokens, colors, spacing, or component changes required]

Do not implement until the plan is approved. Execute phase by phase, presenting results before advancing.

Scope Discipline

Deep audit covers visual design, layout, spacing, typography, color, interaction, motion, and accessibility. It does not touch application logic, state management, API calls, or feature behavior. If a design improvement would require a functional change, flag it rather than implementing it.

If the audit surfaces a control that is broken, dead, or behaves incorrectly, record it as a UX-impacting finding but hand off functional verification to e2e-testing. ux-audit diagnoses quality and clarity of the experience; it does not become the functional debugging workflow.

See Also

  • browser-devtools — inspect runtime DOM, network, and accessibility state
  • e2e-testing — automate critical user journeys after the UX issues are understood

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.