docs: rewrite Your-First-Component

Based on user feedback this section has been re-written for a few
reasons:

 - It focusses more on the `@controller` decorator and less on Custom
   Elements
 - It repeats (multiple times, including a call-out box) that the class
   name must consist of two words, as this is something users miss.

Author: keithamus

docs/_guide/conventions.md

@@ -16,7 +16,7 @@ class UserListElement extends HTMLElement {}
 
 ### The best class-names are two word descriptions
 
-Custom elements are required to have a `-` inside the tag name. Catalyst's `@controller` will derive the tag name from the class name - and so as such the class name needs to have at least two capital letters, or to put it another way, it needs to consist of two words. The element name should describe what it does succinctly in two words. Some examples:
+Custom elements are required to have a `-` inside the tag name. Catalyst's `@controller` will derive the tag name from the class name - and so as such the class name needs to have at least two capital letters, or to put it another way, it needs to consist of at least two CamelCased words. The element name should describe what it does succinctly in two words. Some examples:
 
  - `theme-picker` (`class ThemePickerElement`)
  - `markdown-toolbar` (`class MarkdownToolbarElement`)

docs/_guide/your-first-component.md

@@ -3,51 +3,64 @@ subtitle: Building an HTMLElement
 chapter: 2
 ---
 
-Custom Elements allow you to create reusable components that you can declare in HTML, and [progressively enhance](https://en.wikipedia.org/wiki/Progressive_enhancement) within JavaScript. Custom Elements must named with a `-` in the HTML name, and the JS class must `extend HTMLElement`. When the browser connects each element class instance to the DOM node, `connectedCallback` is fired - this is where you can change parts of the element. Here's a basic example:
+### Catalyst's `@controller` decorator
 
-```html
-<hello-world></hello-world>
-<script>
+Catalyst's `@controller` decorator lets you create Custom Elements with virtually no boilerplate, by automatically calling `customElements.register`, and by adding ["Actions"](/guide/actions) and ["Targets"](/guide/targets) features described later. Using TypeScript (with `decorators` support enabled), simply add `@controller` to the top of your class:
+
+```js
+@controller
 class HelloWorldElement extends HTMLElement {
   connectedCallback() {
     this.innerHTML = 'Hello World!'
   }
 }
-window.customElements.register('hello-world', HelloWorldElement)
-</script>
+// This happens automatically within `@controller`
+// window.customElements.register('hello-world', HelloWorldElement)
 ```
 <br>
 
+Catalyst will automatically convert the classes name; removing the trailing `Element` suffix and lowercasing all capital letters, separating them with a dash.
 
-Here are the three key elements to remember:
+By convention, Catalyst controllers end in `Element`, and Catalyst will strip this for the tag name, but the  `Element` suffix is not required - just convention. All examples in this guide use `Element` suffixed names.
 
- - Custom Elements must have a dash in the name.
- - The JS class must `extend HTMLElement`
- - `connectedCallback` can be used as a life-cycle hook for when the element and class are connected.
+<div class="d-flex border rounded-1 my-3 box-shadow-medium">
+  <span class="d-flex bg-blue text-white rounded-left-1 p-3">
+    <svg width="24" viewBox="0 0 14 16" class="octicon octicon-info" aria-hidden="true">
+      <path
+        fill-rule="evenodd"
+        d="M6.3 5.69a.942.942 0 0 1-.28-.7c0-.28.09-.52.28-.7.19-.18.42-.28.7-.28.28 0 .52.09.7.28.18.19.28.42.28.7 0 .28-.09.52-.28.7a1 1 0 0 1-.7.3c-.28 0-.52-.11-.7-.3zM8 7.99c-.02-.25-.11-.48-.31-.69-.2-.19-.42-.3-.69-.31H6c-.27.02-.48.13-.69.31-.2.2-.3.44-.31.69h1v3c.02.27.11.5.31.69.2.2.42.31.69.31h1c.27 0 .48-.11.69-.31.2-.19.3-.42.31-.69H8V7.98v.01zM7 2.3c-3.14 0-5.7 2.54-5.7 5.68 0 3.14 2.56 5.7 5.7 5.7s5.7-2.55 5.7-5.7c0-3.15-2.56-5.69-5.7-5.69v.01zM7 .98c3.86 0 7 3.14 7 7s-3.14 7-7 7-7-3.12-7-7 3.14-7 7-7z"
+      />
+    </svg>
+  </span>
+  <div class="p-3">
+  
+Remember! A class name _must_ include at least two CamelCased words (not including the `Element` suffix). One-word elements will raise exceptions. Example of good names: `UserListElement`, `SubTaskElement`, `PagerContainerElement`
 
-### Catalyst
+  </div>
+</div>
 
-Catalyst saves you writing some of this boilerplate, by automatically calling the `customElements.register` code, and by adding ["Actions"](/guide/actions) and ["Targets"](/guide/targets) features described later. If you're using TypeScript with `decorators` support, simply add `@controller` to the top of your class:
 
-```js
-@controller
+### What does `@controller` do?
+
+Catalyst components are really just "Custom Elements", they're doing all the heavy lifting. Custom Elements allow you to create reusable components that you can declare in HTML, and [progressively enhance](https://en.wikipedia.org/wiki/Progressive_enhancement) within JavaScript. Custom Elements must named with a `-` in the HTML name, and the JS class must `extend HTMLElement`. When the browser connects each element class instance to the DOM node, `connectedCallback` is fired - this is where you can change parts of the element. Here's a basic example:
+
+```html
+<hello-world></hello-world>
+<script>
 class HelloWorldElement extends HTMLElement {
   connectedCallback() {
     this.innerHTML = 'Hello World!'
   }
 }
-// No longer need this:
-// window.customElements.register('hello-world', HelloWorldElement)
+window.customElements.register('hello-world', HelloWorldElement)
+</script>
 ```
-<br>
-
-Catalyst will automatically convert the classes name; removing the trailing `Element` suffix and lowercasing all capital letters, separating them with a dash.
 
-By convention, Catalyst controllers end in `Element`, and Catalyst will strip this for the tag name, but suffixing `Element` is not required. All examples in this guide use `Element` suffixed names.
+The Catalyst version isn't all that different, it's just that we have the `@controller` decorator to save on some of the boilerplate.
 
-#### What about without Decorators?
+### What about without TypeScript Decorators?
 
-If you don't want to use decorators, you can simply wrap the class in a call to `controller`:
+If you don't want to use TypeScript decorators, you can use `controller` as a regular function, and just pass it your class:
 
 ```js
 controller(