audit-ux

name	audit-ux
description	Audit user experience quality using research-backed frameworks: Nielsen Norman Group's 10 usability heuristics, Intuit Content Design System for microcopy, Google's HEART metrics, and Laws of UX (Fitts's, Hick's, Miller's, Jakob's, cognitive load). Evaluates information architecture, user flows, error recovery, onboarding, content clarity, and interaction patterns. Uses playwright-cli for live walkthrough, Firecrawl for current NN/g research, and Sequential Thinking for complex flows. Generic — works with any webapp. Use when evaluating usability, reviewing user flows, auditing microcopy, checking UX heuristics, assessing cognitive load, reviewing onboarding, or when the user mentions UX audit, usability review, heuristic evaluation, content audit, interaction design review, or user flow analysis. Focuses on per-page EXPERIENCE — for visual design-system compliance (tokens, components, dark mode) use audit-uiux-design-system; for cross-page user-story/IA/journey audits use audit-ux-journeys.
license	MIT

UX Audit Skill

Research-driven user experience evaluation grounded in NN/g heuristics, Laws of UX, Intuit Content Design principles, and Google HEART metrics.

Before ANY browser interaction, read the protocol-browser-anti-stall skill and apply its rules to every step. That skill is protocol-browser-anti-stall.

Context-First, Human-Centric Approach

UX recommendations that don't understand the WHY behind the product are surface-level checkbox audits. Before evaluating any heuristic or pattern, deeply understand:

1. Who is the human? Not "users" — real people with frustrations, time pressure, emotional states, and goals beyond the screen. A tired parent filing taxes at 11pm needs different UX than a power-user analyst building dashboards at work.
2. What's the full journey? The page you're looking at is one moment in a longer story. Understand what happened before (how they arrived, what they already know) and what happens after (what they do with the result, where they go next).
3. What's the data pipeline? Trace data from human input → API → database → back to screen. UX breaks when this pipeline has latency, errors, or mismatch between what the human expects and what the system returns.
4. What's the emotional arc? Every product interaction has an emotional shape: confusion → understanding → action → confirmation → satisfaction (or frustration). Map where the product currently creates anxiety, confusion, or dead ends.

Step 0 grounds every subsequent finding — shallow context produces shallow recommendations.

---

Step 0: Deep Product and Pipeline Understanding

0a. Understand the Business and Human Context

Read README, landing page, marketing copy, and any onboarding flows to answer:

• What problem does this solve? (Not features — the human pain it alleviates)
• Who is the primary human? (Demographics, technical skill, emotional state when using)
• What's the alternative? (What do people do without this product? Spreadsheets? Phone calls? Nothing?)
• What's the success moment? (The "aha" — when the human gets what they came for)
• What's the trust model? (Does the user trust this product with money? Health data? Business data?)

0b. Map the Full Data Pipeline

Trace how data flows through the system from the human's perspective:

Search for data-flow entry points: api/ for API routes, actions/ for server actions, hooks/use* for data-fetching hooks, lib/ for core business logic. Count occurrences of fetch|axios|ky|useSWR|useQuery|trpc in *.{ts,tsx} to map integration points.

Map the pipeline for each core task:

PIPELINE MAP (per core task):
1. Human input → [form / click / gesture]
2. Client-side validation → [schema / inline / none]
3. API call → [endpoint, method, payload]
4. Server processing → [validation, business logic, side effects]
5. Database operation → [create / read / update / delete]
6. Response → [shape, status codes, error format]
7. Client update → [optimistic / refetch / cache invalidation]
8. Human feedback → [toast / redirect / inline update / nothing]

Latency-sensitive points: [where slow responses hurt UX]
Error-prone points: [where failures are most likely]
Trust-sensitive points: [where wrong data erodes confidence]

0c. Map Routes and Information Architecture

Discover routes by framework: app/**/page.tsx (Next.js App Router), pages/**/*.tsx (Next.js Pages Router), src/routes/ (SvelteKit / Remix), router.* (Vue Router / React Router config).

This step builds context only. For a full structural IA audit (click depth, orphan pages, label consistency, findability) and end-to-end user-story walkthroughs, use audit-ux-journeys — this skill stays on the per-page experience lens.

Build the information architecture mental model:

INFORMATION ARCHITECTURE:
- Navigation structure: [flat / hierarchical / hub-and-spoke]
- Depth: [max clicks from landing to deepest page]
- Cross-links: [can users jump between sections, or must they go back?]
- Dead ends: [pages with no forward navigation]

0d. Identify Emotional Touchpoints

Map the emotional arc of core user journeys:

EMOTIONAL MAP (per core flow):
- Entry emotion: [anxious / curious / frustrated / neutral]
- Friction points: [where confusion or anxiety spikes]
- Confidence builders: [where the product earns trust]
- Peak moment: [the most positive or negative experience]
- End emotion: [satisfied / relieved / confused / abandoned]

0e. Record Full Discovery

PRODUCT CONTEXT:
- Type: [SaaS / e-commerce / dashboard / etc.]
- Human problem solved: [the pain, not the feature]
- Primary human: [description including emotional context]
- Core tasks: [list top 3-5]
- Success moment: [what "done" looks like to the human]
- Trust level: [what's at stake — money / data / time / reputation]
- Page count: [N]
- Auth required: [YES/NO — pattern]
- Locale/i18n: [YES — languages / NO]
- Pipeline health: [known latency or error-prone points]

---

Step 1: Research Current UX Standards

1a. NN/g — Usability Heuristics and Methods

firecrawl:firecrawl_search
{
 "query": "site:nngroup.com heuristic evaluation checklist [current year]",
 "limit": 5,
 "sources": [{ "type": "web" }]
}

1b. Intuit Content Design — Microcopy Principles

firecrawl:firecrawl_search
{
 "query": "site:contentdesign.intuit.com UX writing principles",
 "limit": 5,
 "sources": [{ "type": "web" }]
}

Scrape the most relevant result for detailed writing guidelines.

1c. Laws of UX — Interaction Psychology

firecrawl:firecrawl_scrape
{
 "url": "https://lawsofux.com",
 "formats": ["markdown"],
 "onlyMainContent": true
}

1d. Domain-Specific UX Research

firecrawl:firecrawl_search
{
 "query": "<PRODUCT_TYPE> UX best practices usability patterns [current year]",
 "limit": 5,
 "sources": [{ "type": "web" }]
}

Scrape the best result for domain-specific UX patterns.

---

Step 2: Nielsen's 10 Usability Heuristics (Deep Evaluation)

For each heuristic, perform both code analysis and live browser verification.

H1: Visibility of System Status

The system should keep users informed through timely feedback.

What to find in code:

Search *.tsx for feedback patterns: loading|isLoading|isPending|skeleton|Skeleton|spinner|Spinner (loading states); progress|Progress|step.*of|currentStep (multi-step progress); toast|Toast|notification|Notification|snackbar (user notifications).

What to verify in browser:

Signal	Pass	Fail
Loading states	Skeleton/spinner visible during data fetch	Blank screen or frozen UI
Form submission	Button shows loading, success/error feedback	No feedback, user clicks again
Progress indication	Multi-step flows show step count	User doesn't know where they are
Active navigation	Current page/section highlighted	No indication of current location
Real-time updates	Optimistic UI or polling feedback	Stale data, no refresh indication

H2: Match Between System and Real World

Use language and concepts familiar to users, not internal jargon.

What to find in code:

Search *.tsx for copy-quality TODOs: TODO.*wording|TODO.*copy|TODO.*label|TODO.*text (case-insensitive).

What to verify in browser:

Signal	Pass	Fail
Labels and terminology	Domain-appropriate language users expect	Technical jargon, internal codenames
Icons	Universally recognized or labeled	Ambiguous icons without text labels
Data format	Dates, currency, numbers in user's locale	ISO dates, raw numbers, wrong currency
Logical grouping	Information organized by user mental model	Organized by database schema or dev convenience
Metaphors	Real-world analogies aid understanding	Forced metaphors that confuse

H3: User Control and Freedom

Emergency exits, undo, cancel — users make mistakes.

What to find in code:

Search *.tsx for emergency-exit patterns: onCancel|handleCancel|onClose|handleClose|onDismiss (cancel/close handlers); undo|Undo|revert|Revert (undo actions); confirm.*delete|confirm.*remove|AlertDialog|ConfirmDialog (destructive-action guards).

What to verify in browser:

Signal	Pass	Fail
Modal escape	Close button + Escape key + backdrop click	No way to close, trapped
Form abandonment	Back button works, drafts saved	Data lost on navigation
Destructive actions	Confirmation dialog with clear consequences	One-click delete, no undo
Multi-step flows	Back/previous step without data loss	Can only go forward
Undo	Undo available after significant actions	Irreversible changes without warning

H4: Consistency and Standards

Same thing = same treatment. Follow platform conventions.

What to verify in browser:

Signal	Pass	Fail
Button hierarchy	Primary/secondary/ghost used consistently	Random button styles
Terminology	Same action = same label everywhere	"Save" / "Submit" / "Confirm" / "Apply" for same action
Layout patterns	Consistent page structure across views	Each page has different layout logic
Interaction patterns	Same gesture = same result	Click sometimes navigates, sometimes opens modal
Platform conventions	Follows web conventions (links underlined, form patterns)	Custom patterns that break expectations

H5: Error Prevention

Prevent problems before they happen.

What to find in code:

Search *.tsx for prevention patterns: disabled.*(!|=.*false)|isDisabled|isInvalid (disabled/invalid states); required|min.*length|max.*length|pattern= (input constraints). Check package.json for validation libraries: zod|yup|joi|superstruct|valibot.

What to verify in browser:

Signal	Pass	Fail
Input constraints	Date pickers (not free text), dropdowns for known options	Free text for structured data
Inline validation	Validation on blur/change, before submit	Only validates on submit
Destructive guards	Requires confirmation, type-to-confirm for critical actions	One-click irreversible actions
Defaults	Smart defaults reduce input needed	All fields blank, user guesses
Disabled states	Buttons disabled when form invalid, with explanation	Enabled but silently fails

H6: Recognition Over Recall

Make options visible. Don't force users to memorize.

What to verify in browser:

Signal	Pass	Fail
Navigation	All major sections visible in nav	Features hidden in deep menus
Search	Search available for large data sets	User must scroll/browse to find
Breadcrumbs	Breadcrumbs in hierarchical content	User loses context in deep pages
Recent items	Recently accessed items surfaced	Must remember and navigate from scratch
Contextual help	Tooltips, placeholders explain fields	Labels without context

H7: Flexibility and Efficiency of Use

Accelerators for experts, simplicity for novices.

What to find in code:

Search *.tsx for efficiency patterns: keyboard|shortcut|hotkey|useHotkeys|Cmd\+|Ctrl\+ (keyboard accelerators); bulk|batch|selectAll|multiSelect (bulk operations).

What to verify in browser:

Signal	Pass	Fail
Keyboard shortcuts	Power-user shortcuts available	Mouse-only interaction
Bulk actions	Multi-select, batch operations	One-at-a-time only
Filters and sort	Filter/sort on data-heavy pages	Must scan manually
Customization	Users can configure views/preferences	One-size-fits-all
Quick actions	Common tasks reachable in 1-2 clicks	Core tasks buried in menus

H8: Aesthetic and Minimalist Design

Every element competes for attention. Show only what's needed.

What to verify in browser:

Signal	Pass	Fail
Information density	Progressive disclosure, expand-on-demand	Everything visible at once
Visual hierarchy	Clear primary/secondary/tertiary content	Everything same visual weight
Whitespace	Breathing room between sections	Cramped, dense layout
CTAs	1 primary action per view, clearly distinguished	Multiple competing CTAs
Content priority	Most important content first/prominent	Critical info buried below fold

H9: Help Users Recognize, Diagnose, and Recover from Errors

Error messages in plain language, with solutions.

What to find in code:

Search *.tsx for error-handling patterns: error.*message|errorMessage|Error.*:.*' (error message strings); try.*catch|\.catch\(|onError (catch sites); fallback|ErrorBoundary|error\.tsx (fallback components — list files with matches, not just count).

What to verify in browser:

Signal	Pass	Fail
Error language	Plain language, no codes	"Error 500", "ECONNREFUSED", raw stack trace
Specificity	Says exactly what went wrong	"Something went wrong"
Recovery action	Suggests what user can do next	Dead end, user must guess
Inline errors	Field-level errors near the input	Single error at top of form
Empty states	Helpful empty states with next action	Blank page, "No data"

H10: Help and Documentation

Easy to search, task-focused, concise.

What to find in code:

Search *.tsx for in-app help: Tooltip|tooltip|HelpCircle|InfoIcon|help.*text|aria-describedby (contextual help); onboarding|tour|walkthrough|guide|Onboarding (guided flows).

What to verify in browser:

Signal	Pass	Fail
Contextual help	Tooltips on complex fields/features	No explanation, user must guess
Onboarding	First-time user guidance available	Dropped into complex UI cold
Documentation	Help accessible from within the app	Must search external docs
Input guidance	Placeholders, hint text, format examples	Bare input fields

---

Step 3: Laws of UX Evaluation

Evaluate against key psychological principles from lawsofux.com. For each law, check BOTH the current state AND recommend specific improvements.

Law	Principle	What to Check	How to Fix Violations
Jakob's Law	Users expect your site to work like other sites	Navigation, form patterns, checkout flows follow platform conventions	Research 3 competitors via Firecrawl, adopt their common patterns
Fitts's Law	Larger, closer targets are faster to click	Primary CTAs large enough, not in corners. Touch targets ≥44px	Increase CTA size, move primary actions to natural thumb zones on mobile
Hick's Law	More choices = longer decisions	Menus ≤7 items, option lists not overwhelming, progressive disclosure	Group options, add search/filter, hide advanced options behind "More"
Miller's Law	Working memory holds ~7 items	Groups of >7 chunked. Nav items ≤7 per level	Chunk long lists, add category headers, paginate
Cognitive Load	Minimize mental effort	No unnecessary fields, no memory burden between steps	Remove optional fields from default view, show only what's needed now
Aesthetic-Usability	Beautiful = perceived as easier	First impression inspires confidence	Visual polish on landing + key flows. Personality, not just correctness
Tesler's Law	Complexity can't be eliminated, only moved	Complex tasks simplified for the user, not pushed to them	Smart defaults, auto-detection, progressive disclosure of complexity
Doherty Threshold	Productivity rises when response <400ms	Do interactions feel instant?	Optimistic UI, skeleton screens, prefetching, perceived performance tricks
Postel's Law	Be liberal in what you accept	Flexible input parsing (phone, date, case)	Accept multiple input formats, auto-format, don't reject valid variations
Peak-End Rule	People judge by peaks and endings	Success moment satisfying? Error moments handled gracefully?	Celebrate completions (confetti, clear confirmation). Soften errors

---

Step 4: Content and Microcopy Audit (Intuit Content Design Principles)

Evaluate all user-facing text against Intuit's content design standards.

4a. Voice and Tone

Principle	Pass	Fail
Conversational	Reads like talking to a friend	Reads like a legal document or robot
Active voice	"We saved your changes"	"Your changes have been saved by the system"
Second person	"You" for the user, "We" for the product	Third person, passive constructions
Contractions	Natural contractions used ("don't", "we'll")	Stilted formal language ("do not", "we will")

4b. Clarity and Precision

Principle	Pass	Fail
Specific language	"We can't connect to Square right now"	"Something went wrong. Try again later"
Consistent terms	Same word for same concept throughout	"Save" / "Submit" / "Confirm" / "Apply" used interchangeably
Simple verbs	Present/past/future simple tense	Progressive, perfect, complex tenses
Short sentences	≤20 words per sentence	Run-on sentences with multiple clauses

4c. Microcopy Quality

Check these locations in the browser:

Location	What to Evaluate
Button labels	Action-oriented, specific ("Save invoice" not just "Submit")
Error messages	Plain language, specific cause, recovery action
Empty states	Helpful, guides next action, not just "No data"
Confirmations	Clear consequence ("Delete this invoice? This can't be undone")
Tooltips	Concise, answers one question, not paragraphs
Placeholders	Format hints ("e.g., [e-mail]"), not labels
Loading text	Informative when possible ("Loading your invoices...")
Success messages	Confirms what happened ("Invoice sent to John")

4d. Internationalization Readiness

Check	Pass	Fail
Hardcoded strings	All strings in i18n files	Strings inline in components
Cultural idioms	Neutral metaphors	Culture-specific slang or humor
Text expansion	UI handles 40% longer translated text	Layout breaks with longer strings
RTL readiness	Logical properties (margin-inline-start)	Physical properties (margin-left)

Find violations: search *.tsx for >([\w\s]{3,})< to surface hardcoded visible text strings that may be i18n misses.

---

Step 5: Emotional Design and Human-Centric Evaluation

This step evaluates the FEELING of using the product — the layer most audits miss.

5a. First Impression Test (5-Second Test)

Navigate to the landing/home page. In the first 5 seconds of the screenshot:

Question	Evidence
Can you tell what this product does?	[yes/no — what's communicated]
Do you trust it?	[visual polish, credibility signals, brand presence]
Do you know what to do first?	[clear CTA, obvious starting point]
Does it feel like a real product or a template?	[personality, craft, vs generic bootstrap]

Further reading

• 5b. Emotional Friction Map and more