Descriptions use a single sentence to clarify or explain complex information or tasks to the user. This pattern is frequently found in form fields and help-related components.
General
Include a description only when additional information is actually necessary.
| Do ✅ | Don't ❌ |
|---|---|
| Label: Category | Label: Category Description: Complete the category |
| Label: Phone | Label: Phone Description: Example: +1-576-158-4127 |
Keep it as short as possible while still being descriptive enough.
| Do ✅ | Don't ❌ |
|---|---|
| Volume of sessions in the intermediate stages of the purchase flow | This chart allows you to track the volume of sessions in the intermediate stages of the purchase flow and view opportunities for optimizing the conversion rate |
Use sentence case, but capitalize proper nouns.
| Do ✅ | Don't ❌ |
|---|---|
| Schedule for updates | Schedule for Updates |
| Seller identifier in the marketplace | Seller identifier in the Marketplace |
| Performance analysis of all VTEX Shipping Network carriers | Performance analysis of all VTEX shipping network carriers |
Avoid punctuation such as commas, and don't use periods or question marks.
| Do ✅ | Don't ❌ |
|---|---|
| Day in which the changes made will be published considering the time zone where the store is located | Considering the time zone where the store is located, the day in which the changes made will be published. |
Don't include redundant words.
| Do ✅ | Don't ❌ |
|---|---|
| • Label: Frequency Description: Schedule for updates | • Label: Frequency Description: Frequency for updates |
Don't use a marketing tone of voice or explain benefits.
| Do ✅ | Don't ❌ |
|---|---|
| Volume of sessions in the intermediate stages of the purchase flow | Track the volume of sessions in the intermediate stages of the purchase flow to optimize your conversion rate |
Specific
When explaining a label, write as if completing the sentence "This is the…". Start with a noun followed by additional information, such as conditions and definitions.
| Do ✅ | Don't ❌ |
|---|---|
| Label: Seller ID Description: Seller identifier in the marketplace | • Label: Seller ID Description: This is the seller identifier in the marketplace |
| Label: Frequency Description: Schedule for updates | Label: Frequency Description: Frequency is the schedule for updates |
| Label: Privacy policy Description: Declaration of the parties that manage customer data | Label: Privacy policy Description: Fill a declaration of which parties manage customer data |
| Label: Publish date Description: Day in which the changes made will appear in the store | Label: Publish date Description: When should the changes appear in the store? |
When explaining how information given in a form field will be used, write as if completing the sentence "When you enter a value in this field, it…" and start with a verb in the simple present tense.
| Do ✅ | Don't ❌ |
|---|---|
| • Label: Seller ID Description: Appears to customers in the store | • Label: Seller ID Description: When you fill a value in this field, it appears to customers in the store |
| • Label: Frequency Description: Defines when updates will be published | • Label: Frequency Description: Frequency defines when updates will be published |
| • Label: Privacy policy Description: Appears to customers in the store | • Label: Privacy policy Description: This appears to customers in the store |
| • Label: Publish date Description: Considers the time zone where the store is located | • Label: Publish date Description: Consider the time zone where the store is located |
When explaining both the label of a form field and how its value will be used, combine the two sentences described in the previous topics and adapt them if necessary.
| Do ✅ | Don't ❌ |
|---|---|
| • Label: Seller ID Description: Seller identifier in the marketplace that appears to customers in the store | • Label: Seller ID Description: Fill the seller identifier in the marketplace that will appear to customers in the store |
| • Label: Frequency Description: Schedule for updates that defines when they will be published | • Label: Frequency Description: Frequency is the schedule for updates that defines when they will be published |
| • Label: Privacy policy Description: Declaration of which parties manage customer data that will appear to customers in the store | • Label: Frequency Description: Frequency is the schedule for updates that defines when they will be published |
| • Label: Publish date Description: Day in which the changes made will be published considering the time zone where the store is located | • Label: Publish date Description: When should the changes made be published, considering the time zone where the store is located? |