@pugi/cli 1.0.0-alpha.24 → 1.0.0-alpha.241

package/skills/od-craft/references/form-validation.md

@@ -0,0 +1,223 @@
+<!-- Vendored from nexu-io/open-design@78d5637cb49d (craft/form-validation.md), Apache-2.0, Copyright 2026 Open Design contributors. Modified by Pugi: this header line added; the text below is otherwise verbatim. Paths it names (apps/daemon/src/lint-artifact.ts, pnpm lint:craft, od.craft.requires) are upstream's, not Pugi's: the Pugi port of the linter is packages/opencode/src/session/design-lint.ts. See NOTICE.md in the skill root. -->
+
+# Form validation craft rules
+
+Universal rules for form validation lifecycle, error wiring beyond the
+accessibility baseline, and the schema-as-contract layer that makes
+the same validation work on the server and the client. The active
+`DESIGN.md` decides how the field looks; this file decides *when* the
+field tells the user it's wrong, *how* the error reaches assistive
+tech, and *where* the rule lives.
+
+> Grounded in primary sources: WHATWG HTML Living Standard
+> (Constraint Validation section under "Form control infrastructure"),
+> CSS Selectors L4 (`:user-invalid`), WCAG 2.2 SC 3.3.x
+> Understanding pages, ARIA APG forms patterns, Standard Schema spec
+> (`@standard-schema/spec`), Baymard 2024 inline-validation research
+> checkout-UX benchmark, WebAIM Million 2026 forms findings.
+
+## Prior art and scope
+
+Existing OSS forms guidance for AI agents pins to one layer at a time
+— `szilu/ux-designer-skill` is UX-opinion grade with no spec anchors,
+`Community-Access/accessibility-agents/forms-specialist` is
+WCAG-anchored but AT-only and doesn't reach the platform validity
+layer or the schema contract. This file connects the four layers a
+real form spans: **WHATWG Constraint Validation as the platform
+floor, validation timing as a state machine on the input, WCAG 3.3.x
+as the announcement and recovery contract, schema as the cross-stack
+truth.** A11y wiring lives next door in `accessibility-baseline.md`
+(label + describedby + invalid + `role="alert"` for inline errors);
+this file picks up where that ends.
+
+## The input state machine
+
+Every input passes through these states. The names trace back to RHF /
+Formik vocabulary on web; the *shape* applies regardless of stack.
+Drive error chrome off the state, not off raw `:invalid` or
+focus/blur booleans.
+
+| State | Meaning | UI |
+|---|---|---|
+| `pristine` | User has not interacted | No error chrome, no green check |
+| `dirty` | User has typed but not committed (still focused) | No error chrome yet |
+| `touched` | User has blurred at least once after editing | Field-level constraint runs |
+| `invalid-after-touched` | Constraint failed after blur | Show error, link via `aria-describedby` |
+| `invalid-after-submit` | Submit attempted, field still invalid | Same plus focus management to summary or first invalid field |
+| `recovering` | User editing an already-invalid field | Re-validate on `input`, not on next blur |
+| `submitting` | Action in flight | Disable submit, announce status via a polite live region |
+| `server-error` | Server returned an error for this field | Use server's message text; treat as `invalid-after-submit` |
+
+Decision rule that collapses validation-timing debates: errors appear
+on transition into `invalid-after-touched`, clear on transition out
+of any invalid state, and never appear from `pristine` or plain
+`dirty`. CSS `:user-invalid` matches the `invalid-after-touched` /
+`invalid-after-submit` states for free.
+
+## Validation timing
+
+Baymard's checkout-UX benchmark (2024-01-09 inline-validation article):
+**31% of sites have no inline validation, and most of the rest fire
+too early.** The participant quote that anchors the research: *"Why
+are you telling me my email address is wrong, I haven't had a chance
+to fill it all out yet?"* Premature firing is the loudest UX failure
+in this space.
+
+The four rules:
+
+1. **First blur after edit** runs the field-level constraint. Not on focus, not on first keystroke, not on every keystroke.
+2. **Once a field is invalid, switch to `input`-event re-validation** so the error clears the moment input becomes valid. Don't make the user blur again to dismiss it.
+3. **On submit**, run the schema parse. Move focus to the error summary at the top of the form (a heading-led container with `tabindex="-1"`, no `role="alert"` — see the wiring section), or to the first invalid field if no summary exists. Don't move focus on every keystroke.
+4. **Async checks** split into two paths. *Background preflight* (uniqueness while typing, address lookup) debounces 250-500 ms, announces via a polite live region, and never gates typing or keeps the submit button disabled indefinitely. *Authoritative server validation on submit* is different: the submit path must await the server's response and surface field errors from it, since the server is the truth. Don't conflate the two — the rule is "don't let a slow background check freeze the form," not "don't ever wait for the server."
+
+CSS gets you most of timing rule 1 for free: style off `:user-invalid`
+not `:invalid`. The `:user-invalid` selector is Baseline Newly
+available 2023 (Chrome 119, Firefox 88, Safari 16.5; Firefox shipped
+the prefixed `:-moz-ui-invalid` years earlier and unprefixed in v88)
+and matches only after the user has either submitted the form or
+blurred the field with bad input.
+
+## Constraint Validation API as the platform floor
+
+Native HTML constraints are not an alternative to JS validation; they
+are the substrate the rest of the layers run on. They survive JS
+failure, they integrate with autofill, and they are what
+`reportValidity()` and screen-reader native announcements key off.
+
+```html
+<input type="email" name="email" required>
+```
+
+Use these declaratively for every field that has them: `required`,
+`type` (email, url, number, tel), `pattern`, `min`/`max`,
+`minlength`/`maxlength`, `step`. Cross-field rules and dynamic
+constraints go through `setCustomValidity()` on both `input` and
+`change` events — autofill flows historically fired one without the
+other on some browsers, so listening on both is the cheap defense.
+
+Rules of the API:
+
+- **Empty string clears `setCustomValidity`.** Not `null`, not no-arg.
+- **`form.requestSubmit()` honors validation; `form.submit()` skips it.** Never call the second.
+- `disabled` controls are barred from validation and not submitted. The HTML spec says `readonly` is also barred, but `readonly` only has defined behavior on `<input>` and `<textarea>` — implementations diverge for `<select readonly>` and `<button readonly>` ([whatwg/html#11841](https://github.com/whatwg/html/issues/11841)). For non-input controls where the value must still submit, the safe pattern is `disabled` plus a same-named hidden `<input>` carrying the value, or rendering the non-editable text alongside a hidden `<input>`. `aria-readonly` alone is not enough — a `<select>` or custom widget tagged `aria-readonly="true"` is still interactable, so the visible control can drift while the hidden input ships a stale or different value. If you do use `aria-readonly`, you must also block the interaction or keep both values in sync.
+- `inputmode` is a virtual-keyboard hint, **not** validation. `<input type="text" inputmode="numeric" pattern="[0-9]*">` is the Baymard-recommended shape for ZIPs / OTPs / card numbers; `pattern="[0-9]*"` is the historical iOS-Safari trigger for the numeric keypad on top of `inputmode`. `type="number"` adds spinners, strips leading zeros, applies locale-decimal handling, and varies field width across browsers — wrong for any of these.
+
+## Error wiring beyond the baseline
+
+The default error pattern in `accessibility-baseline.md` (`<label>` +
+`aria-describedby` + `aria-invalid` + `role="alert"`) covers WCAG
+3.3.1 / 3.3.2. Three additions matter for real forms:
+
+**Adaptive error messages.** Baymard 2023: 98% of audited sites use
+generic catch-all errors ("Provide a valid phone number") rather than
+the specific subrule that fired ("Phone number is too short"). The
+back end already knows the subrule; surfacing it cuts re-submit
+attempts. Ship 4-7 distinct messages per high-traffic complex field
+(email, phone, card, postal code). The scale of the problem matches
+WebAIM Million 2026: missing form-input labels appear on **51% of
+the top 1M home pages** (input-level rate **33.1%** of all 6.9M
+inputs sampled) — labels and error messages are the categories
+trending sideways or worse year-over-year while overall a11y errors
+drop.
+
+**Error summary at the top, on submit only.** Long forms benefit from
+a summary list of in-page anchor links to invalid fields, focused on
+submit:
+
+```html
+<div id="form-errors" tabindex="-1">
+  <h2>2 problems</h2>
+  <ul>
+    <li><a href="#email">Email is required</a></li>
+    <li><a href="#dob">Date of birth must be in the past</a></li>
+  </ul>
+</div>
+```
+
+The container is heading-led with `tabindex="-1"` so JS can move
+focus to it on submit (render the summary into the DOM, *then*
+`.focus()` it; a `hidden` element can't take focus). It does **not**
+carry `role="alert"` because combining a moved-focus target with an
+alert role causes double-announcement: alert fires on insertion,
+focus fires the accessible name + role. Reserve `role="alert"` for
+inline per-field errors that appear without focus moving — that's
+the canonical baseline pattern in `accessibility-baseline.md`. WCAG
+technique G139 covers the summary; not required, high-value for long
+forms.
+
+**Preserve user input on error.** Baymard 2024: 34% of audited
+checkouts wipe the credit-card field when an unrelated error reloads
+the page. Direct cause of abandonment. Either field-level-validate
+non-sensitive fields first, or split the payment step. PCI-wise,
+persisting card values across an error reload is fine via tokenized
+hosted iframes; never store raw PAN in your own session.
+
+## Schema as the cross-stack contract
+
+Validation expressed once, consumed everywhere. The 2026 React shape
+— `useActionState` + Server Actions + Conform (which added Standard
+Schema support during the v1.x line) + a Zod 4 / Valibot / ArkType
+schema — is the most-cited concrete instance: one schema,
+server-authoritative, validator hot-swappable via the `~standard`
+interface. The same architecture works in TanStack Form, oRPC, Hono
+validator middleware, Nuxt UForm, and any other consumer that reads
+`~standard`.
+
+```ts
+const Signup = z.object({
+  email: z.email(),                  // Zod 4 top-level form
+  password: z.string().min(12),
+});
+// Same schema parses on the Server Action and on the Conform client.
+```
+
+Three rules that survive across stacks:
+
+- **Server is the truth, client is the optimization.** Same schema runs in both. Returning `{ errors }` from the action (not throwing) is what feeds back into `useActionState`'s state slot — throwing routes to the Error Boundary and loses the form data.
+- **Standard Schema is the contract, not Zod.** A form library that ships per-validator resolver shims (`zodResolver`, `valibotResolver`, etc.) is yesterday's stack. Accept any `~standard`-compliant validator.
+- **`novalidate` on `<form>` does not mean "skip validation".** It means "let the form library repaint errors instead of the browser's bubble." But the trade-off is real: a literal server-rendered `<form novalidate>` disables the browser's submit-blocking and native validation UI **even when JS is unavailable**, which loses the no-JS constraint-validation floor. Pick one of two patterns. **A:** render `<form>` without `novalidate` server-side and have the form library set `form.noValidate = true` after hydration — the no-JS user keeps the browser's native validation, the JS user gets the library's chrome. **B:** ship `novalidate` from the start only when the submit path reaches server validation without JS (Server Action, classic POST handler) so the no-JS user is still protected by the server. Either way, keep `required` / `pattern` / `type` attributes — they survive JS failure and integrate with autofill. (HTML attribute is lowercase `novalidate`; the IDL property on the form element is `noValidate`.)
+
+## WCAG 3.3.x beyond Error Identification
+
+`accessibility-baseline.md` covers 3.3.1 (Error ID), 3.3.2 (Labels),
+and 3.3.7 (Redundant Entry). The rest of 3.3 binds harder on
+transactional forms:
+
+- **3.3.3 Error Suggestion (AA):** when the fix is determinable, suggest it in text. Adaptive errors satisfy this. "Date must be MM/DD/YYYY. You entered 5-3-26. Did you mean 05/03/2026?"
+- **3.3.4 Error Prevention — Legal, Financial, Data (AA):** for any submission with legal / financial / data-modifying consequence, provide one of: reversibility, server-side check + correction step, or a confirm-summary screen before commit.
+- **3.3.8 Accessible Authentication (AA, WCAG 2.2):** auth steps must not require a cognitive function test (remember a password, transcribe a code, recognize images) without an alternative. CAPTCHAs are the canonical thing this SC restricts; only object-recognition or personal-content variants escape via the narrow exceptions, and not all CAPTCHAs do. Practical floor: never block paste on password / verification-code fields, support password managers, accept verification-code paste from a clipboard.
+- **3.3.9 Accessible Authentication, No Exception (AAA):** removes even the object-recognition / personal-content exceptions. Aspirational; flag if a project commits to it.
+
+## Native mobile parity
+
+Web validation primitives don't auto-translate. Each platform has its
+own validity machinery and its own AT path. Skills that emit web-only
+artifacts can skim this section; it's the entry point for skills
+that ship to mobile (mobile-onboarding, mobile-app, etc.).
+
+| Platform | Validity primitive | Error announcement |
+|---|---|---|
+| iOS UIKit | Hand-rolled state on the view controller; `UITextField` doesn't carry a built-in invalid flag | `UIAccessibility.post(notification: .announcement, argument: "Email is required")` |
+| iOS SwiftUI | `TextField` + `@State`-driven validation; no built-in `Form`-level validity API as of iOS 18 | `AccessibilityNotification.Announcement("…").post()` (iOS 17+) |
+| Android Compose | `OutlinedTextField(isError = true, supportingText = { Text("…") })` — `isError` wires the AT error semantic for you | `Modifier.semantics { liveRegion = LiveRegionMode.Polite }` on the supporting-text node, or `LocalView.current.announceForAccessibility(message)` |
+| Flutter | `TextFormField(validator: (v) => …)` inside a `Form`, `formKey.currentState!.validate()` | `SemanticsService.announce(message, Directionality.of(context))` — never hardcode `TextDirection.ltr`; pull ambient direction so Arabic / Hebrew / Persian flows announce correctly |
+| React Native | Hand-rolled per field; no platform validity flag | `accessibilityLiveRegion="polite"` on the error node (Android) + `AccessibilityInfo.announceForAccessibility(...)` (iOS) |
+
+Two parity rules that catch most AI-generated mobile forms:
+
+- **Use the platform's native validation flag — and pair it with the platform's error-message semantic where one exists.** On Compose, `isError = true` is the right boolean state for the field visuals and AT error-state cue, but it does *not* carry the localized error message. Pair it with `Modifier.semantics { error(message) }` so accessibility services get the actual text — the same string you render in `supportingText`. The trap is duplication: a hand-rolled `Modifier.semantics { error("Email is required") }` next to a different supporting-text string desyncs. Source `error()` from the same state field as `supportingText` so they stay in sync.
+- **Don't mirror web ARIA into mobile semantics.** `aria-describedby` on a SwiftUI `TextField` is a no-op. Use the platform announcement primitive (`AccessibilityNotification.Announcement` on SwiftUI, `UIAccessibility.post` on UIKit, `announceForAccessibility` on Android, `SemanticsService.announce` on Flutter) for state-change events that need to reach the screen reader.
+
+## Common mistakes (lint these)
+
+- Styling off `input:invalid` instead of `input:user-invalid`. Red borders on page load is the loudest "this validation was added without testing" signal.
+- Validating on every keystroke. Hostile; fires before the user has finished typing.
+- Generic catch-all error messages ("Invalid input") when the back end already knows which subrule fired. Baymard 2023 found 98% of audited sites do this — the most-cited preventable validation failure in their corpus.
+- Throwing from a Server Action on validation failure. Routes to the Error Boundary and loses the form data. Return `{ errors }` instead.
+- `role="alert"` on the error-summary container that focus moves to. Double-announces. Reserve `role="alert"` for inline per-field errors that appear without focus moving.
+- `aria-busy="true"` on the submit button while submitting. `aria-busy` is for stale containers; for buttons use `disabled` plus a polite live-region status message.
+- Email-confirm fields ("retype your email"). 3.3.7 redundant entry — exceptions are essential / security / no-longer-valid, not "we want to catch typos." Allow paste and validate the single field instead.
+- Per-validator resolver shims (`zodResolver`, `valibotResolver`) on a 2026 stack. Accept Standard Schema's `~standard` interface and the validator becomes swappable.
+- Wiping the credit-card field when an unrelated field errors. Baymard 2024: 34% of audited e-commerce sites; direct abandonment cause.
+- `setCustomValidity(null)` to clear an error. Pass empty string; `null` does not clear.
+- Mirroring web ARIA onto SwiftUI / Compose / Flutter. Each platform has its own validity API; `aria-*` attributes don't reach the mobile AT path.

package/skills/od-craft/references/laws-of-ux.md

@@ -0,0 +1,298 @@
+<!-- Vendored from nexu-io/open-design@78d5637cb49d (craft/laws-of-ux.md), Apache-2.0, Copyright 2026 Open Design contributors. Modified by Pugi: this header line added; the text below is otherwise verbatim. Paths it names (apps/daemon/src/lint-artifact.ts, pnpm lint:craft, od.craft.requires) are upstream's, not Pugi's: the Pugi port of the linter is packages/opencode/src/session/design-lint.ts. See NOTICE.md in the skill root. -->
+
+# 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.