Editorial review: Add docs for scroll-target-group (#40843)

* Add docs for scroll-target-group

* Fixes for danielsakhapov review comments

* Update files/en-us/web/css/css_overflow/css_carousels/index.md

Co-authored-by: Dipika Bhattacharya <[email protected]>

* Update files/en-us/web/css/scroll-marker-group/index.md

Co-authored-by: Dipika Bhattacharya <[email protected]>

* Update files/en-us/web/css/_doublecolon_scroll-marker-group/index.md

Co-authored-by: Dipika Bhattacharya <[email protected]>

* Update files/en-us/web/css/_doublecolon_scroll-marker-group/index.md

Co-authored-by: Dipika Bhattacharya <[email protected]>

* Update files/en-us/web/css/scroll-target-group/index.md

Co-authored-by: Dipika Bhattacharya <[email protected]>

* Update files/en-us/web/css/scroll-target-group/index.md

Co-authored-by: Dipika Bhattacharya <[email protected]>

* Update files/en-us/web/css/scroll-target-group/index.md

Co-authored-by: Dipika Bhattacharya <[email protected]>

* Update files/en-us/web/css/scroll-target-group/index.md

Co-authored-by: Dipika Bhattacharya <[email protected]>

* Update files/en-us/web/css/scroll-target-group/index.md

Co-authored-by: Dipika Bhattacharya <[email protected]>

* Update files/en-us/web/css/scroll-target-group/index.md

Co-authored-by: Dipika Bhattacharya <[email protected]>

* Update files/en-us/web/css/scroll-target-group/index.md

Co-authored-by: Dipika Bhattacharya <[email protected]>

* Update files/en-us/web/css/scroll-target-group/index.md

Co-authored-by: Dipika Bhattacharya <[email protected]>

* Update files/en-us/web/css/scroll-target-group/index.md

Co-authored-by: Dipika Bhattacharya <[email protected]>

* Update files/en-us/web/css/scroll-target-group/index.md

Co-authored-by: Dipika Bhattacharya <[email protected]>

* Fixes for dipika review comments

* Clarify a11y semantics of scroll containers

* Clarify a11y semantics of scroll containers

---------

Co-authored-by: Dipika Bhattacharya <[email protected]>

Author: chrisdavidmills

files/en-us/web/css/_doublecolon_scroll-marker-group/index.md

@@ -22,13 +22,16 @@ The **`::scroll-marker-group`** [CSS](/en-US/docs/Web/CSS) [pseudo-element](/en-
 
 ## Description
 
-A scroll container's **`::scroll-marker-group`** pseudo-element represents a **scroll marker group**. This is a container that automatically contains any {{cssxref("::scroll-marker")}} pseudo-elements generated on itself or its descendants. This allows them to be positioned and laid out as a group, and is typically used when creating a CSS carousel to provide a scroll position indicator. The individual scroll markers can be used to navigate to their associated content items.
+A scroll container's **`::scroll-marker-group`** pseudo-element represents a **scroll marker group container**. This is a container that automatically contains any {{cssxref("::scroll-marker")}} pseudo-elements generated on itself or its descendants. This allows them to be positioned and styled as a group. This pseudo-element is typically used when creating a CSS carousel to provide a scroll position indicator. The individual scroll markers can be used to navigate to their associated content items.
 
-The scroll container must have its {{cssxref("scroll-marker-group")}} property set to a non-`none` value for the `::scroll-marker-group` pseudo-element to be generated. The {{cssxref("scroll-marker-group")}} value determines where the scroll marker group appears in the carousel's tab order and layout box order (but not DOM structure) — `before` puts it at the start, while `after` puts it at the end.
+The scroll container must have its {{cssxref("scroll-marker-group")}} property set to a non-`none` value for the `::scroll-marker-group` pseudo-element to be generated. The {{cssxref("scroll-marker-group")}} value determines where the scroll marker group container appears in the carousel's tab order and layout box order (but not DOM structure) — `before` puts it at the start, while `after` puts it at the end.
 
-It is a best practice to match the visual rendering position of the scroll marker group with the tab order. When positioning the group at the start of the content, put it at the beginning of the tab order using `before`. When positioning the group at the end of the content, put it at the end of the tab order using `after`.
+> [!NOTE]
+> Alternatively, a scroll marker group container can be created from an existing element containing a set of {{htmlelement("a")}} elements using {{cssxref("scroll-target-group")}}.
+
+As an accessibility best practice, match the visual rendering position of the scroll marker group container with the tab order. When positioning the group at the start of the content, put it at the beginning of the tab order using `before`. When positioning the group at the end of the content, put it at the end of the tab order using `after`.
 
-Accessibility-wise, the scroll marker group and contained scroll markers are rendered with [`tablist`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tablist_role)/[`tab`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tab_role) semantics. When you <kbd>Tab</kbd> to the group, it behaves like a single item (that is, another press of the <kbd>Tab</kbd> key will move past the group to the next item), and you can move between the different scroll markers using the left and right (or up and down) cursor keys.
+When a scroll marker group container is created on a scroll container using the `scroll-marker-group` property, the scroll container is rendered with [`tablist`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tablist_role)/[`tab`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tab_role) semantics. You can <kbd>Tab</kbd> to it with the keyboard, then move between the different "pages" using the left and right (or up and down) cursor keys, which also changes the state of the associated scroll markers and scroll buttons as expected. The scroll markers can also be tabbed between normally, as expected.
 
 ## Examples
 
@@ -145,9 +148,9 @@ li::scroll-marker:target-current {
 
 {{EmbedLiveSample("carousel-example", "100%", "280px")}}
 
-### Positioning the scroll marker group with anchor-positioning
+### Positioning the scroll marker group container with anchor positioning
 
-This example extends the previous one, demonstrating the use of [CSS anchor positioning](/en-US/docs/Web/CSS/CSS_anchor_positioning) to position the scroll marker group relative to the carousel.
+This example extends the previous one, demonstrating the use of [CSS anchor positioning](/en-US/docs/Web/CSS/CSS_anchor_positioning) to position the scroll marker group container relative to the carousel.
 
 #### CSS
 
@@ -185,6 +188,7 @@ ul::scroll-marker-group {
 ## See also
 
 - {{cssxref("scroll-marker-group")}}
+- {{cssxref("scroll-target-group")}}
 - {{cssxref("::scroll-button()")}}
 - {{cssxref("::scroll-marker")}}
 - {{cssxref("::column")}}

files/en-us/web/css/_doublecolon_scroll-marker/index.md

@@ -26,7 +26,10 @@ A `::scroll-marker` is generated on an element when the `::scroll-marker`'s {{cs
 
 The scroll container's `::scroll-marker-group` pseudo-element automatically contains any `::scroll-marker` pseudo-elements generated on the scroll container or its descendants. This allows them to be positioned and laid out as a group and is typically used when creating a CSS carousel to create a scroll position indicator. The individual scroll markers can be used to navigate to their associated content items.
 
-Accessibility-wise, the scroll marker group and contained scroll markers are rendered with [`tablist`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tablist_role)/[`tab`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tab_role) semantics. When you <kbd>Tab</kbd> to the group, it behaves like a single item (that is, another press of the <kbd>Tab</kbd> key will move past the group to the next item), and you can move between the different scroll markers using the left and right (or up and down) cursor keys.
+> [!NOTE]
+> Alternatively, a scroll marker group container can be created from an existing element container using {{cssxref("scroll-target-group")}}; any contained {{htmlelement("a")}} elements with fragment identifiers linking to sections of the page automatically behave like scroll markers.
+
+When a scroll marker group container is created on a scroll container using the `scroll-marker-group` property, the scroll container is rendered with [`tablist`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tablist_role)/[`tab`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tab_role) semantics. You can <kbd>Tab</kbd> to it with the keyboard, then move between the different "pages" using the left and right (or up and down) cursor keys, which also changes the state of the associated scroll markers and scroll buttons as expected. The scroll markers can also be tabbed between normally, as expected.
 
 ## Examples
 
@@ -57,7 +60,7 @@ We have a basic HTML {{htmlelement("ul")}} list with several {{htmlelement("li")
 
 We convert our `<ul>` into a scroll snapping overflow container by setting the {{cssxref("display")}} to `flex`, creating a single, non-wrapping row of `<li>` elements. The {{cssxref("overflow-x")}} property is set to `auto`, meaning if the items overflow their container on the x-axis, the content will scroll horizontally. We then convert the `<ul>` into a [scroll-snap container](/en-US/docs/Glossary/Scroll_snap#scroll_snap_container), ensuring that items always snap into place when the container is scrolled with a {{cssxref("scroll-snap-type")}} value of `mandatory`.
 
-We create a scroll marker group with the `scroll-marker-group` property, placing the group after all the content.
+We create a scroll marker group container with the `scroll-marker-group` property, placing it after all the content.
 
 ```css live-sample___creating-scroll-markers live-sample___custom-numbering
 ul {
@@ -189,6 +192,7 @@ To improve user experience, we set a different color on the markers on {{cssxref
 ## See also
 
 - {{cssxref("scroll-marker-group")}}
+- {{cssxref("scroll-target-group")}}
 - {{cssxref("::scroll-button()")}}
 - {{cssxref("::scroll-marker-group")}}
 - {{cssxref(":target-current")}}

files/en-us/web/css/css_overflow/css_carousels/index.md

@@ -23,7 +23,7 @@ Users can move through the items by clicking or activating navigational buttons
 
 A key feature of carousels is **pagination** — the items feel like separate pieces of content that are moved between rather than forming one continuous section of content. You might show one item at a time or several items on each carousel "page". When several items are visible, you might show an entirely new group of items each time the "next" or "previous" button is pressed. Alternatively, you could add a single new item to one end of the list while moving the item at the other end out of view.
 
-Creating carousels with JavaScript can be quite brittle and challenging to implement. They require scripts to associate scroll markers with the items they represent while continuously updating the scroll buttons to keep them operating correctly. When carousels are created using JavaScript, the accessibility of the carousel and the associated controls has to be added in.
+Carousels can be quite brittle and challenging to implement with JavaScript. They require scripts to associate scroll markers with the items they represent while continuously updating the scroll buttons to keep them operating correctly. When carousels are created using JavaScript, the accessibility of the carousel and the associated controls has to be added in.
 
 Fortunately, we can create accessible carousels with associated controls without the use of JavaScript, using CSS carousel features.
 
@@ -246,7 +246,7 @@ Scroll markers are a group of buttons, each one of which scrolls the carousel to
 In this section, we will add scroll markers to the carousel, which involves three main features:
 
 - The {{cssxref("scroll-marker-group")}} property is set on the scroll container element. It needs to be set to a non-`none` value for the {{cssxref("::scroll-marker-group")}} pseudo-element to be generated; its value specifies where the scroll marker group appears in the carousel's tab order and layout box order (but not DOM structure) — `before` puts it at the start, before the scroll buttons, while `after` puts it at the end.
-- The {{cssxref("::scroll-marker-group")}} pseudo-element exists inside a scroll container, and is used to collect together and lay out scroll markers.
+- The {{cssxref("::scroll-marker-group")}} pseudo-element exists inside a scroll container, and is used to collect together, contain, and lay out scroll markers as a whole group.
 - {{cssxref("::scroll-marker")}} pseudo-elements exist inside the children and {{cssxref("::column")}} fragments of a scroll container ancestor, and represent their scroll markers. These are collected inside the ancestor's {{cssxref("::scroll-marker-group")}} for layout purposes.
 
 To begin with, the list's `scroll-marker-group` property is set to `after`, so the `::scroll-marker-group` pseudo-element is placed after the list's DOM content in the focus and layout box order; this means it comes after the scroll buttons:
@@ -257,6 +257,9 @@ ul {
 }
 ```
 
+> [!NOTE]
+> Alternatively, a scroll marker group container can be created from an existing element containing a set of {{htmlelement("a")}} elements using {{cssxref("scroll-target-group")}}.
+
 Next, the list's `::scroll-marker-group` pseudo-element is positioned relative to the carousel using CSS anchor positioning, similar to the scroll button's, except that it is horizontally centered on the carousel using a {{cssxref("justify-self")}} value of `anchor-center`. The group is laid out using flexbox, with a {{cssxref("justify-content")}} value of `center` and a {{cssxref("gap")}} of `20px` so that its children (the `::scroll-marker` pseudo-elements) are centered inside the `::scroll-marker-group` with a gap between each one.
 
 ```css live-sample___first-example
@@ -297,7 +300,7 @@ li::scroll-marker:target-current {
 ```
 
 > [!NOTE]
-> Accessibility-wise, the scroll marker group and contained scroll markers are rendered with [`tablist`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tablist_role)/[`tab`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tab_role) semantics. When you <kbd>Tab</kbd> to the group with the keyboard, it behaves like a single item (that is, another press of the <kbd>Tab</kbd> key will move past the group to the next item), and you can move between the different scroll markers using the left and right (or up and down) cursor keys.
+> When a scroll marker group container is created on a scroll container using the `scroll-marker-group` property, the scroll container is rendered with [`tablist`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tablist_role)/[`tab`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tab_role) semantics. You can <kbd>Tab</kbd> to it with the keyboard, then move between the different "pages" using the left and right (or up and down) cursor keys, which also changes the state of the associated scroll markers and scroll buttons as expected. The scroll markers can also be tabbed between normally, as expected.
 
 ## Single page carousel final result
 
@@ -519,7 +522,7 @@ ul::scroll-marker-group {
 
 ### Column scroll markers
 
-The CSS for creating the scroll markers in this demo is nearly identical to the [previous demo](#creating_scroll_markers), except that the selectors are different — the scroll markers are created on the generated `::column` scroll markers rather than the list items (note how we are including two pseudo-elements here, to generate scroll markers on the generated columns).
+The CSS for creating the scroll markers in this demo is nearly identical to the [previous demo](#creating_scroll_markers), except that the selectors are different — the scroll markers are created on the generated `::column` pseudo-elements rather than the list items. Note how we are including two pseudo-elements here to generate scroll markers on the generated columns.
 
 ```css live-sample___second-example
 ul::column::scroll-marker {

files/en-us/web/css/css_overflow/index.md

@@ -227,6 +227,7 @@ A link is included in the content box above to demonstrate the effects of keyboa
 - {{CSSxRef("overflow-y")}}
 - {{CSSxRef("scroll-behavior")}}
 - {{cssxref("scroll-marker-group")}}
+- {{cssxref("scroll-target-group")}}
 - {{CSSxRef("scrollbar-gutter")}}
 - {{CSSxRef("text-overflow")}}
 

files/en-us/web/css/scroll-marker-group/index.md

@@ -10,7 +10,10 @@ sidebar: cssref
 
 {{seecompattable}}
 
-The **`scroll-marker-group`** [CSS](/en-US/docs/Web/CSS) property controls whether a {{glossary("scroll container")}} has a {{cssxref("::scroll-marker-group")}} pseudo-element generated and, if so, whether it should be placed immediately `before` _or_ `after` the container's contents in the default visual and tabbing order.
+The **`scroll-marker-group`** [CSS](/en-US/docs/Web/CSS) property controls whether a {{glossary("scroll container")}} element has a {{cssxref("::scroll-marker-group")}} pseudo-element generated. If present, the property also specifies whether the scroll marker group should be placed `before` _or_ `after` the contents of the scroll group container in the default visual and tab order.
+
+> [!NOTE]
+> To create a scroll marker group container from an existing element that contains a set of {{htmlelement("a")}} elements, use the {{cssxref("scroll-target-group")}} property. Read about the [differences in behavior](/en-US/docs/Web/CSS/scroll-target-group#differences_between_scroll-target-group_and_scroll-marker-group) between the two.
 
 ## Syntax
 
@@ -40,7 +43,7 @@ scroll-marker-group: unset;
   - : No `::scroll-marker-group` pseudo-element will be generated on the element. This is the default value.
 
 > [!NOTE]
-> It is a best practice to match the visual rendering position of the scroll marker group with the tab order. When positioning the marker group at the start of the content with styles applied to {{cssxref("::scroll-marker-group")}}, put it at the beginning of the tab order using `before`. When positioning the group at the end of the content, put it at the end of the tab order using `after`.
+> As an accessibility best practice, match the visual rendering position of the scroll marker group container with the tab order. When positioning the marker group at the start of the content with styles applied to {{cssxref("::scroll-marker-group")}}, put it at the beginning of the tab order using `before`. When positioning the group at the end of the content, put it at the end of the tab order using `after`.
 
 ## Formal definition
 
@@ -88,7 +91,7 @@ We have a basic HTML {{htmlelement("ul")}} list with several {{htmlelement("li")
 
 We convert our `<ul>` into a carousel by setting the {{cssxref("display")}} to `flex`, creating a single, non-wrapping row of `<li>` elements. The {{cssxref("overflow-x")}} property is set to `auto`, meaning if the items overflow their container on the x-axis, the content will scroll horizontally. We then convert the `<ul>` into a [scroll-snap container](/en-US/docs/Glossary/Scroll_snap#scroll_snap_container), ensuring that items always snap into place when the container is scrolled with a {{cssxref("scroll-snap-type")}} value of `mandatory`.
 
-We create a scroll marker group with the `scroll-marker-group` property, placing the group after all the content.
+We create a scroll marker group container with the `scroll-marker-group` property, placing the group after all the content.
 
 ```css
 ul {
@@ -167,7 +170,7 @@ label {
 
 {{EmbedLiveSample("Examples", '', '300')}}
 
-Note the placement of the scroll marker group. Check out how the keyboard tabbing order is different for `before` versus `after`, and note how the group disappears when the value is set to `none`.
+Note the placement of the scroll marker group container. Check out how the keyboard tabbing order is different for `before` versus `after`, and note how the group disappears when the value is set to `none`.
 
 ## Specifications
 
@@ -179,6 +182,7 @@ Note the placement of the scroll marker group. Check out how the keyboard tabbin
 
 ## See also
 
+- {{cssxref("scroll-target-group")}}
 - {{cssxref("::scroll-button()")}}
 - {{cssxref("::scroll-marker-group")}}
 - {{cssxref("::scroll-marker")}}