docs(date-picker): gower review (carbon-design-system#3096)

* docs(date-picker): gower review

* Update date-format-placement.png

* add type styles

* Update style.mdx

* Apply suggestions from design review

Co-authored-by: Lauren Rice <43969356+laurenmrice@users.noreply.github.com>

* update calendar images

Co-authored-by: Lauren Rice <43969356+laurenmrice@users.noreply.github.com>

src/pages/components/date-picker/style.mdx

@@ -10,20 +10,29 @@ tabs: ['Usage', 'Style', 'Code', 'Accessibility']
 
 ### Date input
 
-| Element            | Property         | Color token         |
-| ------------------ | ---------------- | ------------------- |
-| Label              | text-color       | `$text-secondary`   |
-| Field              | background-color | `$field` \*         |
-|                    | border-bottom    | `$border-strong` \* |
-| Field text         | text-color       | `$text-primary`     |
-| Field text: prompt | text-color       | `$text-helper`      |
-| Calendar icon      | svg              | `$icon-primary`     |
+| Element          | Property         | Color token         |
+| ---------------- | ---------------- | ------------------- |
+| Label            | text-color       | `$text-secondary`   |
+| Field            | background-color | `$field` \*         |
+|                  | border-bottom    | `$border-strong` \* |
+| Field text       | text-color       | `$text-primary`     |
+| Placeholder text | text-color       | `$text-placeholder` |
+| Helper text      | text-color       | `$text-helper`      |
+| Calendar icon    | svg              | `$icon-primary`     |
 
 <Caption>
   * Denotes a contextual color token that will change values based on the layer
   it is placed on.
 </Caption>
 
+<Row>
+<Column colLg={8}>
+
+![Date picker input states](images/date-picker-style-7.png)
+
+</Column>
+</Row>
+
 <br />
 
 #### Interactive states
@@ -45,7 +54,7 @@ tabs: ['Usage', 'Style', 'Code', 'Accessibility']
 |          | Calendar icon   | svg              | `$icon-disabled`   |
 
 <Row>
-<Column colLg={8}>
+<Column colLg={12}>
 
 ![Date picker input states](images/date-picker-style-6.png)
 
@@ -64,9 +73,9 @@ tabs: ['Usage', 'Style', 'Code', 'Accessibility']
 | Day                 | text-color       | `$text-primary`                  |
 | Day: hover          | background-color | `$layer-hover` \*                |
 | Day: focus          | border           | `$focus`                         |
+| Day: disabled       | text-color       | `$text-disabled`                 |
 | Day: selected       | text-color       | `$text-on-color`                 |
 |                     | background-color | `$background-brand`              |
-| Day: disabled       | text-color       | `$text-disabled`                 |
 | Day: in range       | text-color       | `$text-primary`                  |
 |                     | background-color | `$highlight`                     |
 | Day: end range      | text-color       | `$text-primary`                  |
@@ -96,23 +105,30 @@ tabs: ['Usage', 'Style', 'Code', 'Accessibility']
 Labels should be set in sentence case, with only the first word in a phrase and
 any proper nouns capitalized, and no more than three words.
 
-| Element       | Font-size  | Font-weight   | Type token  |
-| ------------- | ---------- | ------------- | ----------- |
-| Label         | 12 / 0.75  | Regular / 400 | `$label-01` |
-| Field text    | 14 / 0.875 | Regular / 400 | `$code-02`  |
-| Error message | 12 / 0.75  | Regular / 400 | `$label-01` |
+| Element         | Font-size  | Font-weight    | Type token            |
+| --------------- | ---------- | -------------- | --------------------- |
+| Label           | 12 / 0.75  | Regular / 400  | `$label-01`           |
+| Field text      | 14 / 0.875 | Regular / 400  | `$code-02`            |
+| Helper text     | 12 / 0.75  | Regular / 400  | `$label-01`           |
+| Error message   | 12 / 0.75  | Regular / 400  | `$label-01`           |
+| Warning message | 12 / 0.75  | Regular / 400  | `$label-01`           |
+| Month and year  | 14 / 0.875 | SemiBold / 600 | `$heading-compact-01` |
+| Day             | 14 / 0.875 | Regular / 400  | `$body-compact-01`    |
 
 ## Structure
 
 ### Date inputs
 
 The widths of the date inputs may vary based on the grid and layout.
 
-| Element | Property                    | px / rem | Spacing token |
-| ------- | --------------------------- | -------- | ------------- |
-| Label   | padding-bottom              | 8 / 0.5  | `$spacing-03` |
-| Field   | padding-left, padding-right | 16 / 1   | `$spacing-05` |
-|         | border-bottom               | 1px      | -             |
+| Element       | Property                    | px / rem | Spacing token |
+| ------------- | --------------------------- | -------- | ------------- |
+| Label         | margin-bottom               | 8 / 0.5  | `$spacing-03` |
+| Field         | padding-left, padding-right | 16 / 1   | `$spacing-05` |
+|               | border-bottom               | 1px      | –             |
+| Helper text   | margin-top                  | 4 / .25  | `$spacing-02` |
+| Calendar icon | height, width               | 16 / 1   | –             |
+|               | padding-left                | 8 / 0.5  | `$spacing-03` |
 
 <div className="image--fixed">
 
@@ -140,16 +156,14 @@ The widths of the date inputs may vary based on the grid and layout.
 
 ### Calendar menu
 
-| Element        | Property                                 | px / rem | Spacing token |
-| -------------- | ---------------------------------------- | -------- | ------------- |
-| Calendar       | height                                   | 336 / 21 | –             |
-|                | width                                    | 288 / 18 | –             |
-|                | padding-top, padding-right, padding-left | 4 / 0.25 | `$spacing-02` |
-|                | padding-bottom                           | 8 / 0.5  | `$spacing-03` |
-| Calendar: icon | height, width                            | 16 / 1   | –             |
-|                | padding-right, padding-left              | 16 / 1   | `$spacing-05` |
-| Day            | height, width                            | 40 / 2.5 | –             |
-| Today: dot     | height, width                            | 4 / 0.25 | –             |
+| Element       | Property                                 | px / rem | Spacing token |
+| ------------- | ---------------------------------------- | -------- | ------------- |
+| Calendar menu | height                                   | 336 / 21 | –             |
+|               | width                                    | 288 / 18 | –             |
+|               | padding-top, padding-right, padding-left | 4 / 0.25 | `$spacing-02` |
+|               | padding-bottom                           | 8 / 0.5  | `$spacing-03` |
+| Day           | height, width                            | 40 / 2.5 | –             |
+| Today: dot    | height, width                            | 4 / 0.25 | –             |
 
 <div className="image--fixed">
 
@@ -172,7 +186,7 @@ The widths of the date inputs may vary based on the grid and layout.
 There are two types of time pickers; a 12-hour and 24-hour time picker. The
 12-hour Time Picker is accompanied by a time period (am/pm) input, while the
 24-hour clock is not. Refer to [select](/components/select/code) for inline
-select styling. Hi
+select styling.
 
 | Element | Property                    | px / rem | Spacing token |
 | ------- | --------------------------- | -------- | ------------- |

src/pages/components/date-picker/usage.mdx

@@ -8,8 +8,8 @@ tabs: ['Usage', 'Style', 'Code', 'Accessibility']
 
 <PageDescription>
 
-Date and time pickers allow users to select a single or a range of dates and
-times.
+Date and time pickers allow users to select a single instance or range of dates
+and times.
 
 </PageDescription>
 
@@ -30,23 +30,23 @@ times.
 
 ## Overview
 
-Pickers are used to display past, present, or future dates or times. The kind of
-date (exact, approximate, memorable) you are requesting from the user will
-determine which picker is best to use. Each picker's format can be customized
-depending on location or need.
+Date pickers allow users to select past, present, or future dates. The kind of
+date you are requesting from the user will determine which date picker (simple
+or calendar) is best to use. A time picker helps users select a specific time.
+You can customize the time picker's format depending on location or need.
 
 ### When to use
 
-Use date and time pickers when you are asking the user for a time or date, or
-for scheduling tasks.
+- When asking the user for an exact, approximate, or memorable date or time.
+- For scheduling tasks.
 
 ### Variants
 
-| Variant             | Purpose                                                                                                                                                                                                                               |
-| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| _Simple date input_ | Use if the date can be remembered by the user easily, such as a date of birth, and they don’t need a calendar to anticipate the dates. It consists only of input fields.                                                              |
-| _Calendar pickers_  | Use a calendar picker when the user needs to know a date's relationship to other days or when a date could be variable. It allows the user to view and pick dates from a calendar widget or manually type the date in the text field. |
-| _Time picker_       | Use when asking the user to input a specific time.                                                                                                                                                                                    |
+| Variant                                                              | Purpose                                                                                                                                                                                                                                    |
+| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| [Simple date input](/components/date-picker/usage#simple-date-input) | Use if the date can be remembered by the user easily, such as a date of birth, and they don’t need a calendar to anticipate the dates. It consists only of input fields.                                                                   |
+| [Calendar picker](/components/date-picker/usage#calendar-pickers)    | Use a calendar picker (single or range) when the user needs to know a date's relationship to other days or when a date could be variable. The user can view and pick dates from a calendar widget or manually type them in the text field. |
+| [Time picker](/date-picker/usage#time-pickers)                       | Use when asking the user to input a specific time.                                                                                                                                                                                         |
 
 ## Live demo
 
@@ -199,13 +199,18 @@ for scheduling tasks.
 1. **Label**: Instructs the user what to do with the control.
 2. **Date field**: A text input field where the user can manually type in the
    date.
-3. **Icon**: `calendar` icon indicates the calendar menu is available.
-4. **Calendar**: The menu where a date may be selected.
-5. **Month and year controls**: Allows the user to navigate through past and
+3. **Date format**: Format instructions should appear as helper text below the
+   field or inline with the label.
+4. **Icon**: `calendar` icon indicates the calendar menu is available.
+5. **Calendar**: The menu where a date may be selected.
+6. **Month and year controls**: Allows the user to navigate through past and
    future time frames.
-6. **Previous and next month controls**: Allows the user to move forward or
+7. **Week day**: Days of the week.
+8. **Previous and next month controls**: Allows the user to move forward or
    backward one month at a time.
-7. **Day**: Days in the month.
+9. **Day**: Days in the month, see
+   [calendar variants](/components/date-picker/usage#calendar-variants) for
+   specific day styles.
 
 ### Anatomy of a time picker
 
@@ -256,7 +261,9 @@ should always be aligned to the left edge of its assigned text field.
 
 ### Sizes
 
-Date picker comes in three sizes: small (32px), medium (40px), and large (48px).
+The input fields for date and time picker come in three height sizes: small
+(32px), medium (40px), and large (48px). The calendar menu in the date picker is
+a fixed height and width and does not change with the input size.
 
 <Row>
 <Column colLg={8}>
@@ -376,7 +383,7 @@ the same interactive state and behaviors. See the
 [style tab](/components/date-picker/style) for more details.
 
 <Row>
-<Column colLg={8}>
+<Column colLg={12}>
 
 ![Simple date input states](images/simple-date-input-states.png)
 
@@ -401,7 +408,7 @@ Use a calendar picker when the user needs to know a date's relation to other
 days such as the day of the week it falls on or its proximity to today. They are
 optimal for scheduling tasks.
 
-### Variants
+### Calendar variants
 
 #### Single date picker
 
@@ -544,29 +551,6 @@ a meeting time.
 </Column>
 </Row>
 
-## Modifiers
-
-### Light variant
-
-Use the `light` prop modifier when placing date pickers on alternate
-backgrounds. The light prop will change the background color token of the inputs
-from `field-01` to `field-02`. This is frequently used in form modals or when on
-a tile.
-
-<Row>
-<Column colLg={8}>
-
-![Light prop example](images/date-picker-light-prop.png)
-
-</Column>
-</Row>
-
-<Caption>
-  {' '}
-  Both inputs are displayed in the white theme but the one on the right is using
-  the light prop on the alternate UI background.{' '}
-</Caption>
-
 ## Related
 
 #### Asking for relative times and dates
@@ -578,10 +562,10 @@ made by using the standard [select](/components/select/usage/) component.
 
 #### Using individual inputs
 
-Another acceptable form of a time or date experience would be using individual
-inputs for each factor. Using an individual field for each factor of a date or
-time can help reduce formatting errors. This is especially beneficial when
-localization cannot be used to reformat dates.
+Another acceptable form of a date experience would be using individual inputs
+for each factor. Using an individual field for each factor of a date can help
+reduce formatting errors. This is especially beneficial when localization cannot
+be used to reformat dates.
 
 Instead of having one input for an exact date (month/day/year), you could have
 three separate inputs and a clear label for each.