The spec disagrees with developer documentation about whether precise layout-shift values/thresholds should be relied on

[dholbert]

The Layout Instability spec seems to be in conflict with Google's articles/documentation on how layout shift values should be used & thought about.

From the spec:

Developers are advised to avoid relying on the precise value of the layout shift score, as the metric might evolve over time, and user agents might compromise precision in the interest of calculation efficiency.
(source: WICG spec text)

...vs, from Google's developer articles:

To provide a good user experience, pages should maintain a CLS of less than 0.1.
(source: Web.dev article, another web.dev article, implicit in in "page speed insights" report ranking)

(Technically the spec text is about individual LS values rather than the CLS, but it still applies to the CLS score by extension, since the CLS is a sum of LS scores.)

The above-quoted spec text seems to be saying that the precise value (and precise thresholds like 0.1) aren't meaningful -- it sounds like it's saying authors should prefer to watch for increases/decreases rather than reasoning about any one precise value. However, this disagrees with the web.dev articles and pagespeed insights reports, which treat the precise values 0.1 and 0.25 as special thresholds.

If my reading of the spec isn't the intended meaning (i.e. if values are indeed intended to be meaningful on their own, rather than just metrics to watch for increases/decreases), then maybe that line of spec text should be reworded to clarify what it's trying to say?

[npm1]

I believe the spec is talking about precision in the sense that a small-magnitude change could be expected from a user agent that is implementing the metric, or such deltas can be expected when comparing values between user-agents. This is because the spec provides some flexibility around edge cases and around performance optimizations that may be used to compute the shifts faster. Still, at the scale in which CLS is reported, 0.1 is actually pretty large (I know, not super intuitive), so I still think it makes sense for a developer to aim to be below that threshold while also not paying attention to very small deltas, orders of magnitude smaller than the target. Does this make sense? If so, we can update the spec text so that the intention behind the text is clearer. Let me know what you think!

[dholbert]

Maybe if we reworded the spec text to something like the following, it'd be clearer that you're intending to talk about precision in the sense of small variations being ignorable?

Something like:
"Developers are advised to avoid reacting to small amounts of variation between layout shift scores; this metric is not intended to be a high-precision value, so user agents might compromise precision in the interest of calculation efficiency. Moreover, the definition of the metric may evolve over time."

(I don't love the word "reacting" here, but I can't think of a better word off the top of my head.)

[npm1]

s/reacting to/worrying about? I like the suggestion, thanks!

[dholbert]

Sure, that sounds good. Thanks!