From 973cdb2cd343c424c654d73e56c6660d3fa8e3fc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Connor=20B=C3=A4r?= Date: Mon, 21 Oct 2024 19:53:30 +0200 Subject: [PATCH] Revise PhoneNumberInput docs --- .../circuit-ui/components/Input/Input.mdx | 27 +++++------------ .../PhoneNumberInput/PhoneNumberInput.mdx | 30 ++++--------------- 2 files changed, 13 insertions(+), 44 deletions(-) diff --git a/packages/circuit-ui/components/Input/Input.mdx b/packages/circuit-ui/components/Input/Input.mdx index 1897955b3c..b0a2eca68f 100644 --- a/packages/circuit-ui/components/Input/Input.mdx +++ b/packages/circuit-ui/components/Input/Input.mdx @@ -7,26 +7,21 @@ import * as Stories from './Input.stories'; -A text field is an input field for inserting short text and numbers. It has -multiple functions and supports multiple character types/formats. +A text field is an input field for inserting short text and numbers. ## When to use it -When you need short textual information from the user such as email address, -first name, phone number, street name, etc. +When you need short textual information from the user such as email address, first name, phone number, street name, etc. ## Usage guidelines - **Do** always accompany an input field with a visible label. -- **Do** use one input per row, unless two fields are closely interrelated - (e.g. first and last name). -- **Do not** use input fields for requiring longer textual information from the - user. -- **Do not** communicate that an input field is required on the label or the placeholder. - We assume that everything is required for the user unless explicitly said so. +- **Do** use one input per row, unless two fields are closely interrelated (e.g. first and last name). +- **Do not** use input fields for requiring longer textual information from the user. +- **Do not** communicate that an input field is required on the label or the placeholder. We assume that everything is required for the user unless explicitly said so. - **Do not** mark required fields with asterisks. ## Validations @@ -63,19 +58,11 @@ field should only be open for editing again if a button is clicked. ## Placeholder -An input field must always have a placeholder, which is a short example of the -information required that helps the user to understand what kind of information -is needed. (For instance, an Address Field could have a placeholder: -Grunerstrasse 13) - -### When to use it - -Always provide a placeholder for text input fields. +An input field must always have a placeholder, which is a short example of the information required that helps the user to understand what kind of information is needed. (For instance, an Address Field could have a placeholder: "Grunerstrasse 13") ### Usage guidelines - **Do** make the placeholder succinct (up to 3-4 words). - **Do** make the placeholder contextual to the language and market. - **Do not** repeat the same content in the placeholder as the label. -- **Do not** communicate that a field is optional in the placeholder, you - should do it in the label. +- **Do not** communicate that a field is optional in the placeholder, you should do it in the label. diff --git a/packages/circuit-ui/components/PhoneNumberInput/PhoneNumberInput.mdx b/packages/circuit-ui/components/PhoneNumberInput/PhoneNumberInput.mdx index 7dc7f19903..51eace5c5f 100644 --- a/packages/circuit-ui/components/PhoneNumberInput/PhoneNumberInput.mdx +++ b/packages/circuit-ui/components/PhoneNumberInput/PhoneNumberInput.mdx @@ -12,18 +12,11 @@ The PhoneNumberInput component provides a straightforward way for users to type -## When to use it +## Usage When you need to collect a phone number from the user. This could be for contact information, two-factor authentication, or other purposes where a phone number is required. The component allows the user to select their country code, and normalizes the input to the [E.164 format](https://www.itu.int/rec/t-rec-e.164/en). -## Usage guidelines - -- **Do** always accompany the `PhoneNumberInput` field with a visible label. This helps users understand what information is required. -- **Do not** use `PhoneNumberInput` for non-phone number data. It is specifically designed for phone number input and includes specific formatting and validation for phone numbers. -- **Do not** communicate that a `PhoneNumberInput` field is required on the label or the placeholder. We assume that everything is required for the user unless explicitly stated otherwise. -- **Do not** mark required fields with asterisks. Instead, use the `required` prop to indicate that the field is required. - ## Validations Use the `validationHint` prop to communicate the expected response to users. @@ -39,41 +32,30 @@ When the user is recommended to change the value, but can proceed without doing ### Valid -When the user is reassured that the value is valid. Use sparingly, as the `PhoneNumberInput` component does not validate that the number is actually in service. +When the user is reassured that the value is valid. Use sparingly, as the PhoneNumberInput component does not validate that the number is actually in service. ## Readonly -The `PhoneNumberInput` component supports a Readonly state. Use the `readOnly` prop to indicate that the field is not currently editable. -The state can be applied to the entire component or only to a specific field, e.g. in the example below is used to indicate that only the country code is readonly - -- **Do** use the `readOnly` prop to communicate to the user that the phone number input is not currently editable. This can be useful in situations where the user needs to view but not edit the phone number, such as in a summary or review screen. -- **Do not** use the `readOnly` prop to indicate that the field is optional or not required. The `readOnly` prop only changes the editability of the field, not its requirement status. +Use the `readOnly` prop to indicate that the field is not currently editable. This can be useful in situations where the user needs to view but not edit the phone number, such as in a summary or review screen. The state can be applied to the entire component or only to a specific field, e.g. in the example below is used to indicate that only the country code is read-only. ## Optional -The `PhoneNumberInput` component supports optional fields. Use the `optionalLabel` prop to indicate that the field is optional. This label is only displayed when the `required` prop is falsy. - -- **Do** use the `optionalLabel` prop to communicate to the user that the phone number input is optional. This can help reduce the cognitive load for the user by clearly indicating which fields are required and which are not. -- **Do not** use the `optionalLabel` prop to communicate other information. It should only be used to indicate that the field is optional. +Use the `optionalLabel` prop to indicate that the field is optional. This can help reduce the cognitive load for the user by clearly indicating which fields are required and which are not. This label is only displayed when the `required` prop is falsy. ## Disabled -You should use only when its a critical information from the user that we -already have or need and we do not want the user to edit it easily. A disabled -field should only be open for editing again if a user event is triggered. +You should use only when its a critical information from the user that we already have or need and we do not want the user to edit it easily. A disabled field should only be open for editing again if a user event is triggered. ## With Prefix -The `PhoneNumberInput` component supports prefixes. Use the `renderPrefix` prop to add a small prefix to the country code selected input field. This can be useful for adding a flag icon, which can help the user recognize the selected country. - -- **Do** use the `renderPrefix` prop to provide relevant visual cues that help guide the user's input. +Use the `renderPrefix` prop to add a small prefix to the country code selected input field. This can be useful for adding a flag icon, which can help the user recognize the selected country.