| 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:
- 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.
- 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).
- 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.
- 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., john@example.com"), 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
