ux-antipatterns

name	ux-antipatterns
description	Use when reviewing, building, or refactoring frontend UI — components, pages, forms, or interactive flows. Triggers on code review, pull requests, and new feature implementation involving user-facing interfaces.

UX Anti-Pattern Detection

Scan frontend code for patterns that cause user frustration.

Core Axioms

Before checking individual rules, internalize these. They are the "why" behind every item below.

#	Axiom	One-liner
1	Acknowledge every action	Every user action must produce visible feedback within 100ms, even if the result takes seconds.
2	Never destroy user input	Not on error, not on navigation, not on timeout, not on refresh.
3	State survives the unexpected	Refresh, double-clicks or double submits, network loss — code must handle edge cases.
4	Most recent intent wins	Stale responses must never overwrite a newer user action.
5	Explain every constraint	If it's disabled, say why. If it failed, say how to fix it. If it succeeded, say what happened.
6	Don't fight the platform	Browser conventions, OS gestures, native controls, and accessibility APIs encode billions of hours of UX research.

When NOT to Use

• Backend-only code with no UI layer
• CLI tools or non-visual interfaces
• Design system tokens/docs without implementation code
• Pure API or data-layer reviews
• Performance profiling (unless it manifests as a UX symptom like layout shift)

Workflow

1. Read references/antipatterns.md to load the full detection heuristics.
2. Scan the code under review against each applicable anti-pattern category.
3. Report findings grouped by anti-pattern, citing specific file:line locations.
4. For each finding, state: the anti-pattern name, the user harm, and a concrete fix.
5. If no anti-patterns are found, state that the code is clean rather than manufacturing findings.

Anti-Pattern Categories

#	Category	User Harm
1	Layout Stability	Click target moves; wrong thing clicked.
2	Feedback & Responsiveness	Action feels ignored; user retries, waits, or loses trust that the system is working.
3	Error Handling & Recovery	User is stuck with no way forward; input destroyed; problem unsolvable without guessing.
4	Forms & Input Interference	Platform fights the user's typing; data mangled, basic editing broken.
5	Focus	User is typing and the UI yanks them elsewhere.
6	Notifications, Interruptions & Dialogs	User's flow broken; attention taxed by noise; forced to parse ambiguous choices under pressure.
7	Navigation, Routing & State Persistence	User can't go back; context evaporates on refresh or redirect.
8	Scroll & Viewport	Content unreachable or unstable; user fights the interface to see what they came for.
9	Timing, Debounce & Race Conditions	Actions fire twice, responses arrive stale, sessions expire mid-task; system behaves unpredictably under normal use.
10	Accessibility as UX	Entire interaction modes broken — keyboard users can't navigate, touch users locked out.
11	Visual Layering & Rendering	UI elements overlap, clip, or hide each other; controls become unreachable.
12	Mobile & Viewport-Specific	Keyboard covers input, layout jumps on scroll, tap targets unresponsive; basic mobile interaction degraded.
13	Cumulative Decay & Long-Term UX	App degrades over time; preferences lost, performance rots, stale experiments create inconsistencies.

Quick Reference: Symptom → Category

User complaint / code smell	Category
"Button does nothing when I click it"	2. Feedback & Responsiveness
"I clicked the wrong thing — it moved"	1. Layout Stability
"I lost my form data"	4. Forms & Input Interference
"It says 'Something went wrong' with no explanation"	3. Error Handling & Recovery
"The page jumped while I was typing"	5. Focus
"I got the same notification 5 times"	6. Notifications & Dialogs
"I logged in and it forgot where I was going"	7. Navigation & State Persistence
"I scrolled back and lost my place"	8. Scroll & Viewport
"My order was placed twice"	9. Timing & Race Conditions
"I was filling out a form and it logged me out"	9. Timing & Race Conditions
"I clicked delete and it just... deleted it"	6. Notifications & Dialogs
"It's been loading for 2 minutes with no progress bar"	2. Feedback & Responsiveness
"I can't use this with my keyboard"	10. Accessibility as UX
"The dropdown is hidden behind the modal"	11. Visual Layering
"The keyboard covers the input on my phone"	12. Mobile & Viewport-Specific
"The app gets slower over time"	13. Cumulative Decay

Common Mistakes

• Flagging style preferences as anti-patterns. A non-standard button shape is a design choice, not a UX violation. Only flag patterns that cause measurable user harm per the axioms.
• Ignoring context. A disabled button inside a wizard step IS explained by the wizard's own flow. Check for nearby explanatory elements before reporting.
• Suggesting fixes that break accessibility. A fix that adds a visual indicator but removes keyboard access trades one violation for another. Verify fixes against Axiom 6.
• Over-reporting on handled edge cases. If the code already has an AbortController, don't flag it for race conditions. Read the implementation before reporting.
• Reporting framework internals as violations. React's key prop remounts, Next.js loading states, or SvelteKit form actions may handle anti-patterns at the framework level. Understand the framework before flagging.