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: Phone
| |
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
- Seller identifier in the marketplace
- Performance analysis of all VTEX Shipping Network carriers
| - Schedule for Updates
- Seller identifier in the Marketplace
- 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: Frequency Description: Schedule for updates Label: Privacy policy Description: Declaration of the parties that manage customer data Label: Publish date Description: Day in which the changes made will appear in the store
| Label: Seller ID Description: This is the seller identifier in the marketplace Label: Frequency Description: Frequency is the schedule for updates Label: Privacy policy Description: Fill a declaration of which parties manage customer data 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: Frequency Description: Defines when updates will be published Label: Privacy policy Description: Appears to customers in the store Label: Publish date Description: Considers the time zone where the store is located
| Label: Seller ID Description: When you fill a value in this field, it appears to customers in the store Label: Frequency Description: Frequency defines when updates will be published Label: Privacy policy Description: This appears to customers in the store 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: Frequency Description: 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: Publish date Description: Day in which the changes made will be published considering the time zone where the store is located
| Label: Seller ID Description: Fill the seller identifier in the marketplace 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: Privacy policy Description: Declaration of which parties manage customer data that will appear to customers in the store Label: Publish date Description: When should the changes made be published, considering the time zone where the store is located?
|