diff --git a/docs/ui-components/lists.md b/docs/ui-components/lists.md
new file mode 100644
index 0000000000000000000000000000000000000000..364316e40d171c1f72bd7c39d718ddf25a7272d5
--- /dev/null
+++ b/docs/ui-components/lists.md
@@ -0,0 +1,98 @@
+---
+layout: default
+title: Lists
+parent: UI Components
+nav_order: 5
+---
+
+# Lists
+{:.no_toc}
+
+## Table of contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+Most lists can be rendered with pure markdown...
+
+## Unordered list
+<div class="code-example" markdown="1">
+- Item 1
+- Item 2
+- Item 3
+
+_or_
+
+* Item 1
+* Item 2
+* Item 3
+</div>
+```markdown
+- Item 1
+- Item 2
+- Item 3
+
+_or_
+
+* Item 1
+* Item 2
+* Item 3
+```
+
+
+## Ordered list
+<div class="code-example" markdown="1">
+1. Item 1
+1. Item 2
+1. Item 3
+</div>
+  ```markdown
+1. Item 1
+1. Item 2
+1. Item 3
+  ```
+## Task list
+
+<div class="code-example" markdown="1">
+- [ ] hello, this is a todo item
+- [ ] hello, this is another todo item
+- [x] goodbye, this item is done
+</div>
+  ```markdown
+- [ ] hello, this is a todo item
+- [ ] hello, this is another todo item
+- [x] goodbye, this item is done
+  ```
+
+## Definition list
+
+Definition lists require HTML syntax and aren't supported with the GitHub flavored markdown compiler.
+
+<div class="code-example" markdown="1">
+<dl>
+<dt>Name</dt>
+<dd>Godzilla</dd>
+<dt>Born</dt>
+<dd>1952</dd>
+<dt>Birthplace</dt>
+<dd>Japan</dd>
+<dt>Color</dt>
+<dd>Green</dd>
+</dl>
+</div>
+```html
+<dl>
+  <dt>Name</dt>
+  <dd>Godzilla</dd>
+  <dt>Born</dt>
+  <dd>1952</dd>
+  <dt>Birthplace</dt>
+  <dd>Japan</dd>
+  <dt>Color</dt>
+  <dd>Green</dd>
+</dl>
+```
+