diff --git a/packages/core/docs/display/title-demo/demo1.md b/packages/core/docs/display/title-demo/demo1.md
index 8e195a4a6..1f7ca8644 100644
--- a/packages/core/docs/display/title-demo/demo1.md
+++ b/packages/core/docs/display/title-demo/demo1.md
@@ -1,29 +1,53 @@
-# Demo
+
+
+EuiTitle styles the page, section, and content headings we use in Kibana. They can contain any markup, but usually contain a heading tag of some sort. Unlike EuiText they are margin neutral and more suitable for general layout design.
+
+
```hbs template
-
- Title size="l"
-
-
- Title size="m"
-
-
- Title size="s"
-
-
- Title size="xs"
-
-
- Title size="xxs"
-
-
- Title size="xxxs"
-
-
-
-
-You could also change the title tag using `@tagName`
-
- This is an h6
-
+
+
+ This is a large title, only one should exist per page
+
+ size="l"
+
+
+
+ This is the default size for title
+
+ size="m"
+
+
+
+ This is a small title
+
+ size="s"
+
+
+
+ This is an extra small title
+
+ size="xs"
+
+
+
+ This is an extra extra small title
+
+ size="xxs"
+
+
+
+
+ This is an extra extra extra small title and should only be used when the
+ title is inconsequential (like a label)
+
+
+ size="xxxs"
+
+
+
+
+ Titles are markup agnostic, they only confer style
+
+
```