diff --git a/test/playground.generated/customizing-the-appearence-tokens-and-colors.html b/test/playground.generated/customizing-the-appearence-tokens-and-colors.html
index ec75cd82..1c935084 100644
--- a/test/playground.generated/customizing-the-appearence-tokens-and-colors.html
+++ b/test/playground.generated/customizing-the-appearence-tokens-and-colors.html
@@ -10,16 +10,6 @@
 <style>
 /*----------------------------------------SAMPLE CSS START*/
 
-/*
-These rules customize the "Visual Studio" (vs) theme.
-
-Token names can be discovered by:
-a) exploring the .css theme files that come with the editor;
-b) inspecting the dom elements rendered by the editor;
-*/
-.monaco-editor.vs .token.comment		{ color: orange; }
-.monaco-editor.vs .token.comment.js		{ color: green; }
-.monaco-editor.vs .token.comment.css	{ color: blue; }
 
 
 /*----------------------------------------SAMPLE CSS END*/
@@ -46,15 +36,38 @@ THIS IS A GENERATED FILE VIA gulp generate-test-samples
 loadEditor(function() {
 /*----------------------------------------SAMPLE JS START*/
 
-// This example shows how to integrate the editor with a certain theme and then customize the token colors of that theme.
-var htmlCode = "<html>\n<head>\n	<!-- HTML comment -->\n	<style type=\"text/css\">\n		/* CSS comment */\n	</style>\n	<script type=\"javascript\">\n		// JavaScript comment\n	</"+"script>\n</head>\n<body></body>\n</html>";
+
+// Theme matching (i.e. applying a style to a token) happens in JavaScript.
+// We must therefore register the theme rules in JavaScript.
+
+// A custom theme must name its base theme (i.e. 'vs', 'vs-dark' or 'hc-black')
+// It can then choose to inherit the rules from the base theme or not
+// A rule token matching is prefix based: e.g.
+//  - string will match a token with type: string, string.double.js or string.html
+//  - string.double will match a token with type string.double but will not match string or string.html
+
+// !!! Tokens can be inspected using F1 > Developer: Inspect Tokens !!!
+
+monaco.editor.defineTheme('myCustomTheme', {
+	base: 'vs', // can also be vs-dark or hc-black
+	inherit: true, // can also be false to completely replace the builtin rules
+	rules: [
+		{ token: 'comment', foreground: 'ffa500', fontStyle: 'italic underline' },
+		{ token: 'comment.js', foreground: '008800', fontStyle: 'bold' },
+		{ token: 'comment.css', foreground: '0000ff' } // will inherit fontStyle from `comment` above
+	]
+});
 
 monaco.editor.create(document.getElementById("container"), {
-	value: htmlCode,
+	value: getCode(),
 	language: "text/html",
-	theme: "vs"
+	theme: "myCustomTheme"
 });
 
+function getCode() {
+	return "<html><!-- // !!! Tokens can be inspected using F1 > Developer: Inspect Tokens !!! -->\n<head>\n	<!-- HTML comment -->\n	<style type=\"text/css\">\n		/* CSS comment */\n	</style>\n	<script type=\"javascript\">\n		// JavaScript comment\n	</"+"script>\n</head>\n<body></body>\n</html>";
+}
+
 
 /*----------------------------------------SAMPLE CSS END*/
 });
diff --git a/website/playground/new-samples/customizing-the-appearence/tokens-and-colors/sample.css b/website/playground/new-samples/customizing-the-appearence/tokens-and-colors/sample.css
index ff8164d4..e69de29b 100644
--- a/website/playground/new-samples/customizing-the-appearence/tokens-and-colors/sample.css
+++ b/website/playground/new-samples/customizing-the-appearence/tokens-and-colors/sample.css
@@ -1,10 +0,0 @@
-/*
-These rules customize the "Visual Studio" (vs) theme.
-
-Token names can be discovered by:
-a) exploring the .css theme files that come with the editor;
-b) inspecting the dom elements rendered by the editor;
-*/
-.monaco-editor.vs .token.comment		{ color: orange; }
-.monaco-editor.vs .token.comment.js		{ color: green; }
-.monaco-editor.vs .token.comment.css	{ color: blue; }
diff --git a/website/playground/new-samples/customizing-the-appearence/tokens-and-colors/sample.js b/website/playground/new-samples/customizing-the-appearence/tokens-and-colors/sample.js
index d2cc2057..451e111e 100644
--- a/website/playground/new-samples/customizing-the-appearence/tokens-and-colors/sample.js
+++ b/website/playground/new-samples/customizing-the-appearence/tokens-and-colors/sample.js
@@ -1,8 +1,31 @@
-// This example shows how to integrate the editor with a certain theme and then customize the token colors of that theme.
-var htmlCode = "<html>\n<head>\n	<!-- HTML comment -->\n	<style type=\"text/css\">\n		/* CSS comment */\n	</style>\n	<script type=\"javascript\">\n		// JavaScript comment\n	</"+"script>\n</head>\n<body></body>\n</html>";
+
+// Theme matching (i.e. applying a style to a token) happens in JavaScript.
+// We must therefore register the theme rules in JavaScript.
+
+// A custom theme must name its base theme (i.e. 'vs', 'vs-dark' or 'hc-black')
+// It can then choose to inherit the rules from the base theme or not
+// A rule token matching is prefix based: e.g.
+//  - string will match a token with type: string, string.double.js or string.html
+//  - string.double will match a token with type string.double but will not match string or string.html
+
+// !!! Tokens can be inspected using F1 > Developer: Inspect Tokens !!!
+
+monaco.editor.defineTheme('myCustomTheme', {
+	base: 'vs', // can also be vs-dark or hc-black
+	inherit: true, // can also be false to completely replace the builtin rules
+	rules: [
+		{ token: 'comment', foreground: 'ffa500', fontStyle: 'italic underline' },
+		{ token: 'comment.js', foreground: '008800', fontStyle: 'bold' },
+		{ token: 'comment.css', foreground: '0000ff' } // will inherit fontStyle from `comment` above
+	]
+});
 
 monaco.editor.create(document.getElementById("container"), {
-	value: htmlCode,
+	value: getCode(),
 	language: "text/html",
-	theme: "vs"
+	theme: "myCustomTheme"
 });
+
+function getCode() {
+	return "<html><!-- // !!! Tokens can be inspected using F1 > Developer: Inspect Tokens !!! -->\n<head>\n	<!-- HTML comment -->\n	<style type=\"text/css\">\n		/* CSS comment */\n	</style>\n	<script type=\"javascript\">\n		// JavaScript comment\n	</"+"script>\n</head>\n<body></body>\n</html>";
+}
