Lists and tables

7 min read

Tables and lists present structured content, but sometimes, it’s unclear when to use one over the other. Here are some rules you can follow when creating them:

Lists

Lists help organize the content and facilitate understanding. When you need to roll items that do not configure a sequence of steps, it could be helpful to format it as a list. Use lists to present a series of single items or steps. For example, a bulleted list can outline product features, and a numbered list can guide users through software installation steps.

See the lists guidelines for more information.

Tables

Use tables to organize data with multiple attributes. For example, a table can compare installation requirements for different operating systems, showing the minimum and recommended specifications.

See the tables guidelines for more information.

General rules

When a list or table item contains a colon, the first word after it must be capitalized.

Do ✅	Don't ❌
Authorized reservation: After the order is placed. Confirmed reservation: After the order is placed.	Authorized reservation: after the order is placed. Confirmed reservation: after payment is approved.

Make sure the list or table structure is consistent. Start each item with the same verb or noun form.

Do ✅	Don't ❌
Control search results using specific conditions. Preview how search results will be displayed to customers while navigating the store. Change the order of the items listed in search results.	Controls search results using specific conditions. You can change the order of the items listed in search results.
Indicates the type of editing used in the merchandising rule. Enables or disables a merchandising rule. Type of editing used in the merchandising rule. Option to enable or disable a merchandising rule.	Option that enables or disables a merchandising rule.

When a list or a word in the table is not a complete sentence, don't use punctuation.

Do ✅	Don't ❌
Before cloning your store's repository, ensure that you have the following tools on your machine: Node.js Yarn Git Visual Studio Code	Before cloning your store's repository, ensure that you have the following tools on your machine: Node.js. Yarn. Git. Visual Studio Code.

Lists

There are two types of lists:

Ordered: Presented in a specific sequence, typically numbered. Use for sequential steps (e.g., installation instructions):
```
1. Go to the VTEX Admin and access **Storefront > Headless CMS**.
2. Click **Create a new project**.
3. …
```
Unordered: Presented without a specific sequence, typically bulleted. Use for groups of items without a specific order (e.g., required tools):
```
Before cloning your store repository, ensure that you have the following tools on your machine:
- Node.js
- Yarn
- Git
```

Ordered list

Use a numbered list for sequential steps.

Do ✅	Don't ❌
Archiving a project disables the API and access to the content within the project. To archive a project, follow the steps below: 1. Go to Storefront > Projects. 2. Choose the project you want to archive and click Settings (⚙️) to open a modal. 3. Click `Archive project` on the General page. A pop-up message will appear to confirm that you want to archive the project.	Archiving a project disables the API and access to the content within the project. To archive a project, follow the steps below: Go to Storefront > Projects. Choose the project you want to archive and click Settings (⚙️) to open a modal. Click `Archive project` on the General page. A pop-up message will appear to confirm that you want to archive the project.
The promotions applied to the cart follow the order below: 1. Percentage 2. Nominal 3. Buy Together	The promotions applied to the cart follow the order below: Percentage Nominal Buy Together

Write an introduction to the list providing context for the user. Use a colon at the end of the sentence if the list follows immediately after.

Do ✅	Don't ❌
Follow the steps below to add a new collection: 1. In the Admin, click Catalog. 2. Click Collections.	Add a new collection: 1. In the Admin, click Catalog. 2. Click Collections.

Unordered list

Use a bulleted list of items with a common theme that doesn’t require a specific order.

Do ✅	Don't ❌
The tool has features such as: Autocomplete: Provides search and product suggestions based on the shopper's context. Customizable filters: Help in the process of finding the desired product. Dynamic results: Uses historical data on clicks and orders to improve the search results dynamically. Autocorrect: Handles typos and spelling mistakes, such as plural and singular variations and gender variations in words that share the same radical. Customization: Offers customizable features such as Relevance, Synonyms, and Merchandising Rules, which make it possible to improve the customer experience and meet the store's business needs.	The card Opens a modal that displays three tabs: Autocomplete: Provides search and product suggestions based on the shopper's context. Customizable filters: Help in the process of finding the desired product. Dynamic results: Uses historical data on clicks and orders to improve the search results dynamically. Autocorrect: Handles typos and spelling mistakes, such as plural and singular variations and gender variations in words that share the same radical. Customization: Offers customizable features such as Relevance, Synonyms, and Merchandising Rules, which make it possible to improve the customer experience and meet the store's business needs.

Do ✅

Don't ❌

The tool has features such as:

Autocomplete: Provides search and product suggestions based on the shopper's context.
Customizable filters: Help in the process of finding the desired product.
Dynamic results: Uses historical data on clicks and orders to improve the search results dynamically.
Autocorrect: Handles typos and spelling mistakes, such as plural and singular variations and gender variations in words that share the same radical.
Customization: Offers customizable features such as Relevance, Synonyms, and Merchandising Rules, which make it possible to improve the customer experience and meet the store's business needs.

The card Opens a modal that displays three tabs:

Autocomplete: Provides search and product suggestions based on the shopper's context.
Customizable filters: Help in the process of finding the desired product.
Dynamic results: Uses historical data on clicks and orders to improve the search results dynamically.
Autocorrect: Handles typos and spelling mistakes, such as plural and singular variations and gender variations in words that share the same radical.
Customization: Offers customizable features such as Relevance, Synonyms, and Merchandising Rules, which make it possible to improve the customer experience and meet the store's business needs.

For bullet list items consisting of complete sentences, use a period at the end of each sentence.

Do ✅	Don't ❌
Promotion competition occurs in the following situations: Promotions with the same type of discount. More than one promotion applied to the same item.	Promotion competition occurs in the following situations: Promotions with the same type of discount More than one promotion applied to the same item

Use a period if there are more elements, such as a callout, code example, or an image, between the introduction and the list.

Do ✅

When you send the request, be sure to include the following fields.

{ 
  "skuId": {sku-identification-number}", 
  "quantity": "{product-identification-number}", 
  "price": "{sku-price}"
}

skuId: SKU identification code corresponding to the item.
quantity: Item quantity.
price: Item price in cents.

Don't ❌

When you send the request, be sure to include the following fields:

{ 
   "skuId": {sku-identification-number}", 
   "quantity": "{product-identification-number}", 
   "price": "{sku-price}"
}

skuId: SKU identification code corresponding to the item.
quantity: Item quantity.
price: Item price in cents.

Tables

Use tables for items with three or more related data points.

Do ✅

When creating a field, the following types are displayed:

Field type	Description
Auto Increment	Stores integers and is automatically incremented, which means that for each new record, this field receives the value of the previous record + 1.
Boolean	Stores true or false information, which means it will always be completed as `true` or `false`.
CEP	Stores a CEP (postal code in Brazil).

Don’t ❌

When creating a field, the following types are displayed:

Field type
Auto Increment
Boolean
CEP

Write an introductory sentence for the table and refer to the table's position using phrases like the following table or the preceding table.

Do ✅

FastStore is a toolkit based on Jamstack that helps developers build high-performance stores. In the following table, see its main aspects:

Aspect	Description
Performance	Ensures fast-loading stores and provides a good user experience, focusing on achieving high scores in tests like Lighthouse and Web Vitals.
Stability	Built to be stable and avoid crashes, so your store doesn't lose sales due to provider issues.
Analytics/SEO	Works with analytics tools to understand store customers and with SEO tools to improve store visibility in search results.

Don’t ❌

Aspect	Description
Performance	Ensures fast-loading stores and provides a good user experience, focusing on achieving high scores in tests like Lighthouse and Web Vitals.
Stability	Built to be stable and avoid crashes, so your store doesn't lose sales due to provider issues.
Analytics/SEO	Works with analytics tools to understand store customers and with SEO tools to improve store visibility in search results.

The introductory sentence must be a complete sentence, and it can end with a colon or a period. Usually, a colon if it immediately precedes the table, and usually a period if there's more content (e.g., a callout) between the introduction and the table.