From 69626afb0664170632a1404339bdc8d247e31456 Mon Sep 17 00:00:00 2001
From: Florian Rivoal <git@florian.rivoal.net>
Date: Thu, 21 Oct 2021 14:04:37 +0900
Subject: [PATCH] [css-scrollbars] Add notes and advisements to scrollbar-width

This clarifies the purpose of the property, as well as how users are
ultimately in charge of this UI component.

See #6351
---
 css-scrollbars-1/Overview.bs | 36 +++++++++++++++++++++++++++++++++++-
 1 file changed, 35 insertions(+), 1 deletion(-)

diff --git a/css-scrollbars-1/Overview.bs b/css-scrollbars-1/Overview.bs
index 9ba4aa46281c..67235e47299d 100644
--- a/css-scrollbars-1/Overview.bs
+++ b/css-scrollbars-1/Overview.bs
@@ -192,9 +192,32 @@ Percentages: n/a
 This property allows the author to specify
 the desired thickness of an element’s scrollbars.
 
+<div class=advisement>
+	The primary purpose of this property is not
+	to allow authors to chose a particular scrollbar aesthetic for their pages,
+	but to let them indicate for certain small or cramped elements of their pages
+	that a smaller scrollbar would be desirable.
+
+	Scrollbars are a UI mechanism essential to interact with the page.
+	Operating systems tend to want consistency in such controls to improve usability through familiarity,
+	and users with specific preferences or needs can adjust
+	the appearance of various UI components, including scrollbars,
+	through OS or UA settings.
+
+	While using this property in support of specific UX goals is appropriate,
+	authors should otherwise refrain from overriding such user preferences.
+</div>
+
 <dl dfn-type="value" dfn-for=scrollbar-width>
 <dt><dfn>auto</dfn></dt>
-<dd>Implementations must use the default platform scrollbar width.
+<dd>Implementations must use the default scrollbar width.
+
+Note: On most systems, this corresponds to the traditional somewhat wide scrollbar.
+However, through OS or UA settings,
+users can have the ability to change what this default corresponds to,
+possibly making the default scrollbar
+wider or narrower than is typical.
+
 </dd>
 <dt><dfn>thin</dfn></dt>
 <dd>Implementations should use thinner scrollbars than ''scrollbar-width/auto''.
@@ -204,6 +227,10 @@ The scrollbar should nonetheless remain wide enough to be usable.
 (Implementers may wish to consult
 <a href="https://www.w3.org/TR/WCAG21/#target-size">WCAG 2.1 SC 2.5.5 Target Size</a>. [[WCAG21]])
 
+User agents may disregard this value and treat it as ''scrollbar-width/auto'',
+for instance when the user has indicated discomfort
+for thin scrollbars through some UA or OS setting.
+
 Note: Some platforms only have a tiny scrollbar by default
 which cannot be reasonably made thinner.
 In such cases, this value will behave as ''scrollbar-width/auto''.
@@ -230,6 +257,13 @@ authors should use ''overflow: hidden'' instead of ''scrollbar-width: none''.
 </dd>
 </dl>
 
+<div class=note>Note: Users who find the ''thin'' style of scrollbars unusable
+can include the following rule in their [=user style sheet=]:
+<pre><code class=lang-css>* { scrollbar-width: auto !important; }</code></pre>
+This will ensure that all scrollbars are sized as per OS and UA settings
+regardless of author styles.
+</div>
+
 UAs must apply the 'scrollbar-width' value set on the root element to the viewport.
 
 Note: Unlike the 'overflow' property (and its longhands),