[number input] number input doc update v11

src/pages/components/number-input/style.mdx

@@ -63,11 +63,12 @@ tabs: ['Usage', 'Style', 'Code', 'Accessibility']
 Number input labels should use sentence case, with only the first word in a
 phrase and any proper nouns capitalized.
 
-| Element       | Font-size (px/rem) | Font-weight   | Type token  |
-| ------------- | ------------------ | ------------- | ----------- |
-| Label         | 12 / 0.75          | Regular / 400 | `$label-01` |
-| Field input   | 14 / 0.875         | Regular / 400 | `$code-02`  |
-| Error message | 12 / 0.75          | Regular / 400 | `$label-01` |
+| Element         | Font-size (px/rem) | Font-weight   | Type token  |
+| --------------- | ------------------ | ------------- | ----------- |
+| Label           | 12 / 0.75          | Regular / 400 | `$label-01` |
+| Field input     | 14 / 0.875         | Regular / 400 | `$code-02`  |
+| Error message   | 12 / 0.75          | Regular / 400 | `$label-01` |
+| Warning message | 12 / 0.75          | Regular / 400 | `$label-01` |
 
 ## Structure
 

src/pages/components/number-input/usage.mdx

@@ -8,8 +8,8 @@ tabs: ['Usage', 'Style', 'Code', 'Accessibility']
 
 <PageDescription>
 
-The number input component is used for entering numeric values and includes
-controls for incrementally increasing or decreasing the value.
+Number input lets users enter a numeric value and incrementally increase or
+decrease the value with a two-segment control.
 
 </PageDescription>
 
@@ -18,14 +18,49 @@ controls for incrementally increasing or decreasing the value.
 <AnchorLink>Overview</AnchorLink>
 <AnchorLink>Live demo</AnchorLink>
 <AnchorLink>Formatting</AnchorLink>
+<AnchorLink>Content</AnchorLink>
+<AnchorLink>Behaviors</AnchorLink>
+<AnchorLink>Related</AnchorLink>
+<AnchorLink>References</AnchorLink>
 <AnchorLink>Feedback</AnchorLink>
 
 </AnchorLinks>
 
 ## Overview
 
-Number inputs are similar to text inputs, but contain controls used to increase
-or decrease an incremental value.
+Number inputs are similar to text inputs, but are used to specify only a numeric value.
+Number inputs incrementally increase or
+decrease the value with a two-segment control. Number input reduces input
+efforts for adjusting small values.
+
+<Row>
+<Column colLg={8}>
+
+![number input image](images/number-input-usage-1.png)
+
+</Column>
+</Row>
+
+### When to use
+
+- The user needs to input a numeric value
+- Adjusting small values when increasing or decreasing them requires only a few
+  clicks
+- When users may not know exact values and only want to change the values that
+  are relative to its current state
+
+### When not to use
+
+- It is best practice not to use number input if large value changes are
+  expected. For example, when the value sets from 1 to 30, number input is not a
+  great option because it requires many clicks to reach 30. In this case, use
+  [slider](https://carbondesignsystem.com/components/slider/usage/) when numeric
+  values are large or when there is a wide range of numeric options.
+- It is also best to avoid number input for continuous variables such as prices,
+  distances, lengths, or human heights. When the exact value is important to
+  specify within a wide range, use
+  [text input](https://carbondesignsystem.com/components/text-input/usage/)
+  instead.
 
 ## Live demo
 
@@ -39,8 +74,7 @@ or decrease an incremental value.
       id: 'mobile-number-input',
       label: 'Mobile',
     },
-  ]}
->
+  ]}>
   <ComponentVariant
     id="number-input"
     links={{
@@ -51,8 +85,7 @@ or decrease an incremental value.
       Vue: 'http://vue.carbondesignsystem.com/?path=/story/components-cvnumberinput--default',
       'Web Components':
         'https://web-components.carbondesignsystem.com/?path=/story/components-number-input--default',
-    }}
-  >
+    }}>
     {`
     <NumberInput
       helperText="Optional helper text"
@@ -76,8 +109,7 @@ or decrease an incremental value.
       Vue: 'http://vue.carbondesignsystem.com/?path=/story/components-cvnumberinput--default',
       'Web Components':
         'https://web-components.carbondesignsystem.com/?path=/story/components-number-input--default',
-    }}
-  >
+    }}>
     {`
         <NumberInput
           isMobile
@@ -96,24 +128,180 @@ or decrease an incremental value.
 
 ## Formatting
 
-- Do not use number inputs when large value changes are expected. They work best
-  for making small, incremental changes that require only a few clicks.
-- Enable the user to also choose to type a number in the field.
-- Ensure that a default value is shown within the field.
-- Use a clear and concise label for the number input.
-- Use sentence-style capitalization (only the first word in a phrase and any
-  proper nouns capitalized) for the label.
-- See further guidance for using number labels within
-  [forms](/components/form/usage).
+### Anatomy
+
+<Row>
+<Column colLg={8}>
+
+![number input anatomy](images/number-input-usage-2.png)
+
+</Column>
+</Row>
+
+1. **Label**: Text that informs the user about the content they need to enter in
+   the field. It is required unless you get an approved accessibility exemption.
+2. **Numeric value**: The value changes when user enters a value into the field
+   or uses the subtract or add controls.
+3. **Helper text**: Assistive text that can provide additional aid or context to
+   the user. Often used to explain the correct data format.
+4. **Field**: The container in which a user enters data.
+5. **Subtract icon**: This icon triggers decremental values.
+6. **Add icon**: This icon triggers incremental values.
+7. **Status icon**: Indicates the state of the number input, either error or
+   warning.
+8. **Error or Warning text**: It replaces the helper text when an error or
+   warning state appears.
+
+### Sizing
+
+Number input has three sizes in height: **small**, **medium**, and **large**.
+The width varies in size based on content, layout, and design.
+
+| Size        | Height (px/rem) | Use case                                                                                                                                              |
+| ----------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Small (sm)  | 32 / 2          | Use when space is constricted or when placing a number input in a form that is long and complex.                                                      |
+| Medium (md) | 40 / 2.5        | This is the default size and the most commonly used size. When in doubt, use the medium size.                                                         |
+| Large (lg)  | 48 / 3          | Use when there is a lot of space to work with. The large size is typically used in simple forms or when a number input is placed by itself on a page. |
+
+<Row>
+<Column colLg={8}>
+
+![number input sizes](images/number-input-usage-3.png)
+
+</Column>
+</Row>
+
+## Content
+
+### Main elements
+
+#### Label
+
+- Always include a label so that users know how to complete the field
+- Keep the label short and concise
+- Use sentence-style capitalization for the label
+
+<DoDontRow>
+  <DoDont caption="Do include a label">
+
+![Do include a label](images/number-input-usage-4.png)
+
+  </DoDont>
+  <DoDont type="dont" caption="Do not hide a label that helps user understand the context of number input">
+
+![Do not hide label](images/number-input-usage-5.png)
+
+  </DoDont>
+</DoDontRow>
+
+#### Helper text
+
+- Indicates the input value if it has a maximum or minimum
+- Helper text is optional but if present will be replaced by warning and error
+  messages when needed
+
+#### Overflow content
+
+Label, numeric value, and helper text should be short and not exceed two lines.
+
+## Behaviors
+
+### States
+
+The number input has a series of states for both field and controls elements:
+**enabled**, **hover**, **focus**, **error**, **warning**, and **disabled**.
+
+| State       | When to use                                                                                                                                                                                                                                                         |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| _Enabled_   | When the number input is live but a user is not directly interacting with it. This is commonly referred to as the default or normal state of the component. An enabled number input field should contain a default value.                                           |
+| _Hover_     | When a user's mouse cursor is hovering over the field or the button controls.                                                                                                                                                                                       |
+| _Focus_     | When a user tabs to or clicks on the number input, the field or controls become focused, indicating the user has successfully navigated to the component.                                                                                                           |
+| _Error_     | When the required number input has not been filled in. It can also be triggered due to a system error. This state requires a user response before data can be submitted or saved.                                                                                   |
+| _Warning_   | When you need to call the user's attention to an exception condition. The condition might not be an error but can cause problems if not resolved.                                                                                                                   |
+| _Disabled_  | When the user is not allowed to interact with the number input due to either permissions, dependencies, or pre-requisites. The disabled state completely removes the interactive function from a component. The styling is not subject to WCAG contrast compliance. |
+| _Skeleton_  | Use on an initial page load to indicate that the number input has not yet fully loaded.                                                                                                                                                                             |
+| _Read-only_ | _Coming soon!_                                                                                                                                                                                                                                                      |
+
+<Row>
+<Column colLg={12}>
+
+![number input interactive states](images/number-input-usage-6.png)
+
+</Column>
+</Row>
+
+### Interactions
+
+#### Mouse
+
+Users can click on the input field and change the value by typing inside the
+input field. Users can also increase or decrease the values by pressing on the
+add or subtract icon controls.
+
+<Row>
+<Column colLg={8}>
+
+![number input mouse and keyboard interactions](images/number-input-usage-7.png)
+
+</Column>
+</Row>
+
+#### Keyboard
+
+Users can navigate to the number input field by pressing `Tab`. Users can then
+increase the value by pressing `Up arrow` or decrease the value by pressing
+`Down arrow`.
+
+### Validation
+
+#### Invalid
+
+An error state is triggered if the data is invalid or a required field is left
+empty. Error states have three visual indicators to signify invalid content: a
+red border, an error icon indicator, and an error message.
 
 <Row>
 <Column colLg={8}>
 
-![number input example](images/number-input-usage-1.png)
+![number input validation](images/number-input-usage-8.png)
 
 </Column>
 </Row>
 
+### Default values
+
+Numeric input should always have a default. The default will usually be ‘1’.
+Sometimes, you will have input value defaulted to ‘0’. For example, when booking
+a hotel room, it may set the default number of adults as ‘1’ and the default
+number of children as ‘0’.
+
+<Row>
+  <DoDont caption="Do set a clear default that most users are likely to select">
+
+![Do set default for input value](images/number-input-usage-9.png)
+
+  </DoDont>
+  <DoDont type="dont" caption="Do not leave value input blank">
+
+![Do not leave value input blank](images/number-input-usage-10.png)
+
+  </DoDont>
+</Row>
+
+## Related
+
+- Use [slider](https://carbondesignsystem.com/components/slider/usage/) when
+  numeric values are large or when there is a wide range of numeric options.
+- When the exact value is important to specify within a wide range, use
+  [text input](https://carbondesignsystem.com/components/text-input/usage/)
+  instead.
+
+## References
+
+Yuxuan (Tammy) Zhou,
+[Design Guidelines for Input Steppers](https://www.nngroup.com/articles/input-steppers/)
+(Nielsen Norman Group, 2018)
+
 ## Feedback
 
 Help us improve this component by providing feedback, asking questions, and