Ux Psychology

You apply how people perceive, decide, and remember to the UI being built or reviewed. Every rule cites the research it rests on and says when it does not apply — these are strong predictions about people, not laws, so a rule that does not fit the product is set aside, not forced.

1. Pick the Mode

Decide from the request; do not ask.

• Build mode — the task creates or changes UI. Apply the rules as constraints while writing the code. Stay quiet about them: mention a principle only when it changed a decision, in one line (e.g. "kept one primary button — von Restorff"). No report.
• Audit mode — the user asks to review, audit, or critique the UX, or asks why users drop off, get confused, or don't convert. Produce the report in Step 4.

2. Detect the Platform

Read the manifest as prose and load only the matching guides:

React Native/Expo: add references/apple.md or references/android.md only when the change behaves differently per OS (back navigation, sheets, pickers, haptics, system dialogs). Expo web output also loads references/web.md. A monorepo with several apps loads the guide for the app being touched. For another UI stack (Flutter, Kotlin Multiplatform), use references/cross-platform.md and the closest native guide.

3. Rules

Each rule file has a When building constraint and a When auditing check. Read a rule when the screen in front of you involves what its "Applies to" column names.

rules/deceptive-patterns.md overrides every other rule: when a persuasion rule (defaults, reciprocity, commitment, social proof, goal gradient) would work against the user's interest, it is a deceptive pattern, not a technique.

4. Build Mode

New product or flow, nothing built yet — settle these before the first screen, from the request and the codebase (ask only for what neither answers):

1. Who the user is and their one to three main tasks — for a landing or marketing page, why they would care to buy
2. The one primary action of each screen
3. The navigation pattern the platform expects (tab bar, sidebar, stack)
4. How dense the information should be (glanceable consumer app vs expert tool)
5. Where people will drop off — first run, empty states, sign-up and permission asks
6. Where the user will feel exposed — paying, deleting, sending, granting access — and how they should feel at the end (rules/emotional-design.md)

Then build with the rules as constraints.

Existing UI — follow the conventions already in the codebase (internal consistency is part of rules/jakobs-law.md), and apply the rules to the part being changed. Do not redesign screens nobody asked about.

5. Audit Mode

1. Scope: the files, screens, or flows named; otherwise every user-facing screen. In Claude Code, hand a whole-app or multi-screen audit to the ux-audit agent when it is available, so the files it reads stay out of the main context.
2. Map each screen's job and primary action from its code before judging it.
3. Check each screen against the rules whose "Applies to" matches it, and the platform guide.
4. Report, grouped by impact (CRITICAL first):

### HIGH — Fitts's law
- app/(tabs)/settings.tsx:42 — "Delete account" sits 8pt from "Save" → move it to a separate section at the bottom, behind a confirmation

End with the counts per impact, then this limit, stated plainly: these principles predict problems but cannot confirm them. Recommend checking the top findings with 3–5 real users per distinct user type, and testing again after fixing.

Fix nothing in audit mode unless asked; when asked, fix in impact order.

Boundaries

• Visual styling (colour palettes, type scales, spacing systems) and animation timing (easing, springs, duration) are out of scope — defer to a visual-design or animation skill when one is installed. This skill decides whether an action needs feedback; those decide how it looks and moves.
• Accessibility overlaps where noted (target size, colour-only signals, focus, input purpose); when the accessibility skill is available, apply it alongside this one while building UI, and use it for full WCAG audits.