sprezzature-ux-laws
Laws of user experience (UX)
Apply the canonical Laws of UX (Jon YABLONSKI) to vanilla-JavaScript (JS) + Tailwind: both when making new user interface (UI) and when auditing existing HyperText Markup Language (HTML). Reference covers 30 laws with trigger / action / Tailwind hook.
Makes
- Design a screen with Hick / Fitts / Miller / Peak-End in mind
- Each law paired with a concrete Tailwind hook
Audits
- Static auditor flags the mechanically-detectable subset: Hick, Miller, Fitts, Jakob, Tesler, Aesthetic-Usability, Selective Attention, Choice Overload (eight checks)
- Severity + JavaScript Object Notation (JSON) output for pre-commit / continuous integration (CI)
Say one of these
The skill triggers itself on phrasing like this, no command to memorize.
audit for Laws of UX
design this screen using Hick / Fitts
is my nav too Hick-heavy
too many choices
cognitive load
Doherty threshold
reduce clutter
Frequently asked questions
How do I install sprezzature-ux-laws?
Run pip install sprezzature-ux-laws on Python 3.10 or later: one install gives the library, both commands, the HTTP API and the MCP server, with no extras to choose. sprezzature-ux-laws is free and open source under the BSD 3-Clause licence.
Which Laws of UX does sprezzature-ux-laws check?
sprezzature-ux-laws checks eight of the thirty laws on lawsofux.com, the ones a scan of the HTML source can decide: hick, choice-overload, miller, jakob, fitts, aesthetic-usability, selective-attention and tesler. Two of them, hick and jakob, are errors and the other six are warnings; --only and --ignore pick among them by slug.
What does sprezzature-ux-laws --fix change?
sprezzature-ux-laws repairs four laws with --fix: it adds min-h-11 for Fitts, a focus-visible:ring-2 focus ring for aesthetic-usability, splits long codes into groups of four with non-breaking spaces for Miller, and rewrites a clickable div or span into a real button for Jakob. The other four need a design decision, not a text edit. --fix --dry-run previews the edits, and a second run on a repaired file applies none.
How does sprezzature-ux-laws count choices on a responsive menu?
sprezzature-ux-laws counts what one screen shows, not every link in the file: it resolves each control's visibility from its Tailwind display classes and reports the worse of the phone count and the desktop count, so a desktop row and a hamburger menu are not added together. A details, a dialog, a menu or a group such as a tablist counts as one choice, and a nav with more than seven choices on one screen is a Hick's Law error.
Does sprezzature-ux-laws send my pages to a cloud service?
No: sprezzature-ux-laws reads the raw HTML with Python's standard-library parser, with no browser, no network and no AI model, so it needs nothing besides pip. That keeps it deterministic and fast enough for a pre-commit hook.
How is sprezzature-ux-laws different from Lighthouse or a design review?
sprezzature-ux-laws reads source only, so it catches the mechanical, source-decidable mistakes without a browser, but it cannot render a page or watch a person use it. Lighthouse with field data measures response time, the Doherty threshold this tool explicitly leaves out, and a design review or a session with real users is still what tells you whether a screen makes sense; this tool exists so the mechanical faults never reach that review.
Can I run sprezzature-ux-laws in CI?
Yes: sprezzature-ux-laws exits 1 when sprezzature-ux-laws site/ finds at least one error, or any finding at all with --strict, and exits 2 on a usage error. --json prints one object per finding, with the law, severity, path, line, message and snippet, for a CI job to read.
Can I use sprezzature-ux-laws without Claude Code?
Yes: sprezzature-ux-laws is a Python library (audit_html, audit_file, fix_file), a command line, an HTTP API with a Docker image that runs sprezzature-ux-laws-mcp, and an MCP server whose tools are health, list_laws and audit_interface. The agent skill that tells Claude Code or OpenCode when to apply the laws comes with pip install sprezzature, then sprezzature-skills --install.