The UX Laws in My CLAUDE.md
Every AI coding tool will build you a settings page in about ninety seconds.
It’ll have a form, a save button, maybe a sidebar. It will look fine. And it will quietly violate half a dozen things every product designer learned the hard way. The primary action won’t stand out. The save button will be nowhere near the last field. The error state will wipe your inputs. The whole thing will offer fourteen options when the user needed one.
That’s not the model being dumb. It’s the model having no brief.
So I wrote one. It lives in my CLAUDE.md and it runs every time Claude Code touches a layout, a form, an onboarding flow, or a dashboard. The full thing is at the bottom of this post. Copy it.
Why laws and not a style guide
My first attempt was a style guide. Spacing scale, button variants, type ramp. Claude followed it and the interfaces still felt wrong, because a style guide tells you what things look like, not why they’re there.
What worked was going one level up: the psychology. Hick’s Law, Fitts’s Law, the Peak-End Rule, Tesler’s Law. Twenty of them, each written as a one-line principle plus four concrete instructions.
The difference is that laws generalise. “Buttons are 44px tall” covers one case. “Large, nearby targets are faster to hit” covers the button, the checkbox, the drag handle, and the tap target on the table row you forgot about. A model can reason from a principle. It can only copy from a spec.
The shape of each rule
Every section follows the same pattern:
- The law, named, so the model has a hook to reason from.
- One sentence on what it actually says.
- Four imperative bullets. Do this. Don’t do that.
“Recommend an option when users may struggle to choose.” “Keep form submission near the final input.” “Preserve the user’s work after an error.” None of it is clever. All of it gets skipped when nobody says it out loud.
The part that matters most
The last block is the one I’d keep if I had to cut everything else. Eight implementation steps: identify the primary goal, design the shortest clear path to it, make the next action obvious, remove distractions, give immediate feedback, prevent errors, preserve work, confirm completion.
And one line for conflicts. When the laws disagree, prioritise clarity, accessibility, user control, and task completion. Don’t apply them mechanically.
That line is doing a lot of work. Without it, the model treats twenty rules as a checklist and ships a form that technically satisfies all of them and still feels like a tax return. With it, the model has a tiebreaker. A tiebreaker is most of what judgment is.
What changed
Fewer rounds of “make the button more obvious.” Fewer error states that lose your data. Fewer settings pages with three equally weighted CTAs. Not zero. But the baseline moved from “technically works” to “I’d ship this after one pass,” which is the whole point of a good brief.
Here’s the file.
# UX Design Instructions
Follow these instructions whenever you design, build, or revise a user interface. Apply them across layouts, navigation, onboarding, forms, settings, dashboards, and interactive flows.
Your goal is to minimize confusion, reduce effort, prevent mistakes, and help users complete their intended task as quickly as possible.
## 1. Reduce Choices per Screen: Hick's Law
The time required to make a decision increases with the number and complexity of available choices.
* Give each screen one clear purpose.
* Remove irrelevant or low-priority options.
* Break complicated decisions into smaller steps.
* Recommend an option when users may struggle to choose.
## 2. Make Targets Large: Fitts's Law
Large, nearby targets are faster and easier to interact with.
* Make buttons and controls easy to click or tap.
* Give interactive elements sufficient spacing.
* Avoid tiny icons as the only interaction target.
* Increase the clickable area around important controls.
## 3. Follow Familiar Patterns: Jakob's Law
Users expect your product to work like products they already understand.
* Use established interface conventions.
* Place navigation, search, settings, and account controls where users expect them.
* Use familiar icons and interaction patterns.
* Do not invent a new pattern unless it provides a meaningful advantage.
## 4. Group Related Information: Law of Proximity
Elements positioned near one another are perceived as related.
* Place related labels, controls, and information together.
* Use spacing to communicate relationships.
* Separate unrelated groups with additional space.
* Do not rely on borders when spacing can establish the hierarchy.
## 5. Break Content Into Chunks: Miller's Law
Working memory can only process a limited amount of information at once.
* Divide long content into small, meaningful groups.
* Break complex forms and tasks into manageable steps.
* Use headings, sections, and concise labels.
* Avoid asking users to remember information between screens.
## 6. Respond Within 400 Milliseconds: Doherty Threshold
Interfaces feel more productive when feedback appears within approximately 400 milliseconds.
* Acknowledge every user action immediately.
* Show loading, processing, or success states when results are not instant.
* Use optimistic updates when they are safe.
* Never leave users wondering whether their action registered.
## 7. Highlight the Primary Action: Von Restorff Effect
An element that visually differs from surrounding elements receives more attention.
* Give the primary action the strongest visual emphasis.
* Use one dominant call to action per section.
* Keep secondary actions visually quieter.
* Avoid making every button compete for attention.
## 8. Place Key Actions Nearby: Fitts's Law
Interaction becomes faster when important targets are close to the user's current focus.
* Place actions beside the content they affect.
* Keep form submission near the final input.
* Position frequent actions within easy reach.
* Avoid forcing unnecessary cursor or eye movement.
## 9. Put Essentials First: Serial Position Effect
People remember the first and last items in a sequence most clearly.
* Put the most important information first.
* Place the final action or takeaway at the end.
* Keep lower-priority information in the middle.
* Order navigation and lists according to user importance.
## 10. End Flows Memorably: Peak-End Rule
Users judge an experience largely by its most intense moment and how it ends.
* Create a clear and satisfying completion state.
* Confirm what the user accomplished.
* Explain what happens next.
* Avoid ending flows on an empty or ambiguous screen.
## 11. Show Visible Progress: Zeigarnik Effect
Incomplete tasks remain mentally active and encourage users to return.
* Clearly show completed and unfinished steps.
* Save progress whenever possible.
* Make it easy to resume interrupted tasks.
* Use checklists or completion states for multi-step work.
## 12. Simplify Complex Interfaces: Law of Prägnanz
People interpret complex or ambiguous designs in the simplest form possible.
* Prefer simple structures and recognizable shapes.
* Remove unnecessary decoration and visual noise.
* Create an obvious visual hierarchy.
* Make the interface understandable at a glance.
## 13. Use Sensible Defaults: Hick's Law
Helpful defaults reduce the number of decisions users must make.
* Preselect the safest and most common option.
* Use existing context to reduce unnecessary input.
* Never use defaults that create unexpected commitments.
* Make every default easy to change.
## 14. Prevent Errors Proactively: Postel's Law
Interfaces should accept reasonable variations in user input while producing clear, predictable results.
* Accept common input formats and variations.
* Explain requirements before submission.
* Disable impossible or unavailable actions.
* Warn users before risky or destructive actions.
## 15. Make Errors Recoverable: Postel's Law
The interface should handle user mistakes gracefully without creating unnecessary failure.
* Preserve the user's work after an error.
* Explain what went wrong in plain language.
* Tell the user exactly how to fix it.
* Provide undo, retry, restore, or cancel options where appropriate.
## 16. Maintain Pattern Consistency: Law of Similarity
Elements that look similar are perceived as having related purposes.
* Give similar components the same appearance and behavior.
* Use consistent colors, labels, icons, spacing, and interaction states.
* Do not use the same visual treatment for different actions.
* Reuse established components before creating new ones.
## 17. Connect Related Elements Visually: Law of Uniform Connectedness
Visually connected elements are perceived as more closely related.
* Use containers, lines, backgrounds, or shared states to show relationships.
* Visually connect controls to the content they affect.
* Keep unrelated elements visually separate.
* Use connection deliberately, not decoratively.
## 18. Reduce Task Completion Time: Parkinson's Law
Tasks tend to expand to consume the time made available for them.
* Minimize the number of steps required.
* Remove unnecessary confirmations and screens.
* Prefill information the user has already provided.
* Offer shortcuts for frequent or repeat actions.
## 19. Reveal Complexity Gradually: Tesler's Law
Every system contains some complexity that cannot be removed, only managed or transferred.
* Show essential controls first.
* Reveal advanced options only when relevant.
* Let the system handle complexity whenever possible.
* Do not force users to understand internal technical details.
## 20. Make Completion Feel Closer: Goal-Gradient Effect
Motivation increases as users perceive themselves getting closer to a goal.
* Show progress throughout multi-step flows.
* Divide long tasks into visible milestones.
* Emphasize progress already made.
* Make the remaining work feel specific and achievable.
## Implementation Requirements
When creating or revising an interface:
1. Identify the user's primary goal.
2. Design the shortest clear path to that goal.
3. Make the next action visually obvious.
4. Remove anything that distracts from task completion.
5. Provide immediate feedback after every interaction.
6. Prevent errors before they occur.
7. Preserve user work when something goes wrong.
8. Confirm clearly when the goal has been completed.
When laws appear to conflict, prioritize clarity, accessibility, user control, and successful task completion. Do not apply these laws mechanically. Use them to make deliberate decisions based on the user's context and goal.The model is only as opinionated as the brief you gave it. Give it one.