docs: update slider with range variant (#3789)

* update usage.mdx

* update style.mdx

* remove unused images

* update usage.mdx

* update style.mdx

* update images

* fix image

* update style.mdx

* update usage.mdx

* new images

* update a11y.mdx

* fix bugs

* update style.mdx

* feat: add live demo range slider variant

* update mp4 content

* chore: format

* chore: format

* chore: update yarn

* chore: replace yarn lockfile with main

* chore: update yarn version

* chore: fix yarn

* chore: fix ci

* update mp4 covers

---------

Co-authored-by: Andrea N. Cardona <[email protected]>
Co-authored-by: Alison Joseph <[email protected]>

.github/workflows/ci.yml

@@ -15,6 +15,8 @@ jobs:
         uses: actions/[email protected]
         with:
           node-version: '20.x'
+      - name: Set yarn version
+        run: yarn set version 4.0.1
       - name: Install dependencies
         run: yarn install --immutable
       - name: Check formatting of project files

.yarnrc.yml

@@ -1,3 +1,5 @@
+nmHoistingLimits: workspaces
+
 nodeLinker: node-modules
 
-nmHoistingLimits: workspaces
+yarnPath: .yarn/releases/yarn-4.0.1.cjs

src/pages/components/slider/accessibility.mdx

@@ -1,13 +1,16 @@
 ---
 title: Slider
 description:
-  Sliders provide a visual indication of adjustable content, where the user can
-  move the handle along a horizontal track to increase or decrease the value.
+  No accessibility annotations are needed for sliders, but keep these
+  considerations in mind if you are modifying Carbon or creating a custom
+  component.
 tabs: ['Usage', 'Style', 'Code', 'Accessibility']
 ---
 
-import localVideo from './videos/slider.mp4';
-import localPoster from './images/slider-accessibility-3.png';
+import localVideoOne from './videos/default-slider-demo.mp4';
+import localPosterOne from './images/slider-accessibility-default-mp4-image.png';
+import localVideoTwo from './videos/range-slider-demo.mp4';
+import localPosterTwo from './images/slider-accessibility-range-mp4-image.png';
 
 <PageDescription>
 
@@ -28,11 +31,12 @@ Carbon bakes keyboard operation into its components, improving the experience of
 blind users and others who operate via the keyboard. Carbon incorporates many
 other accessibility considerations, some of which are described below.
 
-### Keyboard interactions
+### Keyboard interactions (default slider)
 
-Tab order goes from slider to text input. Arrow keys are used to change the
-slider value. `Shift`+arrow changes the slider value by a larger increment (such
-as by 10 instead of 1). Users can also directly enter a value in the input.
+Tab order goes from slider to number input. Arrow keys are used to change the
+slider value. `Shift` + `Arrow` changes the slider value by a larger increment
+(such as by 10 instead of 1). Users can also directly enter a value in the
+input.
 
 <Row>
 <Column colLg={8}>
@@ -46,16 +50,16 @@ as by 10 instead of 1). Users can also directly enter a value in the input.
 </Column>
 </Row>
 
-### Labeling and updates
+### Labeling and updates (default slider)
 
 <Row>
 <Column colLg={8}>
 
-![slider label is connected to slider control and text input](images/slider-accessibility-2.png)
+![slider label is connected to slider control and number input](images/slider-accessibility-2.png)
 
 <Caption>
-  The slider label is programmatically associated with both the slider and
-  input.
+  The input value and slider position are in sync. An update to either causes
+  the other to update.
 </Caption>
 
 </Column>
@@ -65,11 +69,48 @@ as by 10 instead of 1). Users can also directly enter a value in the input.
 <Column colLg={8}>
 
 <Video
-  src={localVideo}
-  poster={localPoster}
+  src={localVideoOne}
+  poster={localPosterOne}
   aria-label="pointer clicks on slider range and input updates to 80. input value changes to 75 and slider repositions to match"
 />
 
+<Caption>
+  The multiple ways of updating a value within the default slider component.
+</Caption>
+
+</Column>
+</Row>
+
+### Keyboard interactions (range slider)
+
+For the range slider, tab order goes from the first number input, to the two
+handles in turn, and then to the second number input. The handle keyboard
+operation is the same as with the default slider. Users can also directly enter
+numbers into the minimum and maximum value inputs.
+
+<Row>
+<Column colLg={8}>
+
+![Both the slider and inputs are in the tab order and keyboard operable.](images/slider-accessibility-4.png)
+
+<Caption>
+  Both the slider and inputs are in the tab order and keyboard operable.
+</Caption>
+
+</Column>
+</Row>
+
+### Labeling and updates (range slider)
+
+The slider label is a description what kind of values will be selected from the
+range slider. The minimum and maximum values are labeled with placeholder text
+of min and max due to space constraints.
+
+<Row>
+<Column colLg={8}>
+
+![The input value and slider position are in sync. An update to either causes the other to update.](images/slider-accessibility-5.png)
+
 <Caption>
   The input value and slider position are in sync. An update to either causes
   the other to update.
@@ -78,6 +119,22 @@ as by 10 instead of 1). Users can also directly enter a value in the input.
 </Column>
 </Row>
 
+<Row>
+<Column colLg={8}>
+
+<Video
+  src={localVideoTwo}
+  poster={localPosterTwo}
+  aria-label="pointer clicks on slider range and input updates to 80. input value changes to 75 and slider repositions to match"
+/>
+
+<Caption>
+  The multiple ways of updating a value within the default slider component.
+</Caption>
+
+</Column>
+</Row>
+
 ## Development considerations
 
 Keep these considerations in mind if you are modifying Carbon or creating a
@@ -91,3 +148,14 @@ custom component:
 - See the
   [ARIA authoring practices](https://www.w3.org/TR/wai-aria-practices-1.2/#slider)
   for more considerations.
+
+### Error handling
+
+If an inputted value is outside the allowed range, the slider will auto-correct
+to the nearest allowed digit. When the inputted value results in an error, the
+error will display alongside the corresponding text input.
+
+In the range slider, if the inputted value is not logically correct (for
+example, if a minimum value is greater than the maximum value), a warning
+message will be generated that informs the user that a value was autocorrected
+to the nearest allowed digit.

src/pages/components/slider/code.mdx

@@ -72,5 +72,9 @@ documentation, see the Storybooks for each framework below.
       label: 'Controlled Slider',
       variant: 'components-slider--controlled-slider',
     },
+    {
+      label: 'Range Slider',
+      variant: 'components-slider--two-handle-slider',
+    },
   ]}
 />

src/pages/components/slider/style.mdx

@@ -1,16 +1,33 @@
 ---
 title: Slider
 description:
-  Sliders provide a visual indication of adjustable content, where the user can
-  move the handle along a horizontal track to increase or decrease the value.
+  The following page documents visual specifications such as color, typography,
+  structure, and size.
 tabs: ['Usage', 'Style', 'Code', 'Accessibility']
 ---
 
+<PageDescription>
+
+The following page documents visual specifications such as color, typography,
+structure, and size.
+
+</PageDescription>
+
+<AnchorLinks>
+
+<AnchorLink>Color</AnchorLink>
+<AnchorLink>Typography</AnchorLink>
+<AnchorLink>Structure</AnchorLink>
+<AnchorLink>Size</AnchorLink>
+<AnchorLink>Feedback</AnchorLink>
+
+</AnchorLinks>
+
 ## Color
 
 | Element       | Property         | Color token         |
 | ------------- | ---------------- | ------------------- |
-| Thumb         | fill             | `$icon-primary`     |
+| Handle        | fill             | `$icon-primary`     |
 | Track         | background-color | `$border-subtle` \* |
 | Track: filled | background-color | `$border-inverse`   |
 | Label         | text-color       | `$text-secondary`   |
@@ -24,36 +41,50 @@ tabs: ['Usage', 'Style', 'Code', 'Accessibility']
 <Row>
 <Column colLg={8}>
 
-![Slider enabled state](images/slider-style-color.png)
+<Tabs>
+
+<Tab label="Default">
+
+![Default slider color enabled state](images/color-default-slider.png)
+
+</Tab>
+
+<Tab label="Range">
+
+![Range slider color enabled state](images/color-range-slider.png)
+
+</Tab>
+
+</Tabs>
 
 </Column>
 </Row>
 
 ### Interactive states
 
-Slider uses a text input to type in values. See
-[text input](https://carbondesignsystem.com/components/text-input/usage/#states)
-for more information on its interactive states.
+Slider uses a number input to type in values. See
+[number input](https://carbondesignsystem.com/components/number-input/style) for
+more information on its interactive states.
 
 | State     | Element         | Property         | Color token         |
 | --------- | --------------- | ---------------- | ------------------- |
-| Focus     | Thumb           | border           | `$focus`            |
+| Focus     | Handle          | border           | `$focus`            |
 |           | Track           | background-color | `$interactive`      |
-| Active    | Thumb           | fill             | `$interactive`      |
+| Active    | Handle          | fill             | `$interactive`      |
 |           | Track           | background-color | `$interactive`      |
-| Error     | Text input      | border           | `$support-error`    |
+| Error     | Number input    | border           | `$support-error`    |
 |           | Error icon      | svg              | `$support-error`    |
 |           | Error message   | text-color       | `$text-error`       |
 | Warning   | Warning icon    | svg              | `$support-warning`  |
 |           | Warning message | text-color       | `$text-primary`     |
 | Disabled  | Label           | text-color       | `$text-disabled`    |
 |           | Range label     | text-color       | `$text-disabled`    |
-|           | Thumb           | fill             | `$border-disabled`  |
+|           | Handle          | fill             | `$border-disabled`  |
 |           | Track           | background-color | `$border-disabled`  |
 | Read-only | Label           | text-color       | `$text-secondary`   |
 |           | Range label     | text-color       | `$text-primary`     |
 |           | Track           | background-color | `$border-subtle` \* |
-|           | Track:filled    | background-color | `$border-inverse`   |
+|           | Track: filled   | background-color | `$border-inverse`   |
 
 <Caption>
   * Denotes a contextual color token that will change values based on the layer
@@ -63,7 +94,21 @@ for more information on its interactive states.
 <Row>
 <Column colLg={12}>
 
-![Slider interactive states](images/slider-style-states.png)
+<Tabs>
+
+<Tab label="Default">
+
+![Default slider interactive states](images/slider-default-style-states.png)
+
+</Tab>
+
+<Tab label="Range">
+
+![Range slider interactive states](images/slider-range-style-states.png)
+
+</Tab>
+
+</Tabs>
 
 </Column>
 </Row>
@@ -82,31 +127,71 @@ phrase and any proper nouns capitalized, and no more than three words.
 
 The width of a slider varies based on page content and layout.
 
-| Element       | Property                    | px / rem   | Spacing token |
-| ------------- | --------------------------- | ---------- | ------------- |
-| Thumb         | height, width               | 14 / 0.875 | –             |
-| Thumb:active  | height, width               | 20 / 1.25  | –             |
-| Thumb:active  | height, width               | 20 / 1.25  | –             |
-| Track         | height                      | 4 / 0.25   | –             |
-|               | margin-left, margin-right   | 8 / 0.5    | `$spacing-03` |
-| Label         | margin-bottom               | 8 / 0.5    | `$spacing-03` |
-| Range label   | margin-right                | 16 / 1     | `$spacing-05` |
-| Error message | margin-top                  | 16 / 1     | `$spacing-05` |
-| State icon    | padding-right, padding-left | 16 / 1     | `$spacing-05` |
+### Default slider structure
+
+| Element        | Property                    | px / rem   | Spacing token |
+| -------------- | --------------------------- | ---------- | ------------- |
+| Handle         | height, width               | 14 / 0.875 | –             |
+| Handle: active | height, width               | 20 / 1.25  | –             |
+| Track          | height                      | 4 / 0.25   | –             |
+|                | margin-left, margin-right   | 8 / 0.5    | `$spacing-03` |
+| Label          | margin-bottom               | 8 / 0.5    | `$spacing-03` |
+| Range label    | margin-right                | 16 / 1     | `$spacing-05` |
+| Error message  | margin-top                  | 16 / 1     | `$spacing-05` |
+| Error icon     | padding-right, padding-left | 16 / 1     | `$spacing-05` |
+| Tooltip        | padding-bottom              | 4 / 0.25   | `$spacing-02` |
 
 <div className="image--fixed">
 
-![Structure and spacing measurements for slider enabled state](images/slider-style-spec-enabled.png)
+![Structure and spacing measurements for default slider enabled state](images/slider-style-structure-default-enabled.png)
 
 </div>
 
 <div className="image--fixed">
 
-![Structure and spacing measurements for slider error state](images/slider-style-spec-error.png)
+![Structure and spacing measurements for default slider error state](images/slider-style-structure-default-error.png)
 
 </div>
 
-### Recommended
+<div className="image--fixed">
+
+![Structure and spacing measurements for default sliders with tooltips and no number inputs](images/slider-style-structure-default-tooltip.png)
+
+</div>
+
+### Range slider structure
+
+| Element        | Property                    | px / rem | Spacing token |
+| -------------- | --------------------------- | -------- | ------------- |
+| Handle         | height, width               | 16 / 1   | `$spacing-05` |
+| Handle: active | height, width               | 16 / 1   | `$spacing-05` |
+| Track          | height                      | 4 / 0.25 | –             |
+|                | margin-left, margin-right   | 16 / 1   | `$spacing-05` |
+| Label          | margin-bottom               | 8 / 0.5  | `$spacing-03` |
+| Range label    | margin-right                | 16 / 1   | `$spacing-05` |
+| Error message  | margin-top                  | 16 / 1   | `$spacing-05` |
+| Error icon     | padding-right, padding-left | 16 / 1   | `$spacing-05` |
+| Tooltip        | padding-bottom              | 0        | –             |
+
+<div className="image--fixed">
+
+![Structure and spacing measurements for range slider enabled state](images/slider-style-structure-default-enabled.png)
+
+</div>
+
+<div className="image--fixed">
+
+![Structure and spacing measurements for range slider error state](images/slider-style-structure-default-error.png)
+
+</div>
+
+<div className="image--fixed">
+
+![Structure and spacing measurements forrange sliders with tooltips and no number inputs](images/slider-style-structure-range-tooltip.png)
+
+</div>
+
+## Size
 
 The following specs are not built into the slider component but are recommended
 by design as the proper sizing for the slider tracking line.
@@ -115,3 +200,9 @@ by design as the proper sizing for the slider tracking line.
 | ------- | --------- | ---------- | ------------- |
 | Slider  | min-width | 200 / 12.5 | –             |
 |         | max-width | 640 / 40   | –             |
+
+## Feedback
+
+Help us improve this component by providing feedback, asking questions, and
+leaving any other comments on
+[GitHub](https://github.com/carbon-design-system/carbon-website/issues/new?assignees=&labels=feedback&template=feedback.md).