1---2name: ux-antipatterns3description: 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.4---56# UX Anti-Pattern Detection78Scan frontend code for patterns that cause user frustration. 910## Core Axioms1112Before checking individual rules, internalize these. They are the "why" behind every item below.1314| # | Axiom | One-liner |15|---|-------|-----------|16| 1 | **Acknowledge every action** | Every user action must produce visible feedback within 100ms, even if the result takes seconds. |17| 2 | **Never destroy user input** | Not on error, not on navigation, not on timeout, not on refresh. |18| 3 | **State survives the unexpected** | Refresh, double-clicks or double submits, network loss — code must handle edge cases. |19| 4 | **Most recent intent wins** | Stale responses must never overwrite a newer user action. |20| 5 | **Explain every constraint** | If it's disabled, say why. If it failed, say how to fix it. If it succeeded, say what happened. |21| 6 | **Don't fight the platform** | Browser conventions, OS gestures, native controls, and accessibility APIs encode billions of hours of UX research. |2223## When NOT to Use2425- Backend-only code with no UI layer26- CLI tools or non-visual interfaces27- Design system tokens/docs without implementation code28- Pure API or data-layer reviews29- Performance profiling (unless it manifests as a UX symptom like layout shift)3031## Workflow32331. Read [references/antipatterns.md](references/antipatterns.md) to load the full detection heuristics.342. Scan the code under review against each applicable anti-pattern category.353. Report findings grouped by anti-pattern, citing specific file:line locations.364. For each finding, state: the anti-pattern name, the user harm, and a concrete fix.375. If no anti-patterns are found, state that the code is clean rather than manufacturing findings.3839## Anti-Pattern Categories4041| # | Category | User Harm |42|---|----------|-----------|43| 1 | Layout Stability | Click target moves; wrong thing clicked. |44| 2 | Feedback & Responsiveness | Action feels ignored; user retries, waits, or loses trust that the system is working. |45| 3 | Error Handling & Recovery | User is stuck with no way forward; input destroyed; problem unsolvable without guessing. |46| 4 | Forms & Input Interference | Platform fights the user's typing; data mangled, basic editing broken. |47| 5 | Focus | User is typing and the UI yanks them elsewhere. |48| 6 | Notifications, Interruptions & Dialogs | User's flow broken; attention taxed by noise; forced to parse ambiguous choices under pressure. |49| 7 | Navigation, Routing & State Persistence | User can't go back; context evaporates on refresh or redirect. |50| 8 | Scroll & Viewport | Content unreachable or unstable; user fights the interface to see what they came for. |51| 9 | Timing, Debounce & Race Conditions | Actions fire twice, responses arrive stale, sessions expire mid-task; system behaves unpredictably under normal use. |52| 10 | Accessibility as UX | Entire interaction modes broken — keyboard users can't navigate, touch users locked out. |53| 11 | Visual Layering & Rendering | UI elements overlap, clip, or hide each other; controls become unreachable. |54| 12 | Mobile & Viewport-Specific | Keyboard covers input, layout jumps on scroll, tap targets unresponsive; basic mobile interaction degraded. |55| 13 | Cumulative Decay & Long-Term UX | App degrades over time; preferences lost, performance rots, stale experiments create inconsistencies. |5657## Quick Reference: Symptom → Category5859| User complaint / code smell | Category |60|---|---|61| "Button does nothing when I click it" | 2. Feedback & Responsiveness |62| "I clicked the wrong thing — it moved" | 1. Layout Stability |63| "I lost my form data" | 4. Forms & Input Interference |64| "It says 'Something went wrong' with no explanation" | 3. Error Handling & Recovery |65| "The page jumped while I was typing" | 5. Focus |66| "I got the same notification 5 times" | 6. Notifications & Dialogs |67| "I logged in and it forgot where I was going" | 7. Navigation & State Persistence |68| "I scrolled back and lost my place" | 8. Scroll & Viewport |69| "My order was placed twice" | 9. Timing & Race Conditions |70| "I was filling out a form and it logged me out" | 9. Timing & Race Conditions |71| "I clicked delete and it just... deleted it" | 6. Notifications & Dialogs |72| "It's been loading for 2 minutes with no progress bar" | 2. Feedback & Responsiveness |73| "I can't use this with my keyboard" | 10. Accessibility as UX |74| "The dropdown is hidden behind the modal" | 11. Visual Layering |75| "The keyboard covers the input on my phone" | 12. Mobile & Viewport-Specific |76| "The app gets slower over time" | 13. Cumulative Decay |7778## Common Mistakes7980- **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.81- **Ignoring context.** A disabled button inside a wizard step IS explained by the wizard's own flow. Check for nearby explanatory elements before reporting.82- **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.83- **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.84- **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.
cassiozen