# UX Antipatterns

> 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.

- Skill: `cassiozen/ux-antipatterns` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add cassiozen/ux-antipatterns`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cassiozen/ux-antipatterns/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: cassiozen (https://skillmd.com/u/cassiozen)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/cassiozen/ux-antipatterns

---


# 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](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.