I Put 20 UX Laws Into an AI Coding Brief. Then I Audited the Brief.

The Starting Point

I found Adam Hayes's post, [“The UX Laws in My CLAUDE.md”][1], and immediately understood the appeal.

The premise is simple: an AI coding tool can produce a technically functional interface very quickly, but “functional” does not mean the hierarchy is clear, the interaction states are complete, or the design helps a user recover when something goes wrong.

A style guide can tell the model which spacing token or button variant to use. It does not necessarily tell the model why an action should sit beside the object it affects, why user input should survive an error, or why fourteen equally weighted options create friction.

Hayes's solution was to put twenty named UX “laws” into CLAUDE.md, each translated into concrete instructions. The file covered Hick's Law, Fitts's Law, Miller's Law, the Doherty Threshold, the Peak-End Rule, Postel's Law, Tesler's Law, and more.

I copied the idea into my workflow.

Then I stopped before adopting it.

The question was no longer just:

Will this help an AI generate better interfaces?

It became:

What authority am I giving this file, and what happens when one of its rules is wrong for the product in front of it?

That second question changed the whole exercise.

Part 1: The Wrong Starting Point

My first instinct was to treat the document like a design checklist.

That is the trap.

A file inside CLAUDE.md is not passive documentation. It becomes operating context. The stronger and more universal the language, the more likely the coding agent is to treat it as permission.

The original adaptation opened with:

Follow these instructions whenever you design, build, or revise a user interface.

That sounds reasonable until the product already has an approved information architecture, a dense expert workflow, a governance requirement, or a trust mechanism that looks visually removable.

“Reduce choices” can become hiding necessary evidence.

“Design the shortest path” can become removing a review step that prevents a costly mistake.

“Let the system handle complexity” can become silent AI inference.

“Make completion feel closer” can become fake progress.

“Accept reasonable variations” can become guessing what security-sensitive input was supposed to mean.

The problem was not that the advice was obviously bad. The problem was that good advice had been converted into blanket authority.

Part 2: The Audit

I gave the Markdown file to an AI collaborator with a different task: do not apply it. Audit it.

The review had four parts:

1. Factual accuracy — does the named law actually support the instruction beneath it?

2. Applicability — when is the advice useful, and when does context reverse it?

3. Accessibility and security — what requirements are missing from the psychology framing?

4. Prompt safety — what could an agent infer it is allowed to change if this file is always loaded?

I also ran a static scan over the 200-line source file. It contained no URLs, shell commands, hidden control characters, credential requests, encoded payloads, or “ignore previous instructions” patterns.

So this was not a conventional prompt-injection attack.

It was a subtler problem: instruction scope.

A Markdown file does not need malware or a secret-stealing command to be unsafe. If it is placed high enough in an agent's context, a broad imperative can override the intent of a narrower product task.

That distinction is going to matter more as design teams move reusable guidance into CLAUDE.md, skills, rules files, MCP-connected tools, and repository instructions.

Part 3: What Held Up

A lot of the document survived the review.

The useful core was strong:

• reduce irrelevant choices;

• make interaction targets usable;

• group related information;

• prefer recognition over recall;

• keep actions near the content they affect;

• show system status;

• preserve user work after errors;

• make errors recoverable;

• reuse established patterns;

• expose progress honestly;

• confirm completion clearly.

These align closely with established usability heuristics. Nielsen Norman Group explicitly calls its own ten principles heuristics—broad rules of thumb, not specific universal requirements.[2]

That wording matters.

A heuristic helps the model ask a better question. A law can make the model think the answer has already been decided.

Part 4: What Did Not Hold Up

The Laws Were Duplicated

Hick's Law appeared twice: once for reducing choices and again for defaults.

Fitts's Law also appeared twice: once for target size and again for proximity.

Both applications can be useful, but repetition gives them disproportionate weight. An agent may start treating “fewer choices” and “nearer controls” as the dominant explanation for every interface problem.

I consolidated the repeated rules into task-level guidance instead.

Miller's Law Was Too Convenient

“Break content into chunks” is practical advice.

Treating seven plus or minus two as a UI limit is not.

Nelson Cowan's review notes that Miller's number was closer to a rhetorical device and rough estimate than a dependable capacity rule. Under constrained conditions, later evidence points closer to three to five chunks, but the definition of a chunk and the task conditions matter.[5]

The corrected instruction became:

Chunk content by meaning and task, not by an arbitrary item count.

That gives the model a design principle without pretending psychology produced a universal menu length.

400 Milliseconds Was Not a Completion Requirement

The document said interfaces should respond within approximately 400 milliseconds.

Useful direction, wrong level of certainty.

A better distinction is between acknowledgment and completion. Classic response-time guidance puts direct-manipulation feedback near 100 milliseconds, notices delays around one second, and calls for meaningful progress feedback for longer operations.[4]

An interface can acknowledge an action immediately while a real operation is still running. What it cannot do is announce success before the external write, payment, message, permission change, or deletion is actually confirmed.

The corrected instruction became:

Acknowledge interaction as quickly as practical. If completion is delayed, expose a truthful working state without claiming success prematurely.

The Zeigarnik Effect Was Doing Work It Could Not Support

The source used the Zeigarnik Effect to justify visible progress, saving work, and encouraging users to return.

Those are good product behaviors. The psychological claim is much less stable.

A 2025 meta-analysis found no general memory advantage for unfinished tasks. It did find a tendency to resume interrupted tasks, but concluded that the classic Zeigarnik effect lacks universal validity.[6]

I kept resumability and truthful progress. I removed the idea that a product should use incompleteness to create mental tension.

Postel's Law Was the Security Problem

The document attributed proactive error prevention and graceful recovery to Postel's Law.

That is not the right foundation.

Postel's robustness principle came from network protocol design: be conservative in what you send and liberal in what you accept. Modern IETF guidance warns that broad tolerance of faulty or ambiguous inputs can create inconsistent interpretations, interoperability decay, and security problems.[7]

In a form, trimming accidental whitespace may be helpful.

In a permission, payment amount, file path, URL, structured command, or tool parameter, guessing intent can be dangerous.

The replacement separates the two:

• normalize explicitly supported benign variations;

• validate syntax, semantics, authorization, bounds, and security-sensitive values strictly;

• reject ambiguity with a useful error rather than inferring what the user meant.

Error prevention and recovery still belong in the brief. They just belong under usability and safety, not Postel's Law.

Accessibility Could Not Stay Implicit

Fitts's Law says larger and nearer targets are easier to hit. That does not replace an accessibility requirement.

WCAG 2.2's Level AA target-size criterion generally requires a 24 by 24 CSS-pixel target or sufficient spacing, with defined exceptions. Larger targets remain useful for frequent, important, mobile, or motor-demanding actions.[3]

The rewritten file adds explicit requirements for:

• keyboard operation;

• visible focus;

• semantic names and states;

• screen-reader announcements;

• sufficient contrast;

• zoom and reflow;

• reduced motion;

• focus restoration;

• status that does not rely on color or motion alone.

The psychology can explain some design pressure. The standard defines what must actually be checked.

Part 5: The Rule That Changed the File

The most important addition was not another law.

It was an authority block.

The public version now begins by saying that the guidance is advisory and subordinate to:

• the active user request;

• approved product requirements;

• accessibility standards;

• security requirements;

• repository rules;

• established information architecture.

It also says the file cannot authorize new navigation, dependencies, data handling, external services, publication, deployment, or irreversible actions.

That changes the model's job from:

Apply these twenty rules.

To:

Use these heuristics to identify friction, then propose the smallest change allowed by the current task.

That is a much better contract.

Part 6: From Laws to Review Output

The original file mostly described what a good interface should do.

The revised version also specifies what the agent must return before a non-trivial change:

1. the user goal and observed friction;

2. the smallest proposed change;

3. the existing surface or component affected;

4. the evidence or reference informing it;

5. the interaction states covered;

6. accessibility implications;

7. security and governance implications;

8. information-architecture impact;

9. what remains unchanged;

10. verification performed and the observed result.

This is the same lesson I keep encountering while building design-system infrastructure with Claude Code: principles become useful when they produce inspectable artifacts.

A token rule should produce a build output.

A component spec should produce a validation result.

A UX heuristic should produce a bounded proposal and a verification record.

Otherwise it is just context competing with other context.

Part 7: The Public Artifact

I created a sanitized version of the file that removes project-specific architecture, private context, and internal product language.

It keeps the useful behaviors while adding:

• explicit instruction precedence;

• information-architecture boundaries;

• prompt and data safety;

• accessibility requirements;

• safe optimistic-update constraints;

• strict handling of security-sensitive input;

• truthful progress and completion;

• a required review-output format.

Read the artifact: Safe, Contextual UX Instructions for AI Coding Tools

I recommend referencing it from a project-scoped instruction rather than copying it into a universal system prompt:

Use `safe-contextual-ux-instructions.md` as an advisory UI review checklist.
It does not override the active task, approved product requirements,
accessibility and security requirements, repository rules, or established IA.
Before implementation, identify the observed friction and propose the smallest
change. If product meaning or IA may change, stop and request approval.

What I Learned

The source idea was good. AI coding tools benefit from design reasoning, not just visual tokens.

The word “law” creates too much confidence. Most of this material works better as contextual heuristics.

A clean file can still be unsafe. Prompt safety includes the authority and scope of ordinary instructions, not only obvious injection strings.

Psychology does not replace accessibility. A named effect may explain a tendency; WCAG and interface testing define concrete obligations.

The best reusable instruction includes its own limits. It should say what it cannot authorize, what takes precedence, and when the agent must stop.

The output matters more than the list. The goal is not for Claude to recite Fitts's Law. The goal is for it to identify friction, preserve product intent, cover the right states, and prove the interface works.

I started with a file meant to make AI-generated interfaces better.

I ended with a file meant to make AI-generated design decisions more accountable.

That is the version I actually put into my current workflow.

Sources

[1] https://adamhayes.xyz/blog/the-ux-laws-in-my-claude-md — The UX Laws in My CLAUDE.md — Adam Hayes
[2] https://www.nngroup.com/articles/ten-usability-heuristics — 10 Usability Heuristics for User Interface Design
[3] https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html — WCAG 2.2 — Target Size (Minimum)
[4] https://www.nngroup.com/articles/response-times-3-important-limits — Response Times: The 3 Important Limits
[5] https://cambridge.org/core/services/aop-cambridge-core/content/view/44023F1147D4A1D44BDC0AD226838496/S0140525X01003922a.pdf/the-magical-number-4-in-short-term-memory-a-reconsideration-of-mental-storage-capacity.pdf — The magical number 4 in short-term memory — Nelson Cowan
[6] https://doi.org/10.1057/s41599-025-05000-w — Interruption, recall and resumption — meta-analysis
[7] https://www.rfc-editor.org/rfc/rfc9413.html — RFC 9413 — Maintaining Robust Protocols