diff --git a/src/pages/components/text-input/images/text-area-counter.png b/src/pages/components/text-input/images/text-area-counter.png
new file mode 100644
index 00000000000..30212357b6d
Binary files /dev/null and b/src/pages/components/text-input/images/text-area-counter.png differ
diff --git a/src/pages/components/text-input/images/text-area-usage-1.png b/src/pages/components/text-input/images/text-area-usage-1.png
deleted file mode 100644
index 0b10b71a400..00000000000
Binary files a/src/pages/components/text-input/images/text-area-usage-1.png and /dev/null differ
diff --git a/src/pages/components/text-input/images/text-area-usage-counter.png b/src/pages/components/text-input/images/text-area-usage-counter.png
new file mode 100644
index 00000000000..1c9e0fe3f9a
Binary files /dev/null and b/src/pages/components/text-input/images/text-area-usage-counter.png differ
diff --git a/src/pages/components/text-input/images/text-area-usage-height.gif b/src/pages/components/text-input/images/text-area-usage-height.gif
new file mode 100644
index 00000000000..ab98144f612
Binary files /dev/null and b/src/pages/components/text-input/images/text-area-usage-height.gif differ
diff --git a/src/pages/components/text-input/images/text-area-usage-resize.png b/src/pages/components/text-input/images/text-area-usage-resize.png
new file mode 100644
index 00000000000..6ba0cca1ce0
Binary files /dev/null and b/src/pages/components/text-input/images/text-area-usage-resize.png differ
diff --git a/src/pages/components/text-input/images/text-area-usage-size.png b/src/pages/components/text-input/images/text-area-usage-size.png
new file mode 100644
index 00000000000..1adcd560d40
Binary files /dev/null and b/src/pages/components/text-input/images/text-area-usage-size.png differ
diff --git a/src/pages/components/text-input/images/text-input-header-usage.png b/src/pages/components/text-input/images/text-input-header-usage.png
deleted file mode 100644
index e90922db022..00000000000
Binary files a/src/pages/components/text-input/images/text-input-header-usage.png and /dev/null differ
diff --git a/src/pages/components/text-input/images/text-input-states.png b/src/pages/components/text-input/images/text-input-states.png
new file mode 100644
index 00000000000..1a3865570ec
Binary files /dev/null and b/src/pages/components/text-input/images/text-input-states.png differ
diff --git a/src/pages/components/text-input/images/text-input-usage-1.png b/src/pages/components/text-input/images/text-input-usage-1.png
index 68ab3a28d1b..7bbf6d5b7fc 100644
Binary files a/src/pages/components/text-input/images/text-input-usage-1.png and b/src/pages/components/text-input/images/text-input-usage-1.png differ
diff --git a/src/pages/components/text-input/images/text-input-usage-2.png b/src/pages/components/text-input/images/text-input-usage-2.png
new file mode 100644
index 00000000000..3b4b27d1a5c
Binary files /dev/null and b/src/pages/components/text-input/images/text-input-usage-2.png differ
diff --git a/src/pages/components/text-input/images/text-input-usage-3.png b/src/pages/components/text-input/images/text-input-usage-3.png
deleted file mode 100644
index b11413943ba..00000000000
Binary files a/src/pages/components/text-input/images/text-input-usage-3.png and /dev/null differ
diff --git a/src/pages/components/text-input/images/text-input-usage-4-do.png b/src/pages/components/text-input/images/text-input-usage-4-do.png
new file mode 100644
index 00000000000..2fc120821ab
Binary files /dev/null and b/src/pages/components/text-input/images/text-input-usage-4-do.png differ
diff --git a/src/pages/components/text-input/images/text-input-usage-4-dont.png b/src/pages/components/text-input/images/text-input-usage-4-dont.png
new file mode 100644
index 00000000000..952706874c6
Binary files /dev/null and b/src/pages/components/text-input/images/text-input-usage-4-dont.png differ
diff --git a/src/pages/components/text-input/images/text-input-usage-anatomy.png b/src/pages/components/text-input/images/text-input-usage-anatomy.png
new file mode 100644
index 00000000000..fd14669db0a
Binary files /dev/null and b/src/pages/components/text-input/images/text-input-usage-anatomy.png differ
diff --git a/src/pages/components/text-input/images/text-input-usage-mouse.png b/src/pages/components/text-input/images/text-input-usage-mouse.png
new file mode 100644
index 00000000000..53174d8d98d
Binary files /dev/null and b/src/pages/components/text-input/images/text-input-usage-mouse.png differ
diff --git a/src/pages/components/text-input/images/text-input-usage-optional-do.png b/src/pages/components/text-input/images/text-input-usage-optional-do.png
new file mode 100644
index 00000000000..714a14f70a8
Binary files /dev/null and b/src/pages/components/text-input/images/text-input-usage-optional-do.png differ
diff --git a/src/pages/components/text-input/images/text-input-usage-password.png b/src/pages/components/text-input/images/text-input-usage-password.png
new file mode 100644
index 00000000000..fa9670caa48
Binary files /dev/null and b/src/pages/components/text-input/images/text-input-usage-password.png differ
diff --git a/src/pages/components/text-input/images/text-input-usage-required-do.png b/src/pages/components/text-input/images/text-input-usage-required-do.png
new file mode 100644
index 00000000000..85a4a2c4dea
Binary files /dev/null and b/src/pages/components/text-input/images/text-input-usage-required-do.png differ
diff --git a/src/pages/components/text-input/images/text-input-usage-size.png b/src/pages/components/text-input/images/text-input-usage-size.png
new file mode 100644
index 00000000000..fbe24481256
Binary files /dev/null and b/src/pages/components/text-input/images/text-input-usage-size.png differ
diff --git a/src/pages/components/text-input/images/text-input-width-do.png b/src/pages/components/text-input/images/text-input-width-do.png
new file mode 100644
index 00000000000..b1cedc02aa1
Binary files /dev/null and b/src/pages/components/text-input/images/text-input-width-do.png differ
diff --git a/src/pages/components/text-input/images/text-input-width-dont.png b/src/pages/components/text-input/images/text-input-width-dont.png
new file mode 100644
index 00000000000..4ac0b6ec460
Binary files /dev/null and b/src/pages/components/text-input/images/text-input-width-dont.png differ
diff --git a/src/pages/components/text-input/usage.mdx b/src/pages/components/text-input/usage.mdx
index 305d988e8cb..c91f5767bc7 100755
--- a/src/pages/components/text-input/usage.mdx
+++ b/src/pages/components/text-input/usage.mdx
@@ -8,8 +8,8 @@ tabs: ['Usage', 'Style', 'Code', 'Accessibility']
-Text inputs enable the user to interact with and input content and data. This
-component can be used for long and short form entries.
+Text inputs enable users to enter free-form text data. You can use them for long
+and short-form entries.
@@ -19,20 +19,40 @@ component can be used for long and short form entries.
Live demo
Formatting
Content
+Universal behaviors
+Text input
+Text area
+References
Feedback
## Overview
-There are instances, sometimes in the same form, where you need users to enter
-both short and long form content. Allow the size of the text input box to
-reflect the length of the content you expect the user to enter.
+Text inputs enable users to enter free-form text data. The type of text field
+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.
-| Variant | Purpose |
-| ---------- | --------------------------------------------------------------------------------- |
-| Text input | When the expected user input is a single line of text, as opposed to a paragraph. |
-| Text area | When the expected user input is more than one sentence. |
+#### When to use
+
+- A user needs to input unique information that cannot be predicted with a
+ preset of options.
+- A user needs to input memorable data that can be entered more quickly in a
+ free-hand format versus a more complex control.
+
+#### When not to use
+
+- If a user can only enter an option from a predefined list then avoid using a
+ free-form text input as it is likely to result in an error. Consider using a
+ selection control such as a dropdown, select, or radio button group instead.
+
+### Variants
+
+| Variant | Purpose |
+| ------------------------------------------------------ | ------------------------------------------------------------------------------------- |
+| [Text input](/components/text-input/usage/#text-input) | When the expected user input is a single line of text. |
+| [Text area](/components/text-input/usage/#text-area) | When the expected user input is more than a few words that could span multiple lines. |
## Live demo
@@ -132,99 +152,365 @@ reflect the length of the content you expect the user to enter.
## Formatting
+### Anatomy
+
+
+
+
+
+
+
+
+
+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
+ 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.
+
+### Sizing
+
+#### Text 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
+consistent field height when pairing form components on the same page.
+
+| Size | Height (px/rem) | Use case |
+| ----------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Small (sm) | 32 / 2 | Use when space is constricted or when placing a text 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 text input is placed by itself on a page. |
+
+
+
+
+
+
+
+
+
+#### Text area height
+
+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.
+
+
+
+
+
+
+
+
+
+#### Widths
+
+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.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+### Alignment
+
+Labels and field containers should vertically align to the grid and with other
+form components on a page.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+## Content
+
+### Main elements
+
+#### Labels
+
+Effective labeling helps users understand what information to enter into a text
+input. Text fields should always have a label. There are rare instances were the
+context of an input negates the need for a visible label but we advise you
+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
+
+Optional helper text is pertinent information that assists the user in correctly
+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.
+
+#### 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.
+
+- Use sentence-style capitalization, and in most cases, write the text as a
+ direct statement without punctuation.
+- Placeholder text is not required and by default not shown in text input
+ fields.
+- 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
+
+If a user's content is unexpectedly too long for the single line of a text input
+then the value content can horizontally scroll inside the field container when
+moving the cursor from one end of the value to the other.
+
+#### Overflow in a text area
+
+If a user's content exceeds the vertical space of the variable text area then a
+user can either expand the field container using the resize handle or they can
+vertically scroll the content inside the set field container.
+
+### Further guidance
+
+For further content guidance, see Carbon's
+[content guidelines](/guidelines/content/overview).
+
+## Universal behaviors
+
+The behaviors listed in this section are universal across all variants. For
+behaviors that are unique to each variant, see each of the component variant
+sections below.
+
+### States
+
+| State | When to use |
+| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| _Enabled_ | When a text 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 text input field can contain no content, placeholder text, or user generate content. |
+| _Active_ | When a user is actively typing content into the field. |
+| _Focus_ | When a user `tabs` to or clicks on the text input, it becomes focused, indicating the user has successfully navigated to the component. |
+| _Error_ | When the user input is invalid or a required text 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 text 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 text input has not yet fully loaded. |
+| _Read-only_ | _Coming soon!_ |
+
+
+
+
+
+
+
+
+
+### Validation
+
+Real-time validation helps streamline the process and keep data clean when the
+user fills out forms. Otherwise, validate the text input data when the user
+submits the associated form. For complete guidance on error and validation, see
+the [form pattern](https://carbondesignsystem.com/patterns/forms-pattern/).
+
+#### 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.
+
+
+
+
+
+
+
+
+
### 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
+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.
-### Validation and errors
+### Required vs. 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).
+
+
+
+
+
-Real time validation helps to streamline the process and keep data clean when
-the user is filling out forms. For full guidelines, refer to the
-[forms](/components/form/usage) usage page.
+
+
+
+
+
+
+
+
+### Interactions
+
+#### Mouse
+
+Users can activate a text input by clicking on the field container. A separate
+click is required to activate any additional actions associated with the text
+input such as a tooltip or password visibility toggle.
-
+
-### Character count
+#### Keyboard
+
+For additional keyboard interactions, see the
+[accessibility tab](/components/text-input/accessibility).
+
+| Key | Interaction |
+| ------------------------------------- | -------------------------------------------------------------------------------------- |
+| _Tab_ | Brings focus to the text input. |
+| _Enter_ or _Space_ | Opens any associated actions added to the input, such as a password visibility toggle. |
+| _Esc_ | Closes any associated actions added to the input. |
+| _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 fields and text areas may have a character limit and counter. Use the
-character limit and counter to let users know how long their entry can be before
-they begin typing.
+## Text input
-While useful for data collection, character count is not an intuitive way to
-communicate content length to users. Character count allows a user to understand
-an input error if they surpass the character limit.
+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.
-
+
-## Content
-
-### Labels
+### Password input
-Effective form labeling helps users understand what information to enter into a
-text input. Using placeholder text in lieu of a label is sometimes employed as a
-space-saving method. However, this is not recommended because it hides context
-and presents accessibility issues.
+Password input is a sub-variant of text input. It is used to collect private
+data and will hide the characters as a user enters them. A user can choose to
+toggle on the character visibility by clicking the view icon on the far right of
+the input field. When using a password input be sure to provide detailed helper
+text listing any requirements related to the data format, such as types of
+characters allowed or date structure.
-
+
-#### Accessibility best practices for labels
+## Text area
-- Labels must be visible when an input gets focus.
-- 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.
+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.
+
+
+
+
+
-### Placeholder text
+
+
-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. Use sentence-style capitalization, and in most
-cases, write the text as a direct statement without punctuation.
+### 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.
-
+
-### Helper text
+### Character counter
-Helper text is pertinent information that assists the user in completing a
-field. Helper text is always available when the input is focused and appears
-underneath the label. Use sentence-style capitalization, and in most cases,
-write the text as full sentences with punctuation.
+A character counter can be added to text area to indicate both the number of
+characters being entered and the total number of characters allowed. Once the
+max number of characters is reached the text area should prevent the user from
+entering any additional character and provide messaging to the user that a limit
+has been met.
-
+
+## References
+
+- Katie Sherwin,
+ [Placeholders in Form Fields Are Harmful](https://www.nngroup.com/articles/form-design-placeholders/)
+ (Nielsen Norman Group, 2018)
+
## Feedback
Help us improve this component by providing feedback, asking questions, and
diff --git a/src/pages/components/tree-view/accessibility.mdx b/src/pages/components/tree-view/accessibility.mdx
index e92ab5b22ca..853435deff4 100644
--- a/src/pages/components/tree-view/accessibility.mdx
+++ b/src/pages/components/tree-view/accessibility.mdx
@@ -15,7 +15,7 @@ standard accordion component, Carbon already incorporates accessibility.
-This page is underdevelopment. Please check back later updates.
+This page is underdevelopment. Please check back later for updates.