UX Principles

People do not read interfaces; they scan, guess from what they already know, and give up when the guess fails. This skill turns the durable findings of cognitive psychology and usability research into decisions: how many options to show, what to hide, where to put the primary action, how fast feedback must arrive, and which "growth" patterns are off the table. The outcome it protects is a user who finishes their task without having to think about the interface, and who never gets tricked into something they did not want.

Before you start

If .agents/project-context.md exists (or .claude/project-context.md), read it first and treat it as ground truth for stack, platforms, scale, design system, and constraints. Only ask for what it does not cover. If it does not exist and the task is larger than a quick fix, suggest running the project-context skill — but never block on it.

Name the user, the task, and the context of use (device, frequency, expertise) before applying any law. The same rule points in opposite directions for a first-time visitor and an expert who uses the screen 100 times a day.

Core principles

1. Design for the task, not the data model. Screens, labels, and order follow what the user is trying to get done; exposing tables, enums, and internal states is the most common UX failure in engineer-built UI.
2. Follow conventions unless you can name the gain. Users spend most of their time in other products (Jakob's law); every novel pattern costs learning time you must justify.
3. Cut extraneous load before adding help. Remove, merge, default, and defer first; tooltips and tours are what you add when you failed to simplify.
4. One primary action per view. A single visually dominant next step beats a row of equals (Hick, Von Restorff).
5. The system carries the memory, not the user. Keep context visible across steps; recognition beats recall.
6. Respond within human time limits. Acknowledge input in ≤ 100 ms, show a result or progress within ~400 ms–1 s, and let the user leave anything over 10 s.
7. Persuade only toward what the user already wants. If a pattern works only because the user misunderstands it, do not build it.

Workflow

• Frame: write one line each for user, task, frequency (first-time / occasional / daily-expert), device, and the success signal.
• Map the flow: list every step and decision from entry to done. Mark each step as declares intent, provides data, or waits. Remove or default every step you cannot defend.
• Apply the decision table below to each screen: count options per decision point, identify the primary action, check grouping and placement.
• Run the 10 heuristics (table below) against the flow, including error, empty, and slow paths, not just the happy path.
• Check response times for every action against the limits table; decide optimistic vs. pending vs. background.
• Ethics pass: check every persuasion or retention mechanic against the "never build" list. Remove anything that fails.
• Validate with people: pick the cheapest research method from the table that answers the open question; fix and repeat.

Laws of UX as decisions

Default rules for the laws that change UI decisions most often. The full set of 30 with misuse notes is in references/laws-of-ux.md.

Nielsen's 10 heuristics, as checks

Procedure, severity scale (0–4), and violations typical of complex apps are in references/heuristics.md.

Cognitive load and progressive disclosure

• Separate intrinsic from extraneous load. Intrinsic load is the task itself (choosing a plan). Extraneous load is what the design adds (decoration, duplicate info, jargon, unclear grouping). Only extraneous load is yours to remove, and removing it comes first.
• Budget per view: 1 primary action, 1–2 secondary, the rest in a menu. ≤ 4 options per decision point is a good target; 8+ means split, filter, or default.
• Progressive disclosure: show the few options most people need; put advanced ones behind a visible, labelled control ("Advanced settings"), never behind an unlabeled icon. Anything most users need goes on the first layer. Stop at 2 levels; a third level means the information architecture is wrong.
• Staged disclosure (wizard) is different: use it when everyone must pass every step in order and later steps depend on earlier answers. Show step count and allow Back without data loss.
• Smart defaults are the cheapest simplification: preselect the option most people choose, if it is also safe and honest for them.
• Hidden navigation costs discoverability. NN/g found hiding primary navigation behind a menu icon measurably reduced discoverability and increased task time. With ≤ 5 top destinations, show them (tab bar or visible nav); otherwise expose the top few and collapse the rest.

Response-time limits

Source limits: Nielsen's 0.1 / 1 / 10 s and the Doherty threshold (400 ms). Loading-pattern details live in interaction-design.

Humane design and the "never build" list

Humane by Design's principles, compressed: be transparent (say what data you collect and why; make deletion and unsubscribe easy), resilient (block, mute, report, and visibility controls ship with any social feature), empowering (users control defaults, cadence, and data), finite (natural stopping points, "You're all caught up", "Load more" over endless feeds), inclusive (flexible names, optional gender, accessibility, RTL), intentional (use friction to prevent harm, e.g. a speed bump before sharing unread links), and respectful (notifications match urgency and are configurable per category).

Never build these, whatever the metric pressure:

Legal backstops (as of 2026-09; not legal advice): EU Digital Services Act Art. 25 bans online-platform interfaces that deceive, manipulate, or materially impair free and informed decisions (Recital 67 names repeated prompts, cancellation harder than signup, and hard-to-change defaults). US FTC enforces subscription traps under Section 5 and ROSCA; its 2024 "click-to-cancel" Negative Option Rule was vacated by the 8th Circuit in July 2025 and the FTC reopened rulemaking in 2026. California's Automatic Renewal Law (AB 2863, in force July 2025) requires online cancellation as easy as signup. Pre-ticked boxes do not count as GDPR consent. Details and sources: references/humane-design.md.

Lightweight research

Default: test with real people before arguing about opinions. Pick the cheapest method that answers the question.

Write tasks as goals ("You need to invite a teammate"), not instructions ("Click Invite"). Record what people do, not what they say they would do.

Gotchas

• Treating Miller's 7±2 as a hard limit. It is about working memory, not menu length. Chunk and label; do not truncate a useful nav to 7 items by rule.
• "Simplifying" by removing labels. Icon-only toolbars and hidden menus raise load; Hick's law is about decisions, not pixels.
• Applying a law out of context. Fitts favors big targets, but a big "Delete" next to "Save" is a disaster; frequency and consequence decide placement.
• Checking only the happy path. Heuristics 1, 3, 5, and 9 are mostly about slow, failed, empty, and mistaken paths. Walk them explicitly.
• Confirm dialogs everywhere. Overused confirmations train reflexive clicking; prefer Undo for anything reversible.
• Using biases as levers against users. Scarcity, social proof, defaults, and loss framing are fine when true and in the user's interest; the same mechanisms become dark patterns when fabricated or when they hide the exit.
• Designing for the "rational" user. People skim, misread, and get interrupted; design for distracted, one-handed, first-time use unless the context says otherwise.
• Letting polish substitute for testing. Attractive prototypes get kind feedback (aesthetic-usability effect); measure task success instead.
• Citing a law without a decision. "Per Hick's law" is noise unless followed by the specific change (e.g. "move 5 of 8 actions into More").

Output format

For a design decision or UX assessment, produce:

Context: <user · task · frequency · device>
Findings (ordered by impact)
1. <Observed problem> — <principle/heuristic> — Severity <0–4> — Fix: <specific change>
...
Ethics check: <pass | patterns removed and replacements>
Open questions → research: <question> → <method, participants>

Separate Observed (seen in the UI or code), Inferred (likely, not verified), and Not checked.

References

Related skills

• interaction-design — turning these principles into states, forms, feedback, overlays, and copy.
• design-review — a full scored audit of an existing UI (it uses these heuristics).
• conversion-ux — landing pages, signup, onboarding, pricing, and checkout within the ethics floor.
• accessibility — WCAG 2.2 AA implementation details behind many of these checks.
• data-dense-ui — applying load and hierarchy rules to dashboards and tables.