ui-ux-laws

---
name: ui-ux-laws
description: >
  Priority-ordered rulebook of core UX/UI laws, cognitive-psychology principles, Nielsen's usability heuristics, and accessibility requirements that Claude must actively apply (not just cite) whenever it designs, builds, redesigns, reviews, or critiques any user interface — websites, web/mobile apps, dashboards, forms, mockups, wireframes, prototypes, design systems, or single components (buttons, nav, modals, onboarding, empty states, error messages, etc.), in any output format (React/HTML/Vue/Figma-style/plain design advice). Trigger this skill any time the user asks to build, design, redesign, improve, critique, or give feedback on a UI, layout, screen, flow, or "user experience" — even if they never say the words "UX" or "usability." When two rules pull in different directions, use the Priority Hierarchy below to decide which one wins. Run the Pre-Ship Checklist before presenting any finished UI work.
---

# UI/UX Laws — Applied Rulebook

This skill is a working ruleset, not trivia. Every law below is a **constraint Claude enforces on its own output**, in priority order. If a design choice violates a higher-priority law to serve a lower-priority one (e.g. sacrificing clarity for novelty), fix the design before presenting it.

This skill governs *usability and cognitive ergonomics*. If `frontend-design` (or similar aesthetic skills) is also active, use both together: `frontend-design` picks the bold visual direction, this skill makes sure that direction never breaks usability. On conflict, this skill wins — see Priority Hierarchy.

## How to use this skill

1. Before designing: note the user's goal and their likely mental model (what similar interfaces they already know — Jakob's Law).
2. While designing: run through "Core Laws & Principles" for the specific elements you're building (forms, nav, lists, onboarding, etc.) and apply the relevant ones.
3. Before presenting: run the **Pre-Ship Checklist** at the bottom. Silently fix anything that fails it — don't ask the user for permission to be usable.
4. If a request explicitly asks for something a law would normally discourage (e.g. "make every option visible, no hiding anything"), honor the user's explicit instruction — these laws resolve *ambiguity and default choices*, they don't override direct requests.
5. If the task is to **critique or audit an existing UI** (a screenshot, a competitor site, someone else's code) rather than build one: walk it against the Priority Hierarchy and Pre-Ship Checklist as a reviewer, not a builder — call out which law each issue violates and its priority tier, so fixes get triaged by what actually matters most first.

---

## Priority Hierarchy

When rules conflict, resolve in this order (highest wins):

1. **Accessibility & safety** — nobody is excluded or harmed (contrast, keyboard nav, error prevention, destructive-action confirmation).
2. **Clarity & findability** — the user can tell what's here and what to do next (Hick's Law, Jakob's Law, recognition over recall).
3. **Correctness & forgiveness** — the system prevents, catches, or cheaply undoes mistakes (Postel's Law, error prevention).
4. **Efficiency of effort** — minimize clicks, distance, and cognitive math to finish a task (Fitts's Law, Tesler's Law, Doherty Threshold).
5. **Consistency** — matches the user's existing mental models and the rest of the product (Jakob's Law, internal consistency).
6. **Aesthetic polish & delight** — everything above already holds, *now* make it beautiful and memorable (Aesthetic-Usability Effect, Peak-End Rule).

A gorgeous interface that fails step 2 is a failed interface. A boring interface that nails 1–5 is a good baseline to then make beautiful.

---

## Core Laws & Principles

### A. Perception & Visual Organization (Gestalt)

- **Law of Proximity** — Elements placed close together are read as related. *Apply:* group related fields/actions tightly; add real space between unrelated groups instead of dividers.
- **Law of Similarity** — Similar-looking elements are read as the same type/function. *Apply:* one visual style per function (all primary actions look alike; don't reuse a style for two different meanings).
- **Common Region** — Elements sharing a visible boundary (card, background) are read as one group. *Apply:* use containers/cards to group related content instead of relying on spacing alone in dense UIs.
- **Uniform Connectedness** — Elements visually connected (line, arrow, shared color) are read as related, even far apart. *Apply:* connect steps of a process with a visible line/progress track.
- **Law of Prägnanz (Simplicity)** — People perceive the simplest possible interpretation of a shape/layout. *Apply:* default to the simplest layout that communicates the hierarchy; remove elements that don't change what the user does next.
- **Law of Continuity** — The eye follows the smoothest path/alignment. *Apply:* align elements to a shared grid/axis; avoid staggered, unaligned edges that force the eye to jump.
- **Figure-Ground** — Users separate foreground content from background. *Apply:* keep enough contrast/depth (shadow, blur, dim) between overlays (modals, dropdowns) and the page behind them.

### B. Attention & Cognitive Load

- **Hick's Law** — Decision time grows with the number/complexity of choices. *Apply:* reduce visible options at any one moment; use progressive disclosure, sensible defaults, and categorized menus over long flat lists.
- **Miller's Law ("7±2")** — Working memory holds about 4–7 chunks at once. *Apply:* chunk long forms/lists/nav into groups of ~5±2; paginate or collapse beyond that.
- **Cognitive Load** — Every extra decision, unfamiliar term, or visual choice taxes limited mental bandwidth. *Apply:* prefer plain language over jargon, familiar icons over novel ones, and remove decorative elements competing with functional ones.
- **Chunking** — Grouped information is remembered/scanned better than a continuous stream. *Apply:* break long text/numbers into labeled groups (phone numbers, card numbers, multi-step forms).
- **Selective Attention / Banner Blindness** — Users automatically tune out anything that *looks* like an ad or unrelated chrome. *Apply:* never style genuinely important content (errors, key actions) like a banner/ad; keep critical info inline with content, not in a sidebar/carousel.
- **Choice Overload** — Too many equally-weighted options *reduces* decision confidence and completion rate. *Apply:* highlight one recommended/default option; cap comparison tables and choice lists; use "show more" for the long tail.
- **Empty State Guidance** — A blank/zero-data state is often the user's first impression of a feature. *Apply:* never ship a bare "no data" message; explain what will appear here and give one clear action to fill it (e.g. "No projects yet — create your first one").
- **Occam's Razor (UX version)** — Given two designs of equal function, the simpler one wins. *Apply:* when unsure between two layouts that do the same job, ship the one with fewer elements/steps.

### C. Memory & Recall

- **Serial Position Effect** — People best remember the first and last items in a list. *Apply:* put the most important nav items/actions at the start or end, not buried in the middle.
- **Von Restorff Effect (Isolation Effect)** — The one visually distinct item in a group is what's remembered/noticed. *Apply:* give exactly one primary action a genuinely distinct style per screen; if everything is highlighted, nothing is.
- **Zeigarnik Effect** — Incomplete tasks stay top-of-mind more than completed ones. *Apply:* use progress bars/checklists/"3 of 5 steps done" to pull users back to unfinished flows (onboarding, checkout, setup).
- **Peak-End Rule** — People judge an experience mainly by its most intense moment and its ending. *Apply:* invest disproportionate polish in the single hardest/most emotional step and in the final confirmation/success screen — not evenly across every screen.

### D. Interaction & Effort

- **Fitts's Law** — Time to reach a target depends on its size and distance; bigger + closer = faster/easier to hit. *Apply:* make frequent/important targets (primary buttons, close icons) large and close to where the eye already is; keep destructive actions smaller or farther from safe ones. On mobile, this becomes the **thumb zone**: keep primary actions in the lower two-thirds of the screen, reachable one-handed, not tucked in the top corners.
- **Tesler's Law (Conservation of Complexity)** — Every system has an irreducible amount of complexity; the only choice is whether the user or the system handles it. *Apply:* push complexity into smart defaults, auto-detection, and system logic instead of onto user-facing forms/settings.
- **Doherty Threshold** — Interactions feel "instant" only under ~400ms response time; above that, engagement and flow drop off. *Apply:* show optimistic UI/skeletons/instant feedback for anything that might take longer than ~400ms; never leave an action with zero feedback while it processes. Match the feedback type to what's known: **skeleton screens** when the layout of incoming content is predictable, a **spinner** for short unpredictable waits with no layout to preview, a **progress bar** when completion is actually measurable (uploads, multi-step jobs) — a fake/indeterminate progress bar is worse than an honest spinner.
- **Motion & Animation** — Motion should communicate state/relationship, not decorate. *Apply:* keep transitions short (~150–300ms), use ease-out for things entering and ease-in for things leaving, and never let animation be the *only* carrier of essential information (pair with a static cue too).
- **Goal-Gradient Effect** — Motivation to finish increases as the perceived finish line gets closer. *Apply:* show progress that visibly accelerates (e.g. pre-fill the first step of a progress bar) rather than starting flows at a discouraging 0%.
- **Postel's Law (Robustness Principle)** — Be liberal in what you accept from users, strict in what you output/require. *Apply:* accept flexible input formats (phone numbers, dates, casing) and normalize them; don't force users to match your exact expected format.

### E. Trust, Familiarity & Motivation

- **Jakob's Law** — Users spend most of their time on *other* products, so they expect yours to work the same way. *Apply:* use conventional placement/behavior for nav, search, cart, back-buttons, form controls; save true novelty for the parts of the product that are actually your differentiator.
- **URL State & Deep-Linkability** — On the web, the back button, refresh, and shareable links are part of users' basic mental model. *Apply:* reflect meaningful UI state (open modal, active tab, filters, search query, pagination) in the URL so back/forward/refresh/share all behave predictably — don't trap state only in memory.
- **Just-in-Time Permission Requests** — Asking for notifications/location/camera/mic access before the user has a reason to want it gets reflexively denied, often permanently. *Apply:* request a permission at the exact moment the user takes an action that needs it (e.g. ask for notifications when they hit "remind me"), with a plain-language reason, never on first load.
- **Aesthetic-Usability Effect** — Users perceive attractive design as *more usable*, even when it isn't more functional. *Apply:* polish is not wasted effort, but never let it substitute for real usability — pair it with the laws above, don't use it to mask confusing flows.
- **Pareto Principle** — Roughly 80% of usage concentrates on ~20% of features. *Apply:* optimize the primary path aggressively for that core 20%; let edge-case features be functional-but-plain, reachable via progressive disclosure.
- **Parkinson's Law** — A task expands to fill the time/space given to it. *Apply:* constrain forms/inputs to what's actually needed (don't add optional fields "just in case") — spare fields get filled with noise or abandoned.

### F. Errors, Bias & Trust

- **Never Lose User Input** — Losing typed/entered work to a crash, accidental navigation, or session timeout is one of the most trust-destroying failures possible. *Apply:* persist draft state (local storage, autosave, or server draft) for anything longer than a couple fields; warn before navigating away from unsaved changes.
- **Error Prevention > Error Messages** — Preventing a mistake beats a good error message about it. *Apply:* disable invalid actions, use input masks/constraints, confirm destructive actions — don't rely solely on after-the-fact validation text.
- **Recognition over Recall** — Recognizing an option is easier than recalling it from memory. *Apply:* show available options/actions visibly (menus, autocomplete, recent items) instead of requiring users to remember commands/values.
- **Anchoring Bias** — The first number/option shown skews judgment of everything after it. *Apply:* order pricing/plan tiers deliberately (e.g. show the anchor plan first) — be aware this cuts both ways and don't use it to mislead.
- **Confirmation Bias in testing** — Designers over-trust feedback that confirms their existing choice. *Apply:* when reasoning about a design, actively state the strongest reason it might fail before defending it.
- **Security & Credential Fields** — Password/OTP/payment fields have their own failure modes that regular inputs don't. *Apply:* allow pasting into password fields (don't block it — it breaks password managers), provide a show/hide toggle, set proper `autocomplete`/`inputmode` attributes, and give real-time strength/format feedback instead of only rejecting on submit.

### G. Content & Microcopy

- **Plain-Language Rule** — Every label, button, and error should read like something a person would say, not a system log. *Apply:* replace jargon/internal names ("Submit request ID") with task language ("Send request").
- **Action-Oriented Labels** — Buttons should name the action's result, not a generic verb. *Apply:* prefer "Delete account" over "OK"; prefer "Save changes" over "Submit".
- **Error Message Formula** — A good error states what happened, and what to do next — never a bare code. *Apply:* "This card was declined. Check the number or try another card," not "Error 402."
- **Confirmation Wording** — Destructive-action confirmations should restate the specific consequence, not a generic prompt. *Apply:* "Delete 12 photos? This can't be undone," not "Are you sure?"
- **Escalate Confirmation to the Stakes** — Not every destructive action deserves a blocking modal. *Apply:* cheap/reversible actions (archive an email, remove a list item) get an inline toast with "Undo"; expensive/irreversible ones (delete account, permanent purge) get a blocking confirm — don't make users click through a modal for something a 5-second undo would cover, and don't let a truly irreversible action skip confirmation just to reduce friction.

### H. Ethical Guardrails — Dark Patterns to Avoid

These patterns "work" short-term but erode trust; never use them, even if they'd technically serve a stated business goal.

- **Roach Motel** — easy to get in, hard to get out (one-click subscribe, multi-step cancel). *Apply:* cancelling/unsubscribing should be at least as easy as signing up.
- **Confirmshaming** — guilt-tripping copy on the decline option ("No thanks, I don't want to save money"). *Apply:* neutral, respectful wording for both the accept and decline options.
- **Forced Continuity** — silently converting a free trial to a paid plan with no clear warning. *Apply:* notify before charging, with an easy, visible opt-out.
- **Sneaking / Bait-and-Switch** — adding items, fees, or opt-ins the user didn't choose (pre-checked add-ons, fees revealed at the last step). *Apply:* nothing gets added to a cart/total without an explicit user action.
- **Fake Urgency/Scarcity** — countdowns or "only 2 left" that aren't real. *Apply:* only show urgency/scarcity signals backed by real data.
- **Manipulative Consent** — cookie/tracking/data banners where "Accept All" is one big button and "Reject"/"Manage" is a tiny link or buried in a second screen. *Apply:* give accept and reject equal visual weight and equal number of clicks.

---

## Nielsen's 10 Usability Heuristics (fast checklist)

1. **Visibility of system status** — always show what's happening (loading, saved, errors, progress).
2. **Match between system and the real world** — real words and concepts, not internal jargon or database terms.
3. **User control and freedom** — clear undo/cancel/back out of every flow, especially destructive ones.
4. **Consistency and standards** — same word/icon/action means the same thing everywhere in the product.
5. **Error prevention** — see Section F above; prevent before you have to explain.
6. **Recognition rather than recall** — surface options; don't make users remember them.
7. **Flexibility and efficiency of use** — good defaults for novices, shortcuts/power-features for experts.
8. **Aesthetic and minimalist design** — every element on screen must earn its place.
9. **Help users recognize, diagnose, and recover from errors** — plain-language errors that say what happened and what to do next, not error codes alone.
10. **Help and documentation** — searchable, task-focused help available without derailing the current task.

---

## Accessibility Non-Negotiables

These sit at the top of the Priority Hierarchy — never trade these away for aesthetics:

- **Contrast**: body text ≥ 4.5:1, large text/icons ≥ 3:1 against its background (WCAG AA) — check this in dark mode too, not just the light theme.
- **Never color alone**: pair color-coded meaning (error/success/status) with an icon, label, or pattern.
- **Keyboard access**: every interactive element reachable and operable via keyboard, with a visible focus state.
- **Focus management**: modals/overlays trap focus while open and return it to the triggering element on close; announce dynamic content (toasts, inline errors, live updates) via ARIA live regions so screen-reader users aren't left behind.
- **Target size**: interactive targets comfortably tappable (~44×44px minimum on touch).
- **Alt text / labels**: meaningful `alt` on informative images, real `<label>`s on form inputs, not placeholder-only labels.
- **Motion respect**: avoid essential information conveyed only through animation; respect reduced-motion preferences where feasible.
- **Semantic structure**: real headings, lists, and landmarks — not styled `<div>`s pretending to be interactive elements.
- **Internationalization & RTL**: for right-to-left languages (Persian, Arabic, Hebrew), mirror the whole layout, not just text alignment — nav, directional icons (back-arrows, progress, chevrons), and reading order all flip. Also localize dates, numbers, and currency to the user's locale, and leave ~30% extra width for text expansion in translated UI (German, Finnish, etc. run longer than English).

---

## Component Quick-Reference

Building one specific element? Start with its top laws instead of scanning the whole rulebook:

| Component | Prioritize |
|---|---|
| Forms | Postel's Law, Miller's Law, Error Prevention, Tesler's Law, Recognition over Recall |
| Navigation | Jakob's Law, Hick's Law, Serial Position Effect, Fitts's Law |
| Modals / dialogs | Figure-Ground, User Control & Freedom, Fitts's Law (keep destructive actions small/far), Confirmation Wording |
| Onboarding | Zeigarnik Effect, Goal-Gradient Effect, Progressive Disclosure (Hick's), Peak-End Rule |
| Tables / dense data | Chunking, Miller's Law, Law of Similarity, Law of Continuity |
| Search | Recognition over Recall, Empty State Guidance, Doherty Threshold, Hick's Law (filters) |
| Settings / preferences | Miller's Law, Recognition over Recall, Hick's Law, Chunking |
| Error / empty states | Error Message Formula, Empty State Guidance, Recognition over Recall |
| Pricing / plans | Anchoring Bias, Choice Overload, Von Restorff Effect, Dark Patterns (H) |
| Checkout / destructive flows | Fitts's Law, Error Prevention, Confirmation Wording, Doherty Threshold |

---

## Pre-Ship Checklist

Before presenting any finished UI to the user, silently verify:

- [ ] One clear primary action per screen/section (Von Restorff), everything else visually secondary.
- [ ] No single group of options/nav items exceeds ~7 items without chunking or progressive disclosure (Miller's, Hick's).
- [ ] Every async action gives feedback within ~400ms, even if just a loading state (Doherty).
- [ ] Frequent/important targets are large and reachable; risky ones are not accidentally easy to hit (Fitts's).
- [ ] Destructive actions are confirmable/undoable, escalated to their stakes — toast+undo for cheap/reversible, blocking confirm for irreversible (Error Prevention, User Control).
- [ ] Forms/flows longer than a couple fields autosave or warn before discarding unsaved input (Never Lose User Input).
- [ ] Modals trap focus and return it on close; dynamic content changes are announced to screen readers (Focus Management).
- [ ] Layout, nav, and controls follow conventions users already know unless novelty is the actual point (Jakob's).
- [ ] Contrast (light *and* dark mode), focus states, labels, and target sizes meet the Accessibility section above.
- [ ] Nothing on screen is purely decorative at the cost of clarity (Prägnanz, Occam's Razor).
- [ ] The hardest step and the final/success state got extra craft, not just uniform effort everywhere (Peak-End).
- [ ] No dark patterns snuck in (confirmshaming, hidden costs, forced continuity, fake urgency, unequal consent options) to hit a business goal (Section H).
- [ ] Empty and error states explain what's missing/wrong and give a next action, not just a blank or technical message.
- [ ] If the interface targets an RTL language, layout and directional icons are mirrored — not just text-aligned.
- [ ] Modal/tab/filter state that matters is reflected in the URL; permission prompts (notifications, camera, location) fire on relevant action, not on load.
- [ ] Password/credential fields allow paste and offer a show/hide toggle.
- [ ] Only after all of the above hold: is this genuinely beautiful, distinctive, and delightful?

If something fails a check above, fix it before presenting — don't wait to be asked.