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
- Read references/antipatterns.md to load the full detection heuristics.
- Scan the code under review against each applicable anti-pattern category.
- Report findings grouped by anti-pattern, citing specific file:line locations.
- For each finding, state: the anti-pattern name, the user harm, and a concrete fix.
- 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.
