ux-psychology

name	ux-psychology
description	Use when a design decision needs a cautious cognitive rationale involving Gestalt grouping, affordances, memory, attention, mental models, or bias. Do not use as proof of user behaviour or for heuristic inspection; route claims to research/testing or heuristic evaluation.
metadata	{"portable":true,"category":"05-ux-process-research-and-psychology","compatible_with":["claude-code","codex"]}

Ux Psychology

Acknowledgement: Shared by Peter Bamuhigire, techguypeter.com, [phone].

Use when

• A design or layout needs grouping/hierarchy diagnosed through Gestalt lenses (proximity, similarity, common region, closure, continuity).
• You must justify or defend UX quality on a premium $20k+ build, naming the principle a choice rests on rather than asserting taste.
• A flow feels confusing or high-friction and you need a cognitive-load read: Miller's 7±2, chunking/stacking, Sweller's intrinsic vs. extraneous load.
• An interaction's affordances are unclear and you want the four-stage discipline — Presence, Visibility, Recognizability, Intelligibility — applied to controls and signifiers.
• You need to map a screen against Nielsen's 10 heuristics or Norman's three levels (visceral/behavioral/reflective) and turn each gap into a concrete change.
• Aligning stakeholders on which HCI paradigm (Building / HIP / Design Thinking) a decision belongs to, or declaring UX scope (Single Interaction / Journey / Relationship) in a proposal.
• Spotting System 1/2 friction or dark patterns that erode trust on a conversion path.

Do not use when

• You need to run usability sessions, interviews, or analyze test results — use 05-ux-process-research-and-psychology/ux-research-and-usability-testing.
• You want a structured heuristic walkthrough or design critique deliverable — use 05-ux-process-research-and-psychology/heuristic-evaluation-and-design-critique (this skill supplies its psychology vocabulary, not the critique format).
• The work is visual/brand differentiation or component-level UI patterns — use 04-web-and-ui-design/distinctive-by-design, interaction-design-patterns, or motion-design.
• You only need a non-psychological correctness check (copy, accessibility audit, performance).

Required inputs

Input	Source	Evidence
User task, context, and consequence	Research or approved brief	Observed behaviour or clearly labelled assumptions
Interface/flow under consideration	Stable design or build	Versioned screen and decision point
Competing design hypotheses	Design/product team	Alternatives and predicted cognitive effect

• The specific screen, flow, or interaction under review (mockup, URL, or described artifact) — concrete enough to point at named elements.
• The user goal and decision context for that screen, so cognitive-load and affordance judgments are anchored to a real task.
• Brand, audience, regional, and conversion context that determines whether a psychological tradeoff is acceptable.

Workflow

1. Read the artifact and the decision context before applying rules.
2. Use only the parts of the preserved guidance that matter to the current task.
3. Review or revise the work using this skill as a focused quality lens.
4. Return actionable changes or acceptance criteria instead of abstract theory.

Decision Rules

Condition	Choice	Wrong-choice failure
Claim concerns likely comprehension	Use principle as hypothesis, then test	Psychology is treated as deterministic proof
Many items must be scanned	Meaningful chunking and progressive disclosure	Arbitrary limits hide necessary information
Control meaning is unfamiliar	Visible signifier, label, and feedback	Minimalism creates invisible affordances

Capability Contract

• Must inspect the interface and distinguish sourced evidence from inference; analysis is read-only unless redesign is requested.
• May recommend tests or in-scope changes, but may not diagnose users, manipulate vulnerabilities, or claim universal cognitive effects.

Degraded Mode

• If no user/task context exists, stop prescriptive claims and return competing hypotheses.
• Without research access, label principles as provisional and propose a validation method. Recover a contradicted hypothesis by updating the rationale and design, not dismissing user evidence.

Quality Standards

• Recommendations must be concrete enough to apply immediately.
• Changes should improve consistency, usability, or credibility without flattening the brand.
• The standard should support downstream implementation rather than slow it down.

Anti-patterns

• Do not apply every rule mechanically when only a subset is relevant.
• Do not give generic critique with no change implications.
• Do not override project reality with taste-based preferences alone.
• Do not treat a cognitive principle as proof of behaviour. Correction: frame and test a falsifiable hypothesis.
• Do not apply a universal item-count cap. Correction: chunk by meaning and test comprehension/findability.

Outputs

Output	Consumer	Evidence and acceptance
Cognitive design rationale	Product and design	Principle, observed issue, hypothesis, alternative, and limitation are explicit
Validation plan	Research and QA	Task, participants/evidence, predicted result, and disconfirmation signal are defined

• Revisions, review findings, acceptance criteria, or quality guidance tied to the artifact under review.

Notes

• Treat this SKILL.md as the portable execution layer for both Claude Code and Codex.
• Preserve existing project behavior unless the current task explicitly requires a change.

Examples

• examples/psychology-critique-worked.md — a worked critique of one real screen (a coffee-subscription checkout) through named psychology lenses: Gestalt grouping, Nielsen's heuristics, Norman's affordances/signifiers, cognitive load (Miller/Sweller), and Hick's/Fitts's law. Each finding pairs the principle with the design change it implies; ends with a findings-to-changes table.

References

• doctrine/design-doctrine.md — the Mission and Anti-Slop Charter; psychological quality is part of looking deliberately human-made, not templated.
• doctrine/references/ai-slop-taxonomy.md — the interface/product slop tells whose cognitive cost this skill explains.
• Sibling skills: 04-web-and-ui-design/distinctive-by-design, 04-web-and-ui-design/interaction-design-patterns, 08-motion-and-interaction/motion-design.
• references/legacy-guidance.md — Gestalt, Nielsen, Norman, Krug; + working-memory rules + four-stage cognitive affordance (added 2026-05-04). Read only the specific files under references/ that match the task.
• references/three-paradigms-of-hci.md — Building / HIP / Design Thinking; cockpit-voice example for stakeholder alignment
• references/three-levels-of-ux-scope.md — Single Interaction / Journey / Relationship — declare in every proposal