diff --git a/src/pages/components/text-input/images/text-area-anatomy-fixed.png b/src/pages/components/text-input/images/text-area-anatomy-fixed.png new file mode 100644 index 00000000000..f4447800df1 Binary files /dev/null and b/src/pages/components/text-input/images/text-area-anatomy-fixed.png differ diff --git a/src/pages/components/text-input/images/text-area-anatomy-fluid.png b/src/pages/components/text-input/images/text-area-anatomy-fluid.png new file mode 100644 index 00000000000..fb72d10b7c8 Binary files /dev/null and b/src/pages/components/text-input/images/text-area-anatomy-fluid.png differ diff --git a/src/pages/components/text-input/images/text-area-counter.png b/src/pages/components/text-input/images/text-area-counter.png index 72193f8b159..0576dd3112d 100644 Binary files a/src/pages/components/text-input/images/text-area-counter.png and b/src/pages/components/text-input/images/text-area-counter.png differ diff --git a/src/pages/components/text-input/images/text-area-style-structure-fixed.png b/src/pages/components/text-input/images/text-area-style-structure-fixed.png new file mode 100644 index 00000000000..34027595ed7 Binary files /dev/null and b/src/pages/components/text-input/images/text-area-style-structure-fixed.png differ diff --git a/src/pages/components/text-input/images/text-area-style-structure-fluid.png b/src/pages/components/text-input/images/text-area-style-structure-fluid.png new file mode 100644 index 00000000000..9447713a094 Binary files /dev/null and b/src/pages/components/text-input/images/text-area-style-structure-fluid.png differ diff --git a/src/pages/components/text-input/images/text-input-anatomy-fixed.png b/src/pages/components/text-input/images/text-input-anatomy-fixed.png new file mode 100644 index 00000000000..9262d5d21b1 Binary files /dev/null and b/src/pages/components/text-input/images/text-input-anatomy-fixed.png differ diff --git a/src/pages/components/text-input/images/text-input-anatomy-fluid.png b/src/pages/components/text-input/images/text-input-anatomy-fluid.png new file mode 100644 index 00000000000..6f3931fd21d Binary files /dev/null and b/src/pages/components/text-input/images/text-input-anatomy-fluid.png differ diff --git a/src/pages/components/text-input/images/text-input-mouse-fixed.png b/src/pages/components/text-input/images/text-input-mouse-fixed.png new file mode 100644 index 00000000000..8a46a6308e0 Binary files /dev/null and b/src/pages/components/text-input/images/text-input-mouse-fixed.png differ diff --git a/src/pages/components/text-input/images/text-input-mouse-fluid.png b/src/pages/components/text-input/images/text-input-mouse-fluid.png new file mode 100644 index 00000000000..be4831d4666 Binary files /dev/null and b/src/pages/components/text-input/images/text-input-mouse-fluid.png differ diff --git a/src/pages/components/text-input/images/text-input-style-color-fixed.png b/src/pages/components/text-input/images/text-input-style-color-fixed.png new file mode 100644 index 00000000000..5fd90a78c2e Binary files /dev/null and b/src/pages/components/text-input/images/text-input-style-color-fixed.png differ diff --git a/src/pages/components/text-input/images/text-input-style-color-fluid.png b/src/pages/components/text-input/images/text-input-style-color-fluid.png new file mode 100644 index 00000000000..7fa304be8eb Binary files /dev/null and b/src/pages/components/text-input/images/text-input-style-color-fluid.png differ diff --git a/src/pages/components/text-input/images/text-input-style-size.png b/src/pages/components/text-input/images/text-input-style-size.png index 2c2b7c48f2e..477347b01a1 100644 Binary files a/src/pages/components/text-input/images/text-input-style-size.png and b/src/pages/components/text-input/images/text-input-style-size.png differ diff --git a/src/pages/components/text-input/images/text-input-style-states-fixed.png b/src/pages/components/text-input/images/text-input-style-states-fixed.png new file mode 100644 index 00000000000..b420319f037 Binary files /dev/null and b/src/pages/components/text-input/images/text-input-style-states-fixed.png differ diff --git a/src/pages/components/text-input/images/text-input-style-states-fluid.png b/src/pages/components/text-input/images/text-input-style-states-fluid.png new file mode 100644 index 00000000000..e6e0d092b0a Binary files /dev/null and b/src/pages/components/text-input/images/text-input-style-states-fluid.png differ diff --git a/src/pages/components/text-input/images/text-input-style-structure-fixed.png b/src/pages/components/text-input/images/text-input-style-structure-fixed.png new file mode 100644 index 00000000000..619ade3d4a1 Binary files /dev/null and b/src/pages/components/text-input/images/text-input-style-structure-fixed.png differ diff --git a/src/pages/components/text-input/images/text-input-style-structure-fluid.png b/src/pages/components/text-input/images/text-input-style-structure-fluid.png new file mode 100644 index 00000000000..f42f1bc703a Binary files /dev/null and b/src/pages/components/text-input/images/text-input-style-structure-fluid.png differ diff --git a/src/pages/components/text-input/images/text-input-usage-4-do-fluid.png b/src/pages/components/text-input/images/text-input-usage-4-do-fluid.png new file mode 100644 index 00000000000..a4cc4a060ea Binary files /dev/null and b/src/pages/components/text-input/images/text-input-usage-4-do-fluid.png differ diff --git a/src/pages/components/text-input/images/text-input-usage-states-fixed.png b/src/pages/components/text-input/images/text-input-usage-states-fixed.png new file mode 100644 index 00000000000..35579669a72 Binary files /dev/null and b/src/pages/components/text-input/images/text-input-usage-states-fixed.png differ diff --git a/src/pages/components/text-input/images/text-input-usage-states-fluid.png b/src/pages/components/text-input/images/text-input-usage-states-fluid.png new file mode 100644 index 00000000000..a1f05c0c618 Binary files /dev/null and b/src/pages/components/text-input/images/text-input-usage-states-fluid.png differ diff --git a/src/pages/components/text-input/style.mdx b/src/pages/components/text-input/style.mdx index b78a4d3a94f..d18d3e86476 100755 --- a/src/pages/components/text-input/style.mdx +++ b/src/pages/components/text-input/style.mdx @@ -25,35 +25,65 @@ tabs: ['Usage', 'Style', 'Code', 'Accessibility'] -![text input states](images/text-input-style-1.png) + + + + +![Example of an enabled text input in the fixed style](images/text-input-style-color-fixed.png) + + + + + +![Example of an enabled text input in the fluid style](images/text-input-style-color-fluid.png) + + + + ### Interactive states -| State | Element | Property | Color token | -| -------- | ------------- | ------------- | ---------------- | -| Focus | Field | outline | `$focus` | -| Invalid | Field | outline | `$support-error` | -| | Error message | text color | `$text-error` | -| | Warning icon | svg | `$support-error` | -| Disabled | Field | background | `$field` \* | -| | Field | border-bottom | transparent | -| | Field text | text color | `$text-disabled` | +| State | Element | Property | Color token | +| -------- | --------------- | ------------- | ------------------ | +| Focus | Field | border | `$focus` | +| Invalid | Field | border | `$support-error` | +| | Error message | text color | `$text-error` | +| | Error icon | svg | `$support-error` | +| Warning | Warning message | text color | `$text-primary` | +| | Warning icon | svg | `$support-warning` | +| Disabled | Field | background | `$field` \* | +| | Field | border-bottom | transparent | +| | Field text | text color | `$text-disabled` | - + + + + + + +![Examples of text input states in the fixed style](images/text-input-style-states-fixed.png) + + + + -![text input interactive states](images/text-input-style-3.png) +![Examples of text input states in the fluid style](images/text-input-style-states-fluid.png) + + + + ## Typography -Text input labels and placeholder text should be set in sentence case, with only -the first word in a phrase and any proper nouns capitalized. Text input labels +Text input labels and field text should be set in sentence case, with only the +first word in a phrase and any proper nouns capitalized. Text input labels should be three words or less. | Element | Font-size (px/rem) | Font-weight | Type token | @@ -65,27 +95,54 @@ should be three words or less. ## Structure -### Text input +### Text input – Fixed -| Element | Property | px / rem | Spacing token | -| ------------ | --------------------------- | -------- | ------------- | -| Label | margin-bottom | 8 / 0.5 | `$spacing-03` | -| Helper text | margin-top | 4 / 0.25 | `$spacing-02` | -| Field text | padding-left, padding-right | 16 / 1 | `$spacing-05` | -| Field | border-bottom | 1px | – | -| Field: focus | border | 2px | – | +| Element | Property | px / rem | Spacing token | +| ----------- | --------------------------- | -------- | ------------- | +| Label | margin-bottom | 8 / 0.5 | `$spacing-03` | +| Helper text | margin-top | 4 / 0.25 | `$spacing-02` | +| Input text | padding-left, padding-right | 16 / 1 | `$spacing-05` | +| Field | border-bottom | 1px | – | +| Focus | border | 2px | – | +| Error | border | 2px | – |
-![Structure and spacing measurements for text input](images/text-input-style-2.png) +![Structure and spacing measurements for fixed text input](images/text-input-style-structure-fixed.png)
-Structure and spacing measurements for text input | px / rem + + Structure and spacing measurements for fixed text input | px / rem + + +### Text input – Fluid + +| Element | Property | px / rem | Spacing token | +| ------- | --------------------------- | ----------- | ------------- | +| Label | padding-bottom | 4 / 0.25 | `$spacing-02` | +| Field | height | 64 / 4 | `$spacing-10` | +| | padding-left, padding-right | 16 / 1 | `$spacing-05` | +| | padding-top, padding-bottom | 13 / 0.8125 | – | +| | border-bottom | 1px | – | +| Focus | border | 2px | – | +| Error | border | 2px | – | -### Text area +
+ +
+ +![Structure and spacing measurements for fluid text input](images/text-input-style-structure-fluid.png) + +
+ + + Structure and spacing measurements for fluid text input | px / rem + + +### Text area – Fixed | Element | Property | px / rem | Spacing token | | ------------ | --------------------------- | ----------- | ------------- | @@ -99,14 +156,39 @@ should be three words or less.
-![Structure and spacing measurements for text area](images/text-area-style-1.png) +![Structure and spacing measurements for fixed text area](images/text-area-style-structure-fixed.png) + +
+ + + Structure and spacing measurements for fixed text area | px / rem + + +### Text area – Fluid + +| Element | Property | px / rem | Spacing token | +| ------------ | --------------------------- | ----------- | ------------- | +| Label | margin-bottom | 4 / 0.25 | `$spacing-02` | +| Field | height | varies | – | +| | padding-left, padding-right | 16 / 1 | `$spacing-05` | +| | padding-top, padding-bottom | 11 / 0.6875 | – | +| | border-bottom | 1px | – | +| Field: focus | border | 2px | – | + +
+ +![Structure and spacing measurements for fluid text area](images/text-area-style-structure-fluid.png)
-Structure and spacing measurements for text area | px / rem + + Structure and spacing measurements for fluid text area | px / rem + ## Sizes +These sizes apply only to the fixed style of text input. + | Element | Size | Height (px / rem) | | ------- | ----------- | ----------------- | | Input | Small (sm) | 32 / 2 | diff --git a/src/pages/components/text-input/usage.mdx b/src/pages/components/text-input/usage.mdx index c91f5767bc7..4f9b165c961 100755 --- a/src/pages/components/text-input/usage.mdx +++ b/src/pages/components/text-input/usage.mdx @@ -17,12 +17,13 @@ and short-form entries. Overview Live demo +Text input +Text area Formatting Content Universal behaviors -Text input -Text area -References +Modifiers +Related Feedback @@ -34,6 +35,14 @@ used should reflect the length of the content you expect the user to enter. The default text input is for short, one-line content, whereas text area is for longer, multi-line entries. + + + +![Text input and text area example](images/text-input-usage-2.png) + + + + #### When to use - A user needs to input unique information that cannot be predicted with a @@ -93,7 +102,7 @@ longer, multi-line entries. id="test2" invalidText="A valid value is required" labelText="Text input label" - placeholder="Placeholder text" + placeholder="Optional placeholder text" /> `} @@ -116,7 +125,7 @@ longer, multi-line entries. id="test2" invalidText="A valid value is required" labelText="Text input label" - placeholder="Placeholder text" + placeholder="Optional placeholder text" showPasswordLabel="Show password" /> @@ -143,21 +152,47 @@ longer, multi-line entries. id="test2" invalidText="A valid value is required" labelText="Text area label" - placeholder="Placeholder text" + placeholder="Optional placeholder text" rows={4} /> `} -## Formatting +## Text input + +Use a text input when the expected user input is a single line of text. Text +inputs have a fixed height and are used to enter simple free-form data entries +with any combination of letters, numbers, or symbols. There are two styles of +text input, fixed and fluid, which share the same functionality but look +visually different. The context of how or where the component is used will +dictate which style to use. + +| Style | Purpose | +| ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Fixed | Fixed is the most commonly used text input style with the label and helper text outside the field. Use when white space is needed between input components or in productive moments where space is at a premium, and smaller components are needed. | +| Fluid | Fluid is an alternate styling for text input used in more expressive moments. Use in fluid forms, contained spaces, or attached to complex components, like a toolbar. Fluid components always sit flush with components around them. | ### Anatomy -![Text input anatomy](images/text-input-usage-anatomy.png) + + + + +![Anatomy of a text input in the fixed style](images/text-input-anatomy-fixed.png) + + + + + +![Anatomy of a text input in the fluid style](images/text-input-anatomy-fluid.png) + + + + @@ -165,20 +200,16 @@ longer, multi-line entries. 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. **Value**: The content the user has entered into the field. -3. **Helper text** (optional): 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. Must meet 3:1 non-text +3. **Field**: The container in which a user enters data. Must meet 3:1 non-text contrast requirements. -5. **Input requirement** (optional): This label indicates if the field is - optional or required for the user to complete. -6. **Character counter** (text area only): Indicate the number of characters - being entered and the total number of characters allowed. -7. **Resize handle** (text area only): Allows a user to manipulate the field - height by making it longer or shorter. +4. **Helper text** (optional): Assistive text that can provide additional aid or + context to the user. Often used to explain the correct data format. It is + positioned below the field in the fixed style and surfaced through a tooltip + in the fluid style. ### Sizing -#### Text input heights +#### Fixed input heights There are three text input height sizes: small, medium, and large. Supporting three sizes gives you more flexibility in structuring layouts. Be sure to use a @@ -198,55 +229,117 @@ consistent field height when pairing form components on the same page. -#### Text area height +## Text area + +Use a text area when the expected user input is more than a few words and could +span multiple lines. It is commonly used for features like user commentary or +descriptions. It supports all the same states and functionality as text input +except for the password functionality. Text area has several unique +functionalities not included in the text input, like the resize handle and +character counter. + +| Style | Purpose | +| ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Fixed | Fixed is the most commonly used text area style with the label and helper text outside the field. Use when white space is needed between input components or in productive moments where space is at a premium, and smaller components are needed. | +| Fluid | Fluid is an alternate styling for text area used in more expressive moments. Use in fluid forms, contained spaces, or attached to complex components, like a toolbar. Fluid components always sit flush with components around them. | + +### Anatomy + + + + + + + + +![Anatomy of a text area in the fixed style](images/text-area-anatomy-fixed.png) + + + + + +![Anatomy of a text area in the fluid style](images/text-area-anatomy-fluid.png) + + + + + + + + +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. **Value**: The content the user has entered into the field. +3. **Field**: The container in which a user enters data. Must meet 3:1 non-text + contrast requirements. +4. **Resize handle**: Allows a user to manipulate the field height by making it + longer or shorter. +5. **Optional versus required indicator** (optional): This label indicates if + the field is optional or required for the user to complete. +6. **Character counter** (optional): Indicate the number of characters being + entered and the total number of characters allowed. + +### Sizing Text area has a variable height that can be lengthened or shortened by the user -using the `resize` handle in the bottom right of the field. By default, text -area has a minimum height of 40px/2.5rem but no maximum height. +using the resize handle in the bottom right of the field. By default, text area +has a minimum height of 40px/2.5rem but no maximum height. + +#### Resize handle + +Included by default in both fixed and fluid text area is the resize handle. It +allows a user to manipulate the field height by making it longer or shorter. The +resize handle has no effect on the width of the text area container, it only +effects the height. If the user makes the field size shorter than the content +inside the field then a vertical scroll will become available. - + -![Text input heights](images/text-area-usage-size.png) +![Example showing the resize handle in text area](images/text-area-usage-resize.png) -#### Widths +## Formatting + +### Alignment -The field widths of both text input and text area should reflect the intended -length of the content while still aligning to the grid columns or mini unit -grid. Unlike the height, the width of the text area cannot be controlled by the -user. There are no minimum or maximum widths but you should avoid excessively -wide fields that are disproportionate to the intended data being collected. +Input labels should vertically align to the grid and with other type elements on +the page. The alignment of the input container will differ based on the style of +text input you are using. Default inputs are always flush to the columns and +fluid inputs will hang into the gutters. - + -![Do use proportional widths](images/text-input-width-do.png) +![Do align field containers to the grid.](images/text-input-usage-4-do.png) - + -![Do not make inputs excessively wide.](images/text-input-width-dont.png) +![Do hang fluid field containers to the gutter.](images/text-input-usage-4-do-fluid.png) -### Alignment +#### Placement -Labels and field containers should vertically align to the grid and with other -form components on a page. +The field widths of both text input and text area should reflect the intended +length of the content while still aligning to the grid columns or mini unit +grid. Unlike the height, the width of the text area cannot be controlled by the +user. There are no minimum or maximum widths but you should avoid excessively +wide fields that are disproportionate to the intended data being collected. - + -![Do align field containers to the grid.](images/text-input-usage-4-do.png) +![Do use proportional widths](images/text-input-width-do.png) - + -![Do not align field text to the grid and hang the field in the gutter.](images/text-input-usage-4-dont.png) +![Do not make inputs excessively wide.](images/text-input-width-dont.png) @@ -265,7 +358,6 @@ consult an accessibility expert before proceeding with a label-less design. - Use sentence-style capitalization for all labels, except for product names and proper nouns. - Keep the label short and concise. -- Labels should clearly state the requirement status. - Do not use colons after label names. #### Helper text @@ -275,16 +367,15 @@ completing a field. It is often used to explain the correct data format. - Use sentence-style capitalization, and in most cases, write the text as full sentences with punctuation. -- Helper text is an optional feature and can be used in place of a tooltip. -- When used, helper text is always available when the input is focused and - appears underneath the field. The exceptions are when an error or warning - message replaces the helper text. +- When used, helper text appears persistently underneath the field, except when + an error or warning message replaces it. #### Placeholder text Optional placeholder text provides hints or examples of what to enter. -Placeholder text disappears after the user begins entering data into the input -and should not contain crucial information. +Placeholder text disappears after the user begins entering data into the input. +As such, it should not be used as a replacement for a persistent label nor +should it contain crucial information. - Use sentence-style capitalization, and in most cases, write the text as a direct statement without punctuation. @@ -293,12 +384,6 @@ and should not contain crucial information. - Placeholder text can be harmful to user interactions and should only be added when necessary. -#### Accessibility best practices - -- Labels must be announced to the screen reader on focus. -- Ensure the helper text that appears under an input is read when an assistive - technology user stops at an input using ARIA. - ### Overflow content #### Overflow in a text input @@ -340,7 +425,21 @@ sections below. -![Text input states](images/text-input-states.png) + + + + +![Text input states in the fixed style](images/text-input-usage-states-fixed.png) + + + + + +![Text input states in the fluid style](images/text-input-usage-states-fluid.png) + + + + @@ -366,18 +465,11 @@ red border, an error icon indicator, and an error message. -### Default values - -Where possible, add programmatic assistance. Detect and pre-fill inputs to -reduce errors and save time. When the software can’t determine the value that -belongs in an input, use type-ahead to make suggestions. Use sentence-case for -default values, detected values, and auto-completion text. - -### Required vs. optional +### Required versus optional Text inputs can be labeled as either optional or required depending on the -depending on the circumstance. For more guidance on requirement labeling, see -the [form pattern](/patterns/forms-pattern/#optional-vs.-mandatory). +circumstance. For more guidance on requirement labeling, see the +[form pattern](/patterns/forms-pattern/#optional-vs.-mandatory). + +![Example showing click target areas for text input in the fixed style](images/text-input-mouse-fixed.png) + + + + + +![Example showing click target areas for text input in the fluid style](images/text-input-mouse-fluid.png) + + + + @@ -425,19 +531,7 @@ For additional keyboard interactions, see the | _ctrl_ or _opt_ + _left/right arrows_ | Moves you word by word inside the field. | | _ctrl_ or _opt_ + _up/down arrows_ | Relocates you to the start or end of the input content. | -## Text input - -Use a text input when the expected user input is a single line of text. Text -inputs have a fixed height and are used as a simple free-form data entry. Users -can enter any combination of letters, numbers, or symbols. - - - - -![Example of text input in context](images/text-input-usage-1.png) - - - +## Modifiers ### Password input @@ -456,39 +550,6 @@ characters allowed or date structure. -## Text area - -Use a text area when the expected user input is more than a few words and could -span multiple lines. It is commonly used for features like user commentary or -descriptions. It supports all the same states and functionality as text input -except for the password functionality. Text area has several unique -functionalities not included in the default text input, like the resize handle -and character counter. - - - - -![Example of a text area](images/text-input-usage-2.png) - - - - -### Resize handle - -Included by default in text area is the `resize` handle. It allows a user to -manipulate the field height by making it longer or shorter. The resize handle -has no effect on the width of the text area container, it only effects the -height. If the user makes the field size shorter than the content inside the -field then a vertical scroll will become available. - - - - -![Example showing the resize handle in text area](images/text-area-usage-resize.png) - - - - ### Character counter A character counter can be added to text area to indicate both the number of @@ -505,11 +566,9 @@ has been met. -## References +## Related -- Katie Sherwin, - [Placeholders in Form Fields Are Harmful](https://www.nngroup.com/articles/form-design-placeholders/) - (Nielsen Norman Group, 2018) +- [Form pattern](/patterns/forms-pattern/) ## Feedback