+
+
+1. **Term:** The label for the list item.
+1. **Description:** The descriptive value for a term.
+1. **Contextual help (optional):** When clicked, will trigger a popover that offers more details or definition for a term. Marked by a dotted underline.
+1. **Editable item (optional):** Using an [inline edit component](/components/inline-edit), allows users to edit the description linked to a term. For more guidance, refer to [term help text](#term-help-text).
+
## Usage
-Use a description list when you have a set of terms and definitions related to a single item. The content within the definitions is not limited to only plain text. This component can be extremely useful in context of Detail pages for a certain resource or item.
+Use a description list when you have a set of terms and definitions related to a single topic. Definitions can be plain text or links.
+
+This is particularly useful in context of detail pages, for a certain resource or item:

@@ -23,14 +36,14 @@ By default, the description list will be formatted so that the term stacks verti
### Horizontal
-Description lists can also be horizontally formatted so that the term and description sit inline and the term comes before the description.
+Description lists can also be formatted horizontally, so that the term and description sit inline, with the term placed before the description.

### Using columns
-Columns can be applied in both vertical and horizontal formats. By default, there will be 24px gutters within the column grid.
+Columns can be applied in both vertical and horizontal formats. By default, there will be a 2xl spacer of gutters within the column grid.

@@ -41,7 +54,7 @@ Columns can be applied in both vertical and horizontal formats. By default, ther
### Term help text
-To provide help text about a term in the description list, you may add popovers indicated by a dotted underline on the label. This is recommended in detailed lists where you have many popovers and using a blue link or icon would clutter the page.
+To provide help text about a term in the description list, you can add popovers indicated by a dotted underline on the label. This is recommended in detailed lists where you have many popovers and using a blue link or icon would clutter the page.

diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/description-list/img/default.png b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/description-list/img/default.png
deleted file mode 100644
index 4f608ac86a..0000000000
Binary files a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/description-list/img/default.png and /dev/null differ
diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/description-list/img/default2column.png b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/description-list/img/default2column.png
deleted file mode 100644
index 99736b4776..0000000000
Binary files a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/description-list/img/default2column.png and /dev/null differ
diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/description-list/img/definitionlist.png b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/description-list/img/definitionlist.png
deleted file mode 100644
index 34253a45b8..0000000000
Binary files a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/description-list/img/definitionlist.png and /dev/null differ
diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/description-list/img/description-list-elements.svg b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/description-list/img/description-list-elements.svg
new file mode 100644
index 0000000000..a7a67d7c4e
--- /dev/null
+++ b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/description-list/img/description-list-elements.svg
@@ -0,0 +1,25 @@
+
diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/description-list/img/horizontal.png b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/description-list/img/horizontal.png
deleted file mode 100644
index 2841b05103..0000000000
Binary files a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/description-list/img/horizontal.png and /dev/null differ
diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/description-list/img/horizontal2column.png b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/description-list/img/horizontal2column.png
deleted file mode 100644
index 4f5051937a..0000000000
Binary files a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/description-list/img/horizontal2column.png and /dev/null differ
diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/description-list/img/termhelptext.png b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/description-list/img/termhelptext.png
deleted file mode 100644
index 34fe68555c..0000000000
Binary files a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/description-list/img/termhelptext.png and /dev/null differ