@shopify/polaris
Version:
Shopify’s product component library
177 lines (116 loc) • 4.28 kB
Markdown
---
name: Description list
category: Lists and tables
platforms:
- android
- ios
- web
keywords:
- DescriptionList
- glossary
- description
- list terms
- list and define terms
- item lists
- text lists
- list of terms
- term explaination
- android
- ios
---
# Description list
Description lists are a way to organize and explain related information.
They’re particularly useful when you need to list and define terms such as in a
glossary.
---
## Best practices
Description lists should:
- Contain terms and associated explanations, or descriptions for each term.
- Provide information that isn’t action-oriented.
- Not be an excuse for using unnecessarily complicated or jargon-filled
language. Generally, if merchants need a description list to understand the
language in Shopify, we should look for opportunities to simplify the language.
- Not be used to upsell merchants on a feature or service.
---
## Content guidelines
### Terms
Terms should be:
- Written in sentence case (the first word capitalized, the rest lowercase)
<!-- usagelist -->
#### Do
- Discount code
#### Don’t
- Discount Code
<!-- end -->
### Term description
Terms descriptions should be:
- Directly related to the term they’re describing
<!-- usagelist -->
#### Do
- Discount code: A series of numbers and/or letters that an online shopper may enter at checkout
to get a discount or special offer.
#### Don’t
- Discount code: Having a sale on your store is a great way to sell products quickly.
<!-- end -->
- Written to describe the merchant benefit or utility
- No more than one or two short sentences in length
- Written in sentence case with all appropriate punctuation, including ending
each sentence with a period
- Conversational by using articles (the, a, an)
- Written using plain language
<!-- usagelist -->
#### Do
- Abandoned checkout: The details of a checkout that was started but not completed, including the
products added and the customer’s details.
#### Don’t
- Abandoned checkout: Details of products added to checkout but not purchased
<!-- end -->
---
## Examples
### Default description list
Use when you need to present merchants with a list of items or terms alongside descriptions and explanations.
```jsx
<DescriptionList
items={[
{
term: 'Logistics',
description:
'The management of products or other resources as they travel between a point of origin and a destination.',
},
{
term: 'Sole proprietorship',
description:
'A business structure where a single individual both owns and runs the company.',
},
{
term: 'Discount code',
description:
'A series of numbers and/or letters that an online shopper may enter at checkout to get a discount or special offer.',
},
]}
/>
```
<!-- content-for: android -->
<!-- /content-for -->
<!-- content-for: ios -->
<!-- /content-for -->
---
## Related components
- To create a list of actions or navigation, [use the action list component](https://polaris.shopify.com/components/actions/action-list).
---
## Accessibility
<!-- content-for: android -->
See Material Design and development documentation about accessibility for Android:
- [Accessible design on Android](https://material.io/design/usability/accessibility.html)
- [Accessible development on Android](https://developer.android.com/guide/topics/ui/accessibility/)
<!-- /content-for -->
<!-- content-for: ios -->
See Apple’s Human Interface Guidelines and API documentation about accessibility for iOS:
- [Accessible design on iOS](https://developer.apple.com/design/human-interface-guidelines/ios/app-architecture/accessibility/)
- [Accessible development on iOS](https://developer.apple.com/accessibility/ios/)
<!-- /content-for -->
<!-- content-for: web -->
The description list component produces a description list wrapper (`<dl>`), terms (`<dt>`), and definitions (`<dd>`) to convey the relationships between the list items to assistive technology users.
<!-- /content-for -->