Add migration documentation (#6974)

# Pull Request

## 📖 Description

Based on the current documentation for 1.x, this additionally documentation highlights changes that will be necessary for any consumers of `@microsoft/fast-element` and suggested changes.

## 👩‍💻 Reviewer Notes

There may be additional breaking changes, however since the original documentation does not necessarily go over them, we will assume that no one is using an undocumented (outside of API extractor) part of the API. All other breaking changes should be noted in the forthcoming changelog.

## ✅ Checklist

### General

- [ ] I have included a change request file using `$ yarn change`
- [ ] I have added tests for my changes.
- [x] I have tested my changes.
- [x] I have updated the project documentation to reflect my changes.
- [x] I have read the [CONTRIBUTING](https://github.com/microsoft/fast/blob/master/CONTRIBUTING.md) documentation and followed the [standards](https://github.com/microsoft/fast/blob/master/CODE_OF_CONDUCT.md#our-standards) for this project.

sites/website/src/docs/migration-guide.md

@@ -8,4 +8,148 @@ keywords:
   - web components
 ---
 
-// TODO
+# Migrating from 1.x to 2.x
+
+## Breaking Changes
+
+### `cssPartial`
+
+The `cssPartial` export no longer exists, in its place use `css.partial`.
+
+1.x Example:
+```ts
+import { cssPartial } from "@microsoft/fast-element";
+
+cssPartial`
+:host {
+  color: red;
+}`;
+```
+
+2.x Example:
+```ts
+import { css } from "@microsoft/fast-element";
+
+css.partial`
+:host {
+  color: red;
+}`;
+```
+
+### `CSSDirective`
+
+The `CSSDirective` has been updated to need to be defined. Additionally it cannot be extended from and must use `implements`.
+
+1.x Example:
+```ts
+import { CSSDirective } from "@microsoft/fast-element"
+
+class MyCSSDirective extends CSSDirective {
+    createCSS() {
+      return "color: red;"
+    }
+}
+
+export const myCssDirective = new MyCSSDirective();
+```
+
+2.x Example:
+```ts
+import { CSSDirective } from "@microsoft/fast-element"
+
+class MyCSSDirective implements CSSDirective {
+    createCSS() {
+      return "color: red;"
+    }
+}
+
+CSSDirective.define(MyCSSDirective);
+
+export const myCssDirective = new MyCSSDirective();
+```
+
+### `CSSDirective` with behaviors
+
+Behaviors have been extracted from `CSSDirective` so that they can be used in a modular fashion. The API has also been updated to be more intuitive and re-use methods that are common for web components (see `connectedCallback` in the 2.x example below).
+
+1.x Example:
+```ts
+import { CSSDirective } from "@microsoft/fast-element"
+
+class MyCSSDirective extends CSSDirective {
+  public cssProperty: string = "background";
+
+  createCSS() {
+    return `display: block; color: red;`
+  }
+
+  createBehavior() {
+    var that = this;
+
+    return {
+      bind(el) {
+        el.style.setProperty(that.cssProperty, "yellow")
+      },
+      unbind(el) {
+        el.style.removeProperty(that.cssProperty);
+      }
+    }
+  }
+}
+
+export const myCssDirective = new MyCSSDirective();
+```
+
+2.x Example:
+```ts
+import { css, CSSDirective, AddBehavior, HostBehavior } from "@microsoft/fast-element"
+
+const cssProperty: string = "background";
+
+const myCssBehavior: HostBehavior = {
+  connectedCallback: (controller) => {
+    controller.addStyles(css`:host {${cssProperty}: yellow }`)
+  },
+  disconnectedCallback: (controller) => {
+    controller.removeStyles(css`:host {${cssProperty}: yellow }`)
+  }
+}
+
+class MyCSSDirective implements CSSDirective {
+  createCSS(add: AddBehavior) {
+    add(myCssBehavior);
+    return `display: block; color: red;`
+  }
+}
+
+CSSDirective.define(MyCSSDirective);
+
+export const myCssDirective = new MyCSSDirective();
+```
+
+## Suggested Changes
+
+While some of the APIs remain available, we suggest going forward that certain patterns be updated.
+
+### `@customElement`
+
+We prefer using `FASTElement` and its `.define()` method over the `@customElement` decorator (which is still used under the hood). We believe this more closely matches with how you define custom elements using the native `customElements.define()`.
+
+1.x Example:
+```ts
+import { FASTElement, customElement } from '@microsoft/fast-element';
+
+@customElement('my-component')
+export class MyComponent extends FASTElement {}
+```
+
+2.x Example:
+```ts
+import { FASTElement } from "@microsoft/fast-element";
+
+class MyComponent extends FASTElement {}
+
+MyComponent.define({
+  name: "my-component"
+});
+```