Add optimize-scroll-stability guide

[knowler]

Towards #311

This adds the guide for optimize-scroll-stability which uses contain-intrinsic-size (and friends) for content-visibility: auto. I went with the simplest use case as we can include more advanced ones after I/O.

[knowler]

@malchata do you think the guide should include the following which could affect scroll stability?

1. Should it cover reflow use cases (e.g. items in a wrapping flex layout). The current guide focuses on height/block-size for intrinsic size. For wrapping layout, an item’s width can affect when subsequent content wraps which in turn can also affect scroll. This can be harder to guess a good intrinsic size for.
2. Should it over cover advanced use cases like Alex Russell’s which leverages ResizeObserver and IntersectionObserver to set the exact intrinsic size for elements inline.

I guess you could think of the first as problems that arise in two-dimensional layouts. The technique Alex demonstrates is like “what to do when you need the exact intrinsic size, but can’t infer that from the content,” which could be relevant for both one and two dimension situations.

[malchata]

I would consider an advanced use case as a "nice to have", and the more I think about it, it might be something to land after I/O. ResizeObserver is tricky in part because it runs its callback at a time where it could delay the next frame from being painted. So let's hold off on the advanced stuff for now.

[rviscomi]

Should it cover reflow use cases (e.g. items in a wrapping flex layout). The current guide focuses on height/block-size for intrinsic size. For wrapping layout, an item’s width can affect when subsequent content wraps which in turn can also affect scroll. This can be harder to guess a good intrinsic size for.

Is there a workaround for this, or is the guidance effectively "make an educated guess and good luck"? Asking as someone who's given up on a content-visibility optimization before for this exact reason, so I would actually be very eager to see this covered if there's anything actionable.

I would almost rather hold off on publishing this until we have more time to smooth over these advanced use cases and rough edges with more guidance. IMO it's fine to tackle that after I/O rather than rush out a more basic version of this guide, which might trip some developers up.

WDYT @knowler @malchata?

[rviscomi]

This is missing an expectations file

[knowler]

@rviscomi Unless the exact size of the contents is known ahead of time, it’s very difficult to avoid the reflow issues for two-dimensional layouts, since even for good guesses, an error has more significant effects that don’t get smoothed over as well compared to one-dimensional layouts. With that said, if you can leverage more information about the content ahead of time, like a character count, then you could improve your guesses significantly. This is a some what contrived example (since I’m using the same character to fill the items): https://knowler.dev/demos/hO9UCFj?codepen

The more advanced techniques of caching the sizes after an initial layout seem a bit too tricky to include as instructions for an agent, as there could be a lot of contextual variables necessary to factor into that. There’d also be some performance tradeoffs as well.

[LeaVerou]

(Apologies if you got an email with a half-written version of this, I accidentally hit the keyboard shortcut and posted too soon)

My high level concern is that "optimize scroll stability" is in the same vein as "improve text legibility", i.e. not a concrete use case that an agent is likely to search for. It's good guidance, but it's more useful referenced from elsewhere (i.e. like the new guide-skills) instead of expecting it to come up in a use case search.

But the description already kind of hints at the actual use cases:

Keep the page layout, scroll bar, and scroll position as stable as possible as users scroll through content-heavy pages (feeds, dashboards, long lists) where elements transition from hidden to visible.

It just needs flipping: When we're implementing content-heavy pages (feeds, dashboards, long lists), especially lazy loaded, keeping the page layout and scrollbar stable is one of the things that improve user experience. Are there other things? Can we make a guide that's focused on the concerns that one needs to have in mind when implementing these kinds of long lazy loaded feeds? Scroll stability is only one factor. What are the others?

I would suggest:

• Move the guidance that's the same for all uses of content-visibility and contain-intrinsic-size to a features/ guide and include it here. E.g. the advice about determining good sizes for this is good, and I can't imagine how other uses of contain-intrinsic-size wouldn't benefit from it (but I haven't yet looked at the 6-7 guides we have on these features)
• Focus this around use cases rather than scroll stability and include only the delta that's different from other uses of these features.

From a quick look, we also repeat guidance about how to pick a good size in performance/efficient-background-processing and in performance/defer-rendering-heavy-content:

• 'auto' is optional and enables the browser to remember the actual size
  once rendered. It must be paired with a value to be used for
  the first render.
• 'none' tells the browser not to apply any intrinsic width to this element.
  It can be used for either the height or the width value.
• '500px' is the estimated height of this element. This can be any valid
  CSS value. Replace it with the expected height of your
  component.

Whereas in other places where contain-intrinsic-size is mentioned, it would benefit from this guidance, but it isn't there. E.g. the CSS guide:

• Always pair content-visibility with contain-intrinsic-size to prevent scrollbar jumps (CLS).

Code Example: Render Optimization

.large-section {
  content-visibility: auto;
  contain-intrinsic-size: auto 800px;
}

.popover-reveal {
  /* Allow discrete animations for display transitions */
  transition: display 0.2s allow-discrete;
}

Demo: It's very hard to see what the demo is demonstrating. Commenting content-visibility and contain-intrinsic-size out seems to produce no difference. Also note that scroll anchoring makes the baseline behavior better (though that only affects scroll position, not size). I think it's because all 1000 items are rendered synchronously in one for loop, including their contents.

Last, there's a section at the start with reference-style docs — these shouldn't be needed, this hasn't changed recently and is not super brand new.

(@rviscomi one caveat about this review is that that like I said, perf-related things are not my forte, so I can review what's here, but I'm not the right person to tell you what's missing, if anything!)

[LeaVerou]

This reads like reference documentation for contain-intrinsic-size, which the model shouldn't need (the property is Baseline Widely Available, so its syntax is well within its training data)

[knowler]

@LeaVerou Thank you for the review! I agree that including this guidance along with content-visibility: auto is a good idea — as I was just writing the expectations that became apparent. Also, TIL about scroll anchoring!

@rviscomi Does it seem like a good idea to defer this guide until after I/O? Perhaps before then, there could be some minor additions to the CSS skills that suggest almost always pairing content-visibility: auto with contain-intrinsic-size, as Lea suggested?

[LeaVerou]

@rviscomi Does it seem like a good idea to defer this guide until after I/O? Perhaps before then, there could be some minor additions to the CSS skills that suggest almost always pairing content-visibility: auto with contain-intrinsic-size, as Lea suggested?

We already have this guidance — that it was a direct quote from the CSS skill! Though it's missing the guidance about the CSS units that produce better estimates, which is great!

[rviscomi]

Does it seem like a good idea to defer this guide until after I/O?

Yeah let's pause this for now and pick it back up after I/O. I'll move it to draft.