workbuddy_skills/open-design/craft/laws-of-ux.md

# Laws of UX craft rules

Universal cognitive, perceptual, and behavioral heuristics that decide
what a UI composes — how many pricing tiers fit on a screen, where a
primary action anchors in scanning order, when a progress indicator
earns its place, why a settings list needs grouping. The active
`DESIGN.md` decides brand visual language; the existing craft files
decide rendering rules (color, typography, motion, states, ARIA, RTL,
forms); this file decides composition rules grounded in named research.

> Distilled from primary sources: Hick (1952) + Hyman (1953), Miller
> (1956) for chunking / `7±2` channel capacity, Cowan (2001) for the
> modern ~4 working-memory bound, Fitts (1954), Wertheimer (1923) for
> proximity / similarity / Prägnanz, Palmer (1992) for Common Region,
> Palmer & Rock (1994) for Uniform Connectedness, Kahneman /
> Fredrickson / Schreiber / Redelmeier (1993) for Peak-End, Zeigarnik
> (1927), Csíkszentmihályi (1975), Hull (1932), von Restorff (1933),
> Broadbent (1958), Sweller (1988), Postel (RFC 760, 1980), Carroll &
> Rosson (1987), Tversky & Kahneman (1974) for Anchoring, Kurosu &
> Kashimura (1995), Iyengar & Lepper (2000), Toffler (1970), Pareto
> (c.1906) / Juran (*Quality Control Handbook*, 1951), Ebbinghaus
> (1885), Ockham (14th c.), Tesler at Apple (1980s), Nielsen (2000),
> Norman *POET* (1988), Parkinson (1955).

## Prior art and scope

Existing public catalogs of UX heuristics (Yablonski's lawsofux.com,
NN/g's 10 usability heuristics, Material 3 motion + interaction
guidance, Apple HIG, Baymard Institute checkout research) inventory the
laws but rarely tie each one to a concrete code-gen directive. This
file does the translation: every entry ends with one actionable move
for an HTML / Tailwind / React-emitting agent. Sibling craft files
(`accessibility-baseline.md`, `state-coverage.md`, `typography.md`,
`anti-ai-slop.md`, `color.md`, `animation-discipline.md`,
`form-validation.md`) own the auto-checked rules; this file names the
underlying law and surfaces the folklore. Out of scope: Weber-Fechner
psychophysics and Signal Detection Theory — both apply to UI but the
prompt-emission directives are too narrow to earn a slot here. Add
later if a skill needs them.

The rules below are guidance, not auto-checked. Reviewers and the agent
apply them; the linter does not. Where a law has a sibling rule already
auto-checked elsewhere — touch-target floor in
`accessibility-baseline.md`, the 300 ms / 2 s / 10 s / 30 s / 60 s
loading thresholds in `state-coverage.md`, ALL CAPS letter-spacing in
`typography.md`, the indigo / gradient / emoji-icon list in
`anti-ai-slop.md` — the entry below cross-references rather than
duplicates.

## Perception and visual grouping

Five Gestalt laws plus three attention-and-recognition laws govern how
the eye groups elements before the brain reads them.

- **Law of Proximity** (Wertheimer, 1923). Objects near each other read
  as a group. Cheapest grouping signal — cheaper than borders or shared
  color. Apply variable vertical rhythm: 8–12 px within a group,
  32–48 px between groups. Uniform spacing reads as nothing being
  grouped.
- **Law of Similarity** (Wertheimer, 1923). Visually similar elements
  read as a group. Equivalent affordances must share treatment — every
  list row identical class set, every secondary button identical, every
  destructive action identical. Visible deviation is reserved for the
  one item meant to draw attention (the recommended pricing tier, the
  selected nav item).
- **Law of Common Region** (Palmer, 1992). A shared bounded area binds
  enclosed elements. Use enclosure when proximity is not enough — and
  reserve it. Concrete numbers: padding ≥16 px inside the region,
  distinct surface (border + tinted background, or card chrome at
  ≥1 px hairline). A page where every section is bordered destroys the
  signal.
- **Law of Prägnanz / Good Figure** (Wertheimer, 1923). The eye
  resolves complex layouts into the simplest underlying form. Designs
  that align with a clear underlying grid (12-column, F-pattern,
  4-quadrant) feel inevitable; ornate breaks that add nothing semantic
  feel arbitrary.
- **Law of Uniform Connectedness** (Palmer & Rock, 1994). The
  strongest grouping signal in the Gestalt hierarchy: connected lines,
  shared toolbars, or bracketing containers tie items together more
  strongly than proximity or similarity. Use for wizard steps,
  comparison sets, and explicit navigation flows.
- **Selective Attention** (Broadbent, *Perception and Communication*,
  1958). Cognitive bandwidth is finite. Users filter aggressively and
  ignore anything that looks irrelevant to their goal — banner blindness
  comes from this. Reserve the strongest visual contrast for the single
  goal-relevant action; let supporting content recede in weight.
- **Von Restorff Effect** (von Restorff, 1933). The item that differs
  from a uniform field is the one most likely to be remembered. Make
  the recommended pricing tier, the active nav item, the warning state
  visually distinct. Pair contrast with a non-color signal (icon, text
  label, position) — `accessibility-baseline.md` rules out color-alone
  signaling.
- **Aesthetic-Usability Effect** (Kurosu & Kashimura, Hitachi Design
  Center, 1995). Visual polish biases perceived usability. Refined
  typography, generous whitespace, and a calm palette earn the benefit
  of the doubt for minor friction. Never substitutes for measurable
  usability or for `state-coverage.md`'s required-states rule.

## Decision-making

Six laws govern how fast and how well users decide when an interface
offers a choice.

- **Hick's Law** (Hick, 1952; Hyman, 1953 replication). Decision time
  grows roughly log(n+1) with the number of equivalent options. Cap any
  single decision-screen to 3–5 visible primary options; collapse the
  rest behind a "More" / progressive disclosure pattern; visually
  distinguish the recommended choice. Aggressive truncation that hides
  the path forward is the opposite failure mode — surface the full
  option set, just don't render every option at the same visual weight.
- **Choice Overload** (Iyengar & Lepper, *Journal of Personality and
  Social Psychology*, 2000; framing dates to Toffler, *Future Shock*,
  1970). Too many roughly-equivalent options stall or abandon the
  decision. Pricing pages: 3–4 tiers, exactly one marked recommended.
  Product grids: 6–9 hero cards above the fold. Settings panels: ≤5
  named groups. Never emit a flat wall of equivalents.
- **Anchoring** (Tversky & Kahneman, *Science* 185:1124–1131, 1974).
  The first number a user sees re-weights every subsequent number.
  Place the recommended pricing tier where it anchors the comparison;
  render yearly-billing savings as concrete dollar deltas, not just
  percentage badges; pre-select the safer default in radio groups.
  Visual weight matches intended decision weight.
- **Pareto Principle / 80-20** (Pareto, c.1906; Juran, *Quality Control
  Handbook*, 1951 — popularized the management-application framing). A
  small share of features drives most of the value. Identify the 2–3 actions
  that drive the dominant journey for the target persona; emphasize
  those visually; demote the long tail to overflow menus, footer
  surfaces, or settings.
- **Tesler's Law / Conservation of Complexity** (Tesler, Apple, 1980s).
  Every product has an irreducible amount of complexity. The design
  choice is *where* it lives — engineering team, interface, user — not
  whether to eliminate it. When complexity reaches the user, surface
  contextual guidance (tooltips, smart defaults, inline empty-state
  coaching, progressive disclosure) at the exact step where it
  surfaces. Hiding it is not the same as removing it.
- **Occam's Razor** (Ockham, 14th c.). Among options that explain the
  data equally well, prefer the one with the fewest assumptions. Specify
  a minimal element inventory; forbid decorative chrome that doesn't
  serve a stated user task. The law constrains assumptions, not feature
  count — a "minimum viable" framing misreads it.

## Memory and learning

Five laws cover how working memory handles information density and
what the user retains afterward.

- **Miller's Law and Chunking** (Miller, *The Magical Number Seven,
  Plus or Minus Two*, *Psychological Review*, 1956 — channel capacity /
  `7±2` and chunking; Cowan, *Behavioral and Brain Sciences* 24:1, 2001
  for the modern ~4-item working-memory bound). Working memory holds
  about four items reliably and up to seven for short-term recall. Each
  slot can hold a *larger familiar unit*, constrained by the user's
  domain knowledge — chunking does not let you pack arbitrary content
  into a single slot. Often misread as a rule about menu length;
  Miller's paper is about chunks. Group related fields with clear
  section headings, dividers, or card containers. A settings page with
  sections "Account / Notifications / Privacy / Billing / Danger zone"
  beats one flat list of 30 toggles.
- **Working Memory** (Baddeley & Hitch, 1974; lineage to Atkinson &
  Shiffrin, 1968). Items decay in seconds without rehearsal. Recognition
  beats recall: persisting prior context across screens, marking visited
  elements, and surfacing comparison views beats forcing the user to
  memorize. On dashboards specifically: sticky filter chips, last-N
  selections persisted, breadcrumbs that include applied filters.
- **Serial Position Effect** (Ebbinghaus, *Über das Gedächtnis*, 1885).
  Recall favors the extremes — primacy at the start, recency at the
  end — while middle items fade. Anchor the most important nav items at
  the leftmost and rightmost positions of a horizontal menu; cluster
  utilities in the middle.
- **Peak-End Rule** (Kahneman, Fredrickson, Schreiber, Redelmeier,
  *Psychological Science*, 1993). Memory of an experience is dominated
  by the emotional peak and the ending, not the average. Stage a
  high-effort celebratory success state; let intermediate steps stay
  calm. Mediocre middles matter less than a strong close. The peak
  belongs at the *end* of a flow, not as arbitrary mid-flow motion —
  `animation-discipline.md` rejects motion that performs (rather than
  confirms) a state change.
- **Zeigarnik Effect** (Zeigarnik, *Über das Behalten erledigter und
  unerledigter Handlungen*, 1927). Uncompleted tasks create cognitive
  tension that pulls the user back. Visible progress ("3 of 5 steps",
  greyed-out next sections) converts that tension into completion
  pressure. Reserve for genuinely beneficial flows like onboarding;
  applying the same lever to streaks, daily-quest counters, or notification-
  reduction nags is a dark pattern.

## Interaction and motor

Five laws cover how fast and how accurately users can act on the UI.

- **Fitts's Law** (Fitts, *Journal of Experimental Psychology*, 1954).
  Time to acquire a target depends on its distance and size — bigger
  and closer is faster. Spacing between adjacent hit zones matters as
  much as size. Pair with `accessibility-baseline.md`'s 24 × 24 CSS px
  AA touch-target floor; on mobile, place high-frequency controls in
  the natural thumb arc.
- **Doherty Threshold** (Doherty & Thadani, *IBM Systems Journal*,
  1982). Sub-second feedback keeps users in flow; latency above ~1 s
  breaks attention. The implementable directive lives in
  `state-coverage.md`'s loading-threshold table (no indicator under
  300 ms; skeleton 300 ms – 2 s; labelled spinner 2 – 10 s; determinate
  bar with cancel 10 – 60 s; stop and offer error/retry past 60 s).
  This entry exists to name the underlying law and flag its folklore
  (the 400 ms number doesn't appear in the 1982 paper — see
  `animation-discipline.md` for the 400 ms folklore trace).
- **Flow** (Csíkszentmihályi, *Beyond Boredom and Anxiety*, 1975). Flow
  sits in the balance between challenge and skill — too hard breeds
  frustration, too easy breeds boredom. Continuous feedback and a clear
  sense of control keep the user inside the state. System friction and
  latency are the fastest ways to break it.
- **Goal-Gradient Effect** (Hull, *Psychological Review*, 1932; Kivetz,
  Urminsky, Zheng, 2006 for the punch-card replication). Motivation to
  finish rises as the goal gets closer. Multi-step flows render with a
  prominent progress indicator that reflects *real* endowed progress —
  show completed prerequisites when they truly exist (saved profile,
  imported team, prior survey answer). When no real prerequisite
  exists, render the current step honestly as `1 of N` with the
  empty/current-step state clearly marked. Hull's hypothesis is
  descriptive; treating it as license for fabricated progress, streak
  dark patterns, or loyalty-program quota inflation is a misread.
- **Postel's Law / Robustness Principle** (Postel, RFC 760, 1980). "Be
  liberal in what you accept, conservative in what you send." Take
  input in whatever shape users naturally give it (phone numbers with
  or without dashes, dates in mixed formats, percentages with or
  without `%`); normalize internally to a canonical form; emit one
  consistent format on output. The error-timing and ARIA-wiring half
  lives in `form-validation.md`; the input-tolerance half is the
  directive above. RFC 9413 (Thomson, IAB, 2023; built on the earlier
  `draft-iab-protocol-maintenance`) retracts the maxim for protocol
  design citing security surface; the UX-input application stands.

## Behavior and expectation

Five laws cover what users predict and how that prediction interacts
with the rendered surface.

- **Jakob's Law** (Nielsen, Nielsen Norman Group, 2000). Users spend
  most of their time on other sites and expect yours to work the same.
  Reuse category convention — nav placement, cart icon, settings gear,
  primary CTA in the upper right of a SaaS landing — so the user spends
  zero cycles relearning interaction grammar. Novelty must earn its
  keep against the convention's ROI; "innovate everywhere" is the
  opposite failure mode.
- **Mental Model** (Craik, *The Nature of Explanation*, 1943; Norman,
  *POET / The Psychology of Everyday Things*, 1988). Every user
  arrives with a prior built from competitor products and the physical
  world. When the prediction holds, the product feels intuitive; when
  it breaks, friction shows up as confusion, not curiosity. When the
  brief names a reference product, anchor explicitly — capture the
  reference in the prompt and the agent inherits a transferable
  interaction grammar.
- **Paradox of the Active User** (Carroll & Rosson, in *Interfacing
  Thought: Cognitive Aspects of Human-Computer Interaction*, MIT Press,
  1987, pp. 80–111). Users skip the manual and start using the
  software immediately, even when reading it would speed them up. Bake
  guidance into the surface itself — empty-state coaching, inline
  tooltips, contextual hints — at the action point.
- **Parkinson's Law** (Parkinson, *The Economist*, 1955). Work expands
  to fill the time allotted to it. Loose interfaces let users dawdle;
  cut friction and pre-fill what you can — autofill, smart defaults,
  saved state — so a checkout finishes faster than the user expected.
  Beating anticipated duration becomes the felt win.
- **Cognitive Load** (Sweller, *Cognitive Science*, 1988). Total
  mental effort splits into intrinsic (the task's inherent difficulty)
  and extraneous (poor layout, jargon, inconsistent patterns, visual
  noise). Designers can't reduce intrinsic load; they own extraneous
  fully. The visual-restraint directives (single accent in `color.md`,
  three-weight typography rhythm in `typography.md`, P0 anti-default
  list in `anti-ai-slop.md`) already constrain extraneous load; this
  entry exists to name the cognitive cost the sibling rules reduce.

## Common mistakes (lint these)

Folklore corrections that don't survive a primary-source check, in the
same vein as the busts already documented in `animation-discipline.md`
and `accessibility-baseline.md`. The first three are attribution
corrections (year / venue / institution) the body entries already
applied — restated here so a reviewer reading just this section sees
them. The remainder are folklore not addressed in the body.

- "Anchoring effect = Tversky & Kahneman 1972." Wrong year. The
  *Science* paper introducing the anchoring framing is 1974; the 1972
  paper is "Subjective probability: A judgment of representativeness"
  (different work).
- "Tesler's Law was developed at Xerox PARC." Tesler left PARC for
  Apple in 1980; the Conservation-of-Complexity formulation traces to
  his Apple years.
- "Paradox of the Active User was a CACM article." It's a chapter in
  Carroll's *Interfacing Thought* (MIT Press, 1987), not CACM.
- "Selective Attention = solved by red dots and badges." Repeated
  attention-grabbers train banner blindness. Reserve the strongest
  contrast for one goal-relevant action per surface.
- "Fitts's Law alone is enough for touch targets." Fitts gives the
  speed-accuracy tradeoff. WCAG 2.2 SC 2.5.8 sets the AA floor at
  24 × 24 CSS px (`accessibility-baseline.md`); iOS HIG suggests
  44 × 44 pt; Material 3 suggests 48 × 48 dp. Fitts plus the
  platform floor — never just Fitts.