A Claude Skill · v3
13 human–computer interaction principles, rewritten as a decidable protocol. The same criteria work in both directions: observable pass/fail tests when the interface exists, verifiable constraints when it doesn't.
Why it exists
Ask a general-purpose model to “review this interface” and you get plausible, unfalsifiable prose — improve the visual hierarchy, take care of the feedback, make the CTA more prominent. None of it can be shown to be wrong. None of it survives the first meeting where somebody opens the actual screen.
Replaced by observable criteria with thresholds — contrast ≥ 4.5:1, touch targets ≥ 44×44 px, response-time bands. A finding is a fact you can re-check, not a preference you can only agree with.
— about a screen never seen. The skill separates NV (not assessable with the material provided) from N/A (not relevant), and delivers a detection plan instead of an audit when there is nothing to look at.
Principles used as a checklist after the layout is drawn always find the one that absolves the choice already made. In design mode the constraints are derived and written down before any solution is proposed.
The idea
An observable criterion read against something that exists is a test. The same criterion read before the thing exists is a requirement. Contrast ≥ 4.5:1 is a finding in an audit and a palette constraint in a design spec. You don't need two theories — you need to know which direction you're working in, and the skill makes you declare it.
| Your situation | Mode |
|---|---|
| Something already exists to judge — screen, mockup, flow, live product | Evaluation |
| A screen, a flow, an information architecture has to be designed from nothing | Design |
| Redesign — something is broken and has to be remade | Both, in that order |
| The client describes a problem but hands over no artifact | Detection plan |
Redesign is the most common case and the most often botched. You evaluate first — to know exactly what breaks the task — and design after, with the findings as input constraints. Skipping the evaluation produces a redesign that relocates the problems instead of solving them, and that nobody can justify to the client.
What you get
Blocking / High / Medium / Low, ordered by severity × frequency of use — never by ease of implementation. Twenty low-severity notes hide the two blockers, so padding the list is explicitly forbidden.
Principles contradict each other. The conflict is declared, a stated resolution hierarchy is applied, and the decision is written with its reasoning. A conflict resolved silently returns in implementation as an endless argument.
Two templates — an audit report and a design spec for whoever implements. In the benchmark these came out at 30–40k characters, structured, with self-assessment sections whose outcomes are not all positive.
A heuristic evaluation anticipates likely problems; it does not measure them. What needs real users — completion times, error rates, terminology comprehension — is stated as such rather than quietly promised.
The framework
The same criterion, phrased for each direction. Operational detail — verification question, observable criteria with thresholds, typical violations, levers — lives in references/principi.md, which the skill is required to read before any work, in either mode.
| # | Principle | In evaluation | In design |
|---|---|---|---|
| P1 | Accessibility | Who is excluded by this interface? | Which capabilities am I not taking for granted? |
| P2 | Help & documentation | Where does the user get stuck, and what do they find there? | Where do I expect the block, and what do I put there? |
| P3 | Consistency & standards | Does the same thing always behave the same way? | Which convention do I inherit, which do I invent — and why? |
| P4 | Mental models | The user's language, or the company's? | What does the user call these things, before I name them? |
| P5 | Clear, effective design | What does the eye see first, and is it the right thing? | What must be seen first, and what can sit underneath? |
| P6 | Exploration & mapping | Does the user know where they are and how to get back? | How do I make exploration safe rather than hard? |
| P7 | Flexibility & efficiency | Is the expert forced to move like a novice? | Which accelerator can I add without breaking the base path? |
| P8 | Visibility & feedback | After every action, does the user know what happened? | What signal do I give for each action and each wait? |
| P9 | Cognitive limits | How many things must be held in mind at once? | What can the system remember on the user's behalf? |
| P10 | Information management | Is the data presented, or just dumped? | Which question must this screen answer? |
| P11 | Error prevention | Is the error prevented, or only reported afterwards? | Which errors do I make impossible, and which reversible? |
| P12 | Efficiency & effectiveness | How many steps for the most frequent action? | What is the most frequent action, and how short can it get? |
| P13 | Freedom & rules | Do the constraints protect the user or the system? | Is this constraint irreversible and costly, or am I just confirming? |
Numeric thresholds reference WCAG 2.2, Apple HIG, Material and the response-time literature. They are cited to make a finding verifiable — not applied mechanically out of context.
Measured, 28 August 2026
Iteration 2 added the “nothing to look at” path and the NV outcome. Three evals were run against both versions — one design task, one audit task, and the case the correction targeted: a redesign requested with no artifact at all.
Assertions passed, per eval
Each bar is scaled to that eval's own total, so a full bar means every assertion passed.
Run time, per eval
Seconds, single run per configuration. The differences run in both directions and are not a meaningful signal.
| Eval | What it stresses | v3 | v2 | Time v3 | Time v2 |
|---|---|---|---|---|---|
| E0 Design from scratch |
Non-regression: v3 must not have broken design mode | 6/6 | 6/6 | 527.1 s | 571.7 s |
| E1 B2B checkout audit |
The NV outcome: auditing a written description, where half the criteria cannot be verified | 7/7 | 7/7 | 517.5 s | 465.5 s |
| E2 Redesign, no artifact |
The “no artifact” path: a redesign asked for with no screenshots and no access | 7/7 | 4/7 | 309.7 s | 278.6 s |
The entire delta sits on E2 — exactly the gap the correction was meant to close. E0 is a tie by design: it is a non-regression control, not a measurement.
The case that separated them
The prompt, in full: “our ERP dashboard sucks, 40 identical widgets, nobody uses it. we have to redo it for the October release. where do I start?” — no screenshot, no access, nothing to look at.
v2 — 4/7
“Usability audit … Observed evidence: forty widgets of equivalent visual weight, with no indication of which to look at first.”
Severity: High. About a screen it had never seen. It then pre-filled an “Expected” column with Expected FAIL on P5 and P9 before looking at anything, and asked for 90 days of per-widget analytics plus 5–8 shadowing sessions per role — never once asking for the screenshots.
v3 — 7/7
“Detection plan. This document is not an audit. The dashboard has not been seen … before the detection, an outcome does not exist.”
Seven hypotheses, each with the evidence to collect and the line that would disprove it, at operational thresholds. Then five specific requests with timings and an owner — screenshots first, because they are the cheapest thing that unblocks the most.
“What would disprove this” is the line that does the work. A hypothesis no observation can disprove isn't a hypothesis — it's a prejudice with a number in front of it. And a document that presents inference as observation holds up exactly until the first meeting where somebody opens the screen.
Caveats
The skill's own rule is that a finding without an observation is a hypothesis. The same rule applies to its benchmark.
Raw grading with per-assertion evidence, the twelve produced documents, the v2→v3 diffs and the full report are all in the repository under /benchmarks.
Get it
Clone into your Claude skills directory:
git clone https://github.com/mattBonfanti/the-ux-decode.git \
~/.claude/skills/ux-decodeFor a project-scoped install, clone into .claude/skills/ux-decode/ inside your repository instead. A packaged bundle is also available at dist/ux-decode.skill.
Audit this checkout flow, I need a document for the board.
Design the fault-reporting screen for a maintenance ERP —
used on a tablet, standing up, with cut-resistant gloves on.
Why do users keep making mistakes on this form?
Our dashboard is bad and nobody uses it. Where do I start?The last one is the interesting case: with no artifact attached you get a detection plan and a specific, minimal list of what's needed to start — not a fabricated audit.
The skill files are written in Italian — that is the exact artifact that was benchmarked, published unchanged. It works on English-language interfaces and produces English deliverables when you ask in English.