diff --git a/docs/docassets/images/ThemeSwatches.png b/docs/docassets/images/ThemeSwatches.png
new file mode 100644
index 0000000000..07a631b206
Binary files /dev/null and b/docs/docassets/images/ThemeSwatches.png differ
diff --git a/docs/theming.md b/docs/theming.md
index bf404c5ae7..a7ff89b0f1 100644
--- a/docs/theming.md
+++ b/docs/theming.md
@@ -1,4 +1,29 @@
-# Theming your Alfresco ADF app
+# Theming an ADF app
+
+The [Material Design](https://material.io/guidelines/material-design/introduction.html)
+specification doesn't specify a single color scheme. Instead it uses the concept
+of color **themes** to allow designers some flexibility in their choice of colors.
+
+A theme is a palette based around two main colors: the **primary** color (used widely
+throughout the app) and the **accent** color (used mainly for highlighting and calling
+out specific UI elements). Each of these colors is defined in a number of shades. For
+example, a blue/orange theme could define shades like the following:
+
+![Theme swatches](docassets/images/ThemeSwatches.png)
+
+Each shade is related to a particular purpose or set of purposes within the app. So for
+example, the shade that works best for text isn't necessarily the same shade you would use
+for flat areas of color. Material Design provides a number of
+[standard themes](https://material.io/guidelines/style/color.html#color-themes)
+with shades that are carefully chosen for each purpose within the UI. The CSS files are
+designed so that the names are consistent between themes (so the same "purpose" will always
+have the same class name across CSS files). This makes it easy to switch themes simply by
+changing a few CSS definitions. Material Design also defines the relationship between
+the different shades, so you can calculate your own color values or, more straightforwardly, use
+an [online palette design tool](http://mcg.mbitson.com/).
+
+See the [Material Design Style page](https://material.io/guidelines/style/color.html#) for
+more information about color concepts.
 
 ## Using a pre-built theme
 
@@ -20,7 +45,7 @@ Available pre-built themes:
 * `adf-pink-bluegrey.css`
 * `adf-purple-green.css`
 
-If you're using Angular CLI you can include one of the prebuilt theme in your `styles.scss` file:
+If you're using Angular CLI you can include one of the prebuilt themes in your `styles.scss` file:
 ```css
 @import '~@alfresco/adf-core/prebuilt-themes/adf-blue-orange.css';
 ```
@@ -32,7 +57,7 @@ Or you can add it directly in your index.html
 
 ## Defining a custom theme
 
-When you want more customization than a pre-built theme offers, you can create your own theme file. You need to include the packages only what you really use in your application.
+When you want more customization than a pre-built theme offers, you can create your own theme file. You only need to include the packages you actually use in your application.
 
 ```scss
 /*