microsoft · daviddossett · Feb 7, 2022 · Jan 20, 2022 · Jan 21, 2022 · Jan 21, 2022
diff --git a/docs/assets/images/badge-do-1.png b/docs/assets/images/badge-do-1.png
diff --git a/docs/assets/images/badge-do-2.png b/docs/assets/images/badge-do-2.png
diff --git a/docs/assets/images/badge-do-3.png b/docs/assets/images/badge-do-3.png
diff --git a/docs/assets/images/badge-dont-1.png b/docs/assets/images/badge-dont-1.png
diff --git a/docs/assets/images/badge-dont-2.png b/docs/assets/images/badge-dont-2.png
diff --git a/docs/assets/images/badge-dont-3.png b/docs/assets/images/badge-dont-3.png
diff --git a/docs/assets/images/badge-hero.png b/docs/assets/images/badge-hero.png
diff --git a/docs/assets/images/button-do-1.png b/docs/assets/images/button-do-1.png
diff --git a/docs/assets/images/button-do-2.png b/docs/assets/images/button-do-2.png
diff --git a/docs/assets/images/button-do-3.png b/docs/assets/images/button-do-3.png
diff --git a/docs/assets/images/button-do-4.png b/docs/assets/images/button-do-4.png
diff --git a/docs/assets/images/button-do-5.png b/docs/assets/images/button-do-5.png
diff --git a/docs/assets/images/button-dont-1.png b/docs/assets/images/button-dont-1.png
diff --git a/docs/assets/images/button-dont-2.png b/docs/assets/images/button-dont-2.png
diff --git a/docs/assets/images/button-dont-3.png b/docs/assets/images/button-dont-3.png
diff --git a/docs/assets/images/button-dont-4.png b/docs/assets/images/button-dont-4.png
diff --git a/docs/assets/images/button-dont-5.png b/docs/assets/images/button-dont-5.png
diff --git a/docs/assets/images/button-hero.png b/docs/assets/images/button-hero.png
diff --git a/docs/assets/images/button-types-icon.png b/docs/assets/images/button-types-icon.png
diff --git a/docs/assets/images/button-types-primary.png b/docs/assets/images/button-types-primary.png
diff --git a/docs/assets/images/button-types-secondary.png b/docs/assets/images/button-types-secondary.png
diff --git a/docs/assets/images/checkbox-do-1.png b/docs/assets/images/checkbox-do-1.png
diff --git a/docs/assets/images/checkbox-do-2.png b/docs/assets/images/checkbox-do-2.png
diff --git a/docs/assets/images/checkbox-do-3.png b/docs/assets/images/checkbox-do-3.png
diff --git a/docs/assets/images/checkbox-do-4.png b/docs/assets/images/checkbox-do-4.png
diff --git a/docs/assets/images/checkbox-dont-1.png b/docs/assets/images/checkbox-dont-1.png
diff --git a/docs/assets/images/checkbox-dont-2.png b/docs/assets/images/checkbox-dont-2.png
diff --git a/docs/assets/images/checkbox-dont-3.png b/docs/assets/images/checkbox-dont-3.png
diff --git a/docs/assets/images/checkbox-dont-4.png b/docs/assets/images/checkbox-dont-4.png
diff --git a/docs/assets/images/checkbox-hero.png b/docs/assets/images/checkbox-hero.png
diff --git a/docs/assets/images/data-grid-do-1.png b/docs/assets/images/data-grid-do-1.png
diff --git a/docs/assets/images/data-grid-do-2.png b/docs/assets/images/data-grid-do-2.png
diff --git a/docs/assets/images/data-grid-dont-1.png b/docs/assets/images/data-grid-dont-1.png
diff --git a/docs/assets/images/data-grid-dont-2.png b/docs/assets/images/data-grid-dont-2.png
diff --git a/docs/assets/images/data-grid-hero.png b/docs/assets/images/data-grid-hero.png
diff --git a/docs/assets/images/divider-do-1.png b/docs/assets/images/divider-do-1.png
diff --git a/docs/assets/images/divider-do-2.png b/docs/assets/images/divider-do-2.png
diff --git a/docs/assets/images/divider-dont-1.png b/docs/assets/images/divider-dont-1.png
diff --git a/docs/assets/images/divider-dont-2.png b/docs/assets/images/divider-dont-2.png
diff --git a/docs/assets/images/divider-hero.png b/docs/assets/images/divider-hero.png
diff --git a/docs/assets/images/dropdown-do-1.png b/docs/assets/images/dropdown-do-1.png
diff --git a/docs/assets/images/dropdown-do-2.png b/docs/assets/images/dropdown-do-2.png
diff --git a/docs/assets/images/dropdown-do-3.png b/docs/assets/images/dropdown-do-3.png
diff --git a/docs/assets/images/dropdown-dont-1.png b/docs/assets/images/dropdown-dont-1.png
diff --git a/docs/assets/images/dropdown-dont-2.png b/docs/assets/images/dropdown-dont-2.png
diff --git a/docs/assets/images/dropdown-dont-3.png b/docs/assets/images/dropdown-dont-3.png
diff --git a/docs/assets/images/dropdown-hero.png b/docs/assets/images/dropdown-hero.png
diff --git a/docs/assets/images/img-placeholder.png b/docs/assets/images/img-placeholder.png
diff --git a/docs/assets/images/link-do-1.png b/docs/assets/images/link-do-1.png
diff --git a/docs/assets/images/link-do-2.png b/docs/assets/images/link-do-2.png
diff --git a/docs/assets/images/link-dont-1.png b/docs/assets/images/link-dont-1.png
diff --git a/docs/assets/images/link-dont-2.png b/docs/assets/images/link-dont-2.png
diff --git a/docs/assets/images/link-hero.png b/docs/assets/images/link-hero.png
diff --git a/docs/assets/images/option-hero.png b/docs/assets/images/option-hero.png
diff --git a/docs/assets/images/panels-do-1.png b/docs/assets/images/panels-do-1.png
diff --git a/docs/assets/images/panels-do-2.png b/docs/assets/images/panels-do-2.png
diff --git a/docs/assets/images/panels-do-3.png b/docs/assets/images/panels-do-3.png
diff --git a/docs/assets/images/panels-dont-1.png b/docs/assets/images/panels-dont-1.png
diff --git a/docs/assets/images/panels-dont-2.png b/docs/assets/images/panels-dont-2.png
diff --git a/docs/assets/images/panels-dont-3.png b/docs/assets/images/panels-dont-3.png
diff --git a/docs/assets/images/panels-hero.png b/docs/assets/images/panels-hero.png
diff --git a/docs/assets/images/progress-ring-do-1.png b/docs/assets/images/progress-ring-do-1.png
diff --git a/docs/assets/images/progress-ring-do-2.png b/docs/assets/images/progress-ring-do-2.png
diff --git a/docs/assets/images/progress-ring-dont-1.png b/docs/assets/images/progress-ring-dont-1.png
diff --git a/docs/assets/images/progress-ring-dont-2.png b/docs/assets/images/progress-ring-dont-2.png
diff --git a/docs/assets/images/progress-ring-hero.png b/docs/assets/images/progress-ring-hero.png
diff --git a/docs/assets/images/radio-do-1.png b/docs/assets/images/radio-do-1.png
diff --git a/docs/assets/images/radio-do-2.png b/docs/assets/images/radio-do-2.png
diff --git a/docs/assets/images/radio-do-3.png b/docs/assets/images/radio-do-3.png
diff --git a/docs/assets/images/radio-dont-1.png b/docs/assets/images/radio-dont-1.png
diff --git a/docs/assets/images/radio-dont-2.png b/docs/assets/images/radio-dont-2.png
diff --git a/docs/assets/images/radio-dont-3.png b/docs/assets/images/radio-dont-3.png
diff --git a/docs/assets/images/radio-group-hero.png b/docs/assets/images/radio-group-hero.png
diff --git a/docs/assets/images/radio-hero.png b/docs/assets/images/radio-hero.png
diff --git a/docs/assets/images/tag-do-1.png b/docs/assets/images/tag-do-1.png
diff --git a/docs/assets/images/tag-dont-1.png b/docs/assets/images/tag-dont-1.png
diff --git a/docs/assets/images/tag-hero.png b/docs/assets/images/tag-hero.png
diff --git a/docs/assets/images/text-area-do-1.png b/docs/assets/images/text-area-do-1.png
diff --git a/docs/assets/images/text-area-do-2.png b/docs/assets/images/text-area-do-2.png
diff --git a/docs/assets/images/text-area-do-3.png b/docs/assets/images/text-area-do-3.png
diff --git a/docs/assets/images/text-area-dont-1.png b/docs/assets/images/text-area-dont-1.png
diff --git a/docs/assets/images/text-area-dont-2.png b/docs/assets/images/text-area-dont-2.png
diff --git a/docs/assets/images/text-area-dont-3.png b/docs/assets/images/text-area-dont-3.png
diff --git a/docs/assets/images/text-area-hero.png b/docs/assets/images/text-area-hero.png
diff --git a/docs/assets/images/text-field-do-1.png b/docs/assets/images/text-field-do-1.png
diff --git a/docs/assets/images/text-field-do-2.png b/docs/assets/images/text-field-do-2.png
diff --git a/docs/assets/images/text-field-do-3.png b/docs/assets/images/text-field-do-3.png
diff --git a/docs/assets/images/text-field-do-4.png b/docs/assets/images/text-field-do-4.png
diff --git a/docs/assets/images/text-field-dont-1.png b/docs/assets/images/text-field-dont-1.png
diff --git a/docs/assets/images/text-field-dont-2.png b/docs/assets/images/text-field-dont-2.png
diff --git a/docs/assets/images/text-field-dont-3.png b/docs/assets/images/text-field-dont-3.png
diff --git a/docs/assets/images/text-field-dont-4.png b/docs/assets/images/text-field-dont-4.png
diff --git a/docs/assets/images/text-field-hero.png b/docs/assets/images/text-field-hero.png
diff --git a/docs/assets/toolkit-artwork.png → docs/assets/images/toolkit-artwork.png b/docs/assets/toolkit-artwork.png → docs/assets/images/toolkit-artwork.png
diff --git a/docs/assets/toolkit-button-click-test.png → ...sets/images/toolkit-button-click-test.png b/docs/assets/toolkit-button-click-test.png → ...sets/images/toolkit-button-click-test.png
diff --git a/docs/assets/toolkit-button-test.gif → docs/assets/images/toolkit-button-test.gif b/docs/assets/toolkit-button-test.gif → docs/assets/images/toolkit-button-test.gif
diff --git a/docs/assets/toolkit-theme-test.gif → docs/assets/images/toolkit-theme-test.gif b/docs/assets/toolkit-theme-test.gif → docs/assets/images/toolkit-theme-test.gif
diff --git a/docs/assets/webview-test.gif → docs/assets/images/webview-test.gif b/docs/assets/webview-test.gif → docs/assets/images/webview-test.gif
diff --git a/src/badge/README.md b/src/badge/README.md
@@ -2,17 +2,32 @@
 
 The `vscode-badge` component is used to highlight an item, attract attention, and/or flag status.
 
-## Attributes
-
-None
+![Badge hero](/docs/assets/images/badge-hero.png)
 
 ## Usage
 
-A `vscode-badge` can only contain numbers to follow the conventions of the Visual Studio Code design language.
+| ❌ Don't                                                                                           | ✅ Do                                                          |
+| -------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
+| ![Badge with text value](/docs/assets/images/badge-dont-1.png)                                     | ![Badge with number value](/docs/assets/images/badge-do-1.png) |
+| Don't use a badge to display text content. Use a [vscode-tag](../tag/README.md) component instead. | Use a badge to display numbers.                                |
+
+| ❌ Don't                                                                 | ✅ Do                                                                                      |
+| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ |
+| ![Badge used to display and error](/docs/assets/images/badge-dont-2.png) | ![Badge showing the number of items in a history view](/docs/assets/images/badge-do-2.png) |
+| Don't use a badge to indicate an error.                                  | Use badges to indicate the numbered state of an element.                                   |
+
+| ❌ Don't                                                                | ✅ Do                                                                            |
+| ----------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| ![Multiple badges on one element](/docs/assets/images/badge-dont-2.png) | ![One badge used for each section in a view](/docs/assets/images/badge-do-3.png) |
+| Don't use more than one badge on a single element.                      | Ensure badges are clearly associated with their parent element.                  |
 
-If a component that labels an item with a string is desired, see the `vscode-tag` component.
+## Implementation
+
+### Attributes
+
+None
 
-### Basic Usage
+### Basic Badge
 
 [Interactive Storybook Example](https://microsoft.github.io/vscode-webview-ui-toolkit/?path=/story/library-badge--default)
 

diff --git a/src/button/README.md b/src/button/README.md
@@ -2,7 +2,48 @@
 
 The `vscode-button` is a web component implementation of a [button element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button). The `vscode-button` also supports several visual appearances––primary, secondary, and icon.
 
-## Attributes
+![Button hero](/docs/assets/images/button-hero.png)
+
+## Usage
+
+### Types
+
+| Type      | Example                                                                                               | Usage                                                                              |
+| --------- | ----------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| Primary   | <img src="../../docs/assets/images/button-types-primary.png" alt="Primary button" width="100px"/>     | Emphasizes the highest priority action in a view.                                  |
+| Secondary | <img src="../../docs/assets/images/button-types-secondary.png" alt="Secondary button" width="100px"/> | Used for additional actions in a view that already features a primary action.      |
+| Icon      | <img src="../../docs/assets/images/button-types-icon.png" alt="Icon button" width="50px"/>            | A space-efficient style that renders a single icon to represent a specific action. |
+
+### Best Practices
+
+| ❌ Don't                                                           | ✅ Do                                                                              |
+| ------------------------------------------------------------------ | ---------------------------------------------------------------------------------- |
+| ![Multiple primary buttons](/docs/assets/images/button-dont-1.png) | ![One primary and multiple secondary buttons](/docs/assets/images/button-do-1.png) |
+| Don't use multiple primary buttons in close proximity.             | Provide a single primary button with one or more secondary actions                 |
+
+| ❌ Don't                                                                | ✅ Do                                                               |
+| ----------------------------------------------------------------------- | ------------------------------------------------------------------- |
+| ![Buttons with incorrect casing](/docs/assets/images/button-dont-2.png) | ![Buttons with correct casing](/docs/assets/images/button-do-2.png) |
+| Don't use fully capitalized or lowercase text.                          | Use sentence case for all button text.                              |
+
+| ❌ Don't                                                            | ✅ Do                                                                                          |
+| ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| ![Button with a vague label](/docs/assets/images/button-dont-3.png) | ![Button with a clear label](/docs/assets/images/button-do-3.png)                              |
+| Don't use vague action text.                                        | Use clear verbs like "Save" or "Cancel" to ensure users feel confident when peforming actions. |
+
+| ❌ Don't                                                                                    | ✅ Do                                                                                  |
+| ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| ![Button used as a link](/docs/assets/images//button-dont-4.png)                            | ![Button clearly associated with the view above](/docs/assets/images//button-do-4.png) |
+| Don't use buttons as navigational elements. Use a [vscode-link](../link/README.md) instead. | Use buttons to perform actions relevant to the current view.                           |
+
+| ❌ Don't                                                                       | ✅ Do                                                                                                       |
+| ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- |
+| ![Icon button used for primary action](/docs/assets/images//button-dont-5.png) | ![Icon buttons in a group](/docs/assets/images//button-do-5.png)                                            |
+| Don't use an icon button for primary actions.                                  | Use icon buttons for supporting actions in space-constrained layouts. Use icons that convey clear outcomes. |
+
+## Implementation
+
+### Attributes
 
 | Attribute        | Type    | Description                                                                             |
 | ---------------- | ------- | --------------------------------------------------------------------------------------- |
@@ -20,9 +61,7 @@ The `vscode-button` is a web component implementation of a [button element](http
 | `type`           | string  | See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#attributes). |
 | `value`          | string  | See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#attributes). |
 
-## Usage
-
-### Basic Usage
+### Basic Button
 
 [Interactive Storybook Example](https://microsoft.github.io/vscode-webview-ui-toolkit/?path=/story/library-button--default)
 

diff --git a/src/checkbox/README.md b/src/checkbox/README.md
@@ -2,7 +2,33 @@
 
 The `vscode-checkbox` is a web component implementation of a [checkbox element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Input/checkbox).
 
-## Attributes
+![Checkbox hero](/docs/assets/images/checkbox-hero.png)
+
+## Usage
+
+| ❌ Don't                                                      | ✅ Do                                                                                                                                                                                             |
+| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| ![Image placeholder](/docs/assets/images/checkbox-dont-1.png) | ![Image placeholder](/docs/assets/images/checkbox-do-1.png)                                                                                                                                       |
+| Avoid grouping unrelated checkboxes together.                 | Split related checkboxes into groups of with descriptive labels. It's ok to group up to three loosely-unrelated checkboxes into one group if using a label that generally captures their purpose. |
+
+| ❌ Don't                                                      | ✅ Do                                                                           |
+| ------------------------------------------------------------- | ------------------------------------------------------------------------------- |
+| ![Image placeholder](/docs/assets/images/checkbox-dont-2.png) | ![Image placeholder](/docs/assets/images/checkbox-do-2.png)                     |
+| Avoid using horizontal checkbox group layouts.                | Arrange checkbox groups vertically to make it easy to scan and compare options. |
+
+| ❌ Don't                                                                                   | ✅ Do                                                       |
+| ------------------------------------------------------------------------------------------ | ----------------------------------------------------------- |
+| ![Image placeholder](/docs/assets/images/checkbox-dont-3.png)                              | ![Image placeholder](/docs/assets/images/checkbox-do-3.png) |
+| Don't use an ambiguous label that makes it difficult to understand what the checkbox does. | Use checkbox labels that imply clearly opposite states.     |
+
+| ❌ Don't                                                      | ✅ Do                                                       |
+| ------------------------------------------------------------- | ----------------------------------------------------------- |
+| ![Image placeholder](/docs/assets/images/checkbox-dont-4.png) | ![Image placeholder](/docs/assets/images/checkbox-do-4.png) |
+| Don't use long blocks of text.                                | Use concise language to describe each option.               |
+
+## Implementation
+
+### Attributes
 
 | Attribute   | Type    | Description                                                                              |
 | ----------- | ------- | ---------------------------------------------------------------------------------------- |
@@ -13,15 +39,13 @@ The `vscode-checkbox` is a web component implementation of a [checkbox element](
 | `required`  | boolean | Indicates that the user must check the checkbox before the owning form can be submitted. |
 | `value`     | string  | The string to use as the value of the checkbox when submitting the form                  |
 
-## Properties
+### Properties
 
 | Attribute       | Type    | Description                                                               |
 | --------------- | ------- | ------------------------------------------------------------------------- |
 | `indeterminate` | boolean | Determines if the element should render the indeterminate checkbox state. |
 
-## Usage
-
-### Basic Usage
+### Basic Checkbox
 
 [Interactive Storybook Example](https://microsoft.github.io/vscode-webview-ui-toolkit/?path=/story/library-checkbox--default)
 

diff --git a/src/data-grid/README.md b/src/data-grid/README.md
@@ -1,41 +1,57 @@
 # Visual Studio Code Data Grid
 
-The `vscode-data-grid` enables developers to display data in a tabular layout. The data grid is created using three components that work together:
+The `vscode-data-grid` enables developers to display data in a tabular layout.
+
+![Data grid hero](/docs/assets/images/data-grid-hero.png)
+
+The data grid is created using three components that work together:
 
 -   `<vscode-data-grid>`: The top level container element.
 -   `<vscode-data-grid-row>`: Displays a single row of data associated with a single record or a header row.
 -   `<vscode-data-grid-cell>`: Displays a single cell of data within a row.
 
-## Data Grid Attributes
+## Usage
+
+| ❌ Don't                                                                     | ✅ Do                                                                      |
+| ---------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| ![Data grid used as a simple list](/docs/assets/images/data-grid-dont-1.png) | ![Data grid with a large data set](/docs/assets/images/data-grid-do-1.png) |
+| Don't use a data grid in place of a basic list.                              | Use data grids to list complex data with secondary information.            |
+
+| ❌ Don't                                                                    | ✅ Do                                                                                                                                                                                                           |
+| --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| ![Data grid in a VS Code sidebar](/docs/assets/images/data-grid-dont-2.png) | ![Data grid in a VS Code editor panel](/docs/assets/images/data-grid-do-2.png)                                                                                                                                  |
+| Avoid data grids in small containers if possible.                           | Place data grids in a main content area to display as much information as possible in one view. It's ok to use a data grid in a small container if only using 2-3 small columns that don't scroll horizontally. |
+
+## Implementation
+
+### Data Grid Attributes
 
 | Attribute               | Type   | Description                                                                            |
 | ----------------------- | ------ | -------------------------------------------------------------------------------------- |
 | `generate-header`       | string | The type of header row that should be generated. Options: `default`, `sticky`, `none`. |
 | `grid-template-columns` | string | A string that gets applied to the `grid-template-columns` attribute of child rows.     |
 
-## Data Grid Row Attributes
+### Data Grid Row Attributes
 
 | Attribute               | Type   | Description                                                          |
 | ----------------------- | ------ | -------------------------------------------------------------------- |
 | `grid-template-columns` | string | A CSS Grid string that defines the column widths of a data grid row. |
 | `row-type`              | string | The type of row. Options: `default`, `header`, `sticky-header`.      |
 
-## Data Grid Cell Attributes
+### Data Grid Cell Attributes
 
 | Attribute     | Type   | Description                                           |
 | ------------- | ------ | ----------------------------------------------------- |
 | `cell-type`   | string | The type of cell. Options: `default`, `columnheader`. |
 | `grid-column` | string | The column index of the cell.                         |
 
-## Usage
-
 ❗️❗️❗️ Important ❗️❗️❗️
 
 An aria-label of "Data Grid" is automatically defined on all data grids so they are technically accessible out of the box. However, a descriptive and meaningful label that fits the use case or context of the data grid should always be defined to replace the default label so those viewing your data grid with a screen reader can better understand the meaning of the data.
 
 For example, if you're using a data grid to display real-time earthquake data, adding an aria-label with the value "Real-Time Earthquakes" would be appropriate.
 
-### Basic Usage
+### Basic Data Grid
 
 The recommended basic usage of the `vscode-data-grid` is to use JavaScript (or TypeScript) to programmatically populate the rows and cells of the grid using the `rowsData` property as shown below.
 

diff --git a/src/divider/README.md b/src/divider/README.md
@@ -2,15 +2,27 @@
 
 The `vscode-divider` is a web component implementation of a [horiztonal rule element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/hr).
 
+![Divider hero](/docs/assets/images/divider-hero.png)
+
+## Usage
+
+| ❌ Don't                                                                             | ✅ Do                                                                                              |
+| ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- |
+| ![An editor panel divided into pseudo-views](/docs/assets/images/divider-dont-1.png) | ![A form with with multiple sections separated by a divider](/docs/assets/images/divider-do-1.png) |
+| Don't use a divider to create pseudo-views within a webview.                         | Use dividers to create distinct sections of related content in a single view.                      |
+
+| ❌ Don't                                                                           | ✅ Do                                                                          |
+| ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| ![A form with dividers between each input](/docs/assets/images/divider-dont-2.png) | ![A form with dividers between sections](/docs/assets/images/divider-do-2.png) |
+| Don't split up related form elements with a divider.                               | Use a divider to separate multiple forms on the same page.                     |
+
 ## Attributes
 
 | Attribute | Type   | Description                                    |
 | --------- | ------ | ---------------------------------------------- |
 | role      | string | Indicates the semantic meaning of the divider. |
 
-## Usage
-
-### Basic Usage
+### Basic Divider
 
 [Interactive Storybook Example](https://microsoft.github.io/vscode-webview-ui-toolkit/?path=/story/library-divider--default)