[RFC] Add Smooth Scrolling transition to the Table of Contents.

[SatanshuMishra]

What version of starlight are you using?

0.15.2

What is your idea?

For context, when I mention Table of Contents, the following section is what I am talking about:

To make navigating via the Table of Contents smoother. Instead of the page snapping to a section when clicking it's section link on the Table of Contents, add a simple scrolling effect that smooth scrolls the page to the linked section.

Why is this feature necessary?

While this change is purely aesthetic, eliminating the abrupt and often jarring scroll jumps in favour for smooth scrolling would make the navigating via the Table of Contents more user friendly and make the docs more visually appealing.

Do you have examples of this feature in other projects?

The following are examples of the intended behaviour. While the aesthetics of these pages may not match that of Starlight, my idea is to combine the behaviour seen in these examples with the pre-existing Table of Contents in Starlight:

• Example A - Clicking the links at the top left smooth scrolls down to the relevant section on the page instead of Snapping to it.
• Example B - Another example can be seen in the Demo shown near the end of the page.

Participation

• I am willing to submit a pull request for this feature.

[delucis]

Thanks for the detailed write up and demo links @SatanshuMishra! Appreciate the care taken putting together this proposal.

I think on balance we’d prefer not to add this as the default behaviour.

A few reasons:

1. Smooth scrolling can cause issues for users with vestibular disorders (see “Designing Safer Web Animation For Motion Sensitivity” for some more details), so even though this can be partially addressed using prefers-reduced-motion media queries, I’d still rather avoid something that might cause folks issues if they haven’t or don’t know how to set up those media options on their device.

2. Especially on longer pages, smooth scrolling can take a while and can actually slow down users. Without it, they click an item, see the content they want instantly.

3. It’s relatively simple to add to your site if you’d like to override the default! Some custom CSS containing the following should be all you need:

   @media (prefers-reduced-motion: no-preference) {
     html {
       scroll-behavior: smooth;
     }
   }

[SatanshuMishra]

Makes sense and I agree. Thought I would suggest it just to get some opinions on the idea :)! Thanks for the comment!

[delucis]

No problem — and thanks again for the thoughtful proposal! 🙌