diff --git a/docs/theming.md b/docs/theming.md
index 9b90fb26066..08825b6bbea 100644
--- a/docs/theming.md
+++ b/docs/theming.md
@@ -1,14 +1,14 @@
-Theming Element
-============
+CSS Based Themes
+================
 
 Themes are a very basic way of providing simple alternative look & feels to the
 Element app via CSS & custom imagery.
 
-They are *NOT* co be confused with 'skins', which describe apps which sit on top
+They are *NOT* to be confused with 'skins', which describe apps which sit on top
 of matrix-react-sdk - e.g. in theory Element itself is a react-sdk skin.
 As of Jan 2017, skins are not fully supported; Element is the only available skin.
 
-To define a theme for Element:
+To define a css theme for Element:
 
  1. Pick a name, e.g. `teal`. at time of writing we have `light` and `dark`.
  2. Fork `src/skins/vector/css/themes/dark.scss` to be `teal.scss`
@@ -24,10 +24,10 @@ To define a theme for Element:
 In future, the assets for a theme will probably be gathered together into a
 single directory tree.
 
-Custom Themes
-=============
+ JSON Based Themes
+==================
 
-Themes derived from the built in themes may also be defined in settings.
+JSON themes derived from the built in CSS themes may be defined in the `config.json` file. When [`feature_custom_themes`](https://github.com/vector-im/element-web/blob/master/docs/labs.md#custom-themes-feature_custom_themes) is enabled, users can add new JSON themes in the Appearance section of Settings.
 
 To avoid name collisions, the internal name of a theme is
 `custom-${theme.name}`. So if you want to set the custom theme below as the