What Cognitive Effort Actually Measures

Your performance tools measure the machine. Your accessibility tools measure the markup. Neither one measures the person — and the person is the one who leaves.

The Short Answer

cognitive_effort scores how much mental work a specific kind of person has to spend to use your page, and tells you which part of that work breaks them first.

Not "is the page fast." Not "does it pass WCAG." Both of those can be green while a real visitor gives up on screen two.

Here is a real measurement from a university homepage we tested. Same page, same code, four different people:

The first-time visitor is doing 2.6 times the mental work of the ADHD visitor on identical HTML. That difference is not a bug in the page. It is the page meeting four different sets of capacities, and only one of those people is in real trouble.

Lighthouse gives this page one number. So does axe. cognitive_effort gives you eight, per person, and tells you which one is the wall.

What It Actually Measures

The model is borrowed from a simple idea: using a page costs something, and everyone has a different amount to spend.

You arrive with a budget — attention, working memory, patience, reading stamina, motor precision. The page makes demands on each of those. Where demand exceeds what you have, it costs you. Where you have plenty, it is free.

That is the whole model in one sentence, and the interesting part is what it lets you say that a single score cannot: why it is hard, and for whom.

The Eight Layers

Using a page is not one act. It is a sequence, and each step has its own way of failing. The chain runs in the order a person actually experiences it:

1. Saliency — can they find the thing they came for? The feeling of scanning a page and not seeing the button that is right there. Measured as visual prominence against how readily this person notices change at all. Fix: raise contrast, size or isolation on the one element that matters. Competing emphasis is the same as none.

2. Cognitive Load — is there more here than they can hold at once? Reading a page twice and still not knowing what it wants from you. Information and visual density against working memory and comprehension. Fix: cut, group, or defer. Familiarity is real capacity, so a returning visitor genuinely pays less here.

3. Decision — are there too many choices? A nav with 180 links where every one of them might be the right one. Choice count under Hick-Hyman, against tolerance for risk and for settling on "good enough". Fix: reduce or rank. A default is cheaper than a choice; a recommendation is cheaper than a list.

4. Motor — can they physically hit the target? Missing a small link twice before it takes. Fitts' law: how long the movement takes, and how likely it lands. Those are two independent things, and we model them separately. Fix: bigger targets, further apart. Spacing helps accuracy even when size cannot change.

5. Motor Procedure — can they get through the whole sequence? Knowing which button to press and still losing your place halfway through the form. Separate from Motor because hitting a target and completing a procedure fail for different reasons, and conflating them hides one of them. Fix: shorten the sequence or make its state visible.

6. Frustration — how close are they to giving up? The point where you decide the site is not worth it. This layer is where the others are paid for: cumulative friction against patience and resilience. Fix: nothing here directly. Fix whichever layer is feeding it.

7. Readability — can they decode the words? Re-reading a sentence because the type is too tight, too small, or too clever. This is decoding only: turning marks into words. Fix: simpler sentences, plainer vocabulary, larger and looser type.

8. Reading Attention — can they hold the line long enough to finish? Reaching the bottom of a paragraph with no idea what it said. Split from Readability because decoding and holding your place are different abilities. An ADHD reader typically decodes fine and loses the thread, and a single "reading" score cannot express that. Fix: break long passages, cut what competes with them, put the important sentence first.

Why the Order Matters

The layers are not eight independent scores that get averaged. They run in sequence, and each one is paid out of what the previous ones left.

This is the part that makes the model tell you something a checklist cannot. A page that is uniformly a bit demanding and a page that exhausts someone in the first two layers can produce the same total — and they are completely different problems. The first needs broad trimming. The second needs one thing fixed.

It also means the same page is genuinely a different page depending on who arrives. Someone who knows your site spends almost nothing on Cognitive Load, which leaves them more for everything after it. A first-timer spends it all up front and arrives at your form already depleted.

What It Tells You That You Can Act On

Here is the practical output, from that same university homepage.

Which layer is the wall, per person. For the low-vision and hand-tremor visitors, the bottleneck was Decision — and it jumped from 0.064 to 0.480 once we measured the whole page instead of just the top. The cause was a 180-link mega-menu that is invisible above the fold. That is a specific, findable, fixable thing. No accessibility scanner flagged it, because nothing about it is a violation.

Where people stop. Score the page as a sequence of screens and you get an expected depth:

Every one of them drops at screen 2 — but for different reasons. The two cognitive profiles hit Cognitive Load. The two sensory and motor profiles hit Decision. One screen, two distinct causes, one place to spend your afternoon.

That is the output that changes what a developer does on Monday. Not "your score is 68". Rather: screen two, the mega-menu, and the density above it — and here is which of your visitors each one costs.

Which of your users you are actually failing. Fixing the mega-menu barely helps the first-time visitor. Cutting density on screen two barely helps the tremor user. A single score forces you to guess which; eight per-person layers just tell you.

Why You Should Trust It

Fair question, and the honest answer is not "because we say so."

It is built on published models, not vibes. Fitts' law for pointing. Hick-Hyman for choice. Established readability and working-memory literature. Where a layer rests on a specific paper, we cite it. Where a layer does not yet have one — the two newest splits do not — we say so rather than inventing a citation.

Every claim it makes is testable, and we test it against itself. The scoring engine is pinned to a golden corpus: if a change moves a published number, the build fails and someone has to say why. Properties that must always hold are asserted as properties, not as examples. A longer page can never come out safer. A declared measurement scope has to change the measurement, not just the label on it.

We publish our own corrections. Earlier this year we ran our saliency model against 495 pages of real eye-tracking data and a centred blob beat it. We wrote that up. When an external reviewer told us our attentional reading cost was moving the wrong direction on long pages, we confirmed it, fixed it, and published the before and after. A model that has never been shown to be wrong about anything is not a model anyone has checked.

The output tells you which of its own numbers to distrust. Ask for the sequential breakdown and the payload will tell you, in plain language, that the compounded total is the least reliable figure in it and that expected depth and drop-off are what to act on. We would rather ship a number with a warning label than a confident number you cannot audit.

The Caveats, Plainly

Personas are not people. Each one is a single hypothetical person with fixed traits, not a population. "68% abandonment risk" is not a prediction that 68 out of 100 visitors leave. It is the probability that this modelled person's budget is exhausted given they process the whole page. Treat it as a comparison instrument, not a forecast.

Some constants are not yet calibrated against field data. The curve that turns accumulated cost into an abandonment figure has an exponent nobody set empirically. It is flagged as uncalibrated in the code and in the output, and it is why we tell you to trust the ranking of screens over the absolute percentage.

It measures effort, not intent. A page can be effortless and still fail to persuade anyone. This tool tells you whether someone can get through. Whether they want to is a different question and we do not pretend to answer it.

None of that makes the numbers less useful. It makes them numbers you can reason about, which is more than most scores offer.

Why This Is Different

Every other tool in your pipeline models a machine.

Lighthouse models a browser. Bundle analysers model a network. Accessibility scanners model a specification: they ask whether your markup satisfies a rule, which is a genuinely useful question and a completely different one from whether a person with a tremor can complete your checkout.

There is a real gap between "compliant" and "usable", and most teams only discover it through support tickets and funnel drop-off — signals that arrive weeks late and never tell you which element caused them.

cognitive_effort models a person. It gives you the thing user research gives you, at the speed of a linter: run it on a branch, get eight numbers for four kinds of visitor, see which one moved.

That is the shift. Not a better score — a different subject. You have always been able to measure your page. Now you can measure the person trying to use it, before they are the one telling you it did not work.

---

cognitive_effort is available through the cbrowser MCP server and CLI. Pass scope: "full_page" to measure the whole document, or scope: "sequential" to score it screen by screen and get expected depth and drop-off.