From 0c26116e2a69ba639a420d436fc2ded82cc53def Mon Sep 17 00:00:00 2001
From: Cory LaViska <cory@abeautifulsite.net>
Date: Tue, 7 Jul 2020 10:34:49 -0400
Subject: [PATCH] Update docs

---
 .github/CONTRIBUTING.md       |  4 ++
 .prettierignore               |  1 +
 docs/getting-started/usage.md | 69 +++++++++++++++++++++++++++++++----
 3 files changed, 67 insertions(+), 7 deletions(-)

diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
index 98eff7b3..999f89a5 100644
--- a/.github/CONTRIBUTING.md
+++ b/.github/CONTRIBUTING.md
@@ -96,3 +96,7 @@ The select component, for example, makes use of the dropdown, input, and menu co
 When designing a component's API, standard properties ("props") are generally used to change the _behavior_ of a component, whereas CSS custom properties ("CSS variables") are used to change the _appearance_ of a component. Remember that props can't respond to media queries, but CSS variables can.
 
 There are some exceptions to this (e.g. when it significantly improves developer experience), but a good rule of thumbs is "will this need to change based on screen size?" If so, you probably want to use a CSS variable.
+
+### Boolean Props
+
+Boolean props should _always_ default to `false`, otherwise there's no way for the user to unset it without JavaScript. To keep the API as friendly and consistent as possible, use a name like `noHeader` with a default value of `false` instead of `header` with a default value of `true`.
\ No newline at end of file
diff --git a/.prettierignore b/.prettierignore
index 39c9d41e..d1ed7ec9 100644
--- a/.prettierignore
+++ b/.prettierignore
@@ -2,6 +2,7 @@
 .stencil
 dist
 docs/assets
+docs/**/*.md
 loader
 node_modules
 src/components/**/readme.md
diff --git a/docs/getting-started/usage.md b/docs/getting-started/usage.md
index 62f5f934..92981ca1 100644
--- a/docs/getting-started/usage.md
+++ b/docs/getting-started/usage.md
@@ -1,17 +1,72 @@
 # Usage
 
-## HTML + JS
+## Web Component Basics
+
+Shoelace components are just regular HTML elements, or "custom elements" to be precise. You can use them like any other element. Each component has detailed documentation showing its props, events, methods, and more.
+
+### Properties
+
+Many components have properties ("props") that can be set using attributes. For example, buttons accept a `size` attribute that determines the button's size.
+
+```html
+<sl-button size="small">Small</sl-button>
+```
+
+Some props are booleans, so they only have true/false values. To set a boolean prop, add the corresponding attribute with no value.
+
+```html
+<sl-button pill>Pill Button</sl-button>
+```
+
+In rare cases, a prop may require an array, an object, or a function. For example, to customize the color picker's swatches, you set the `swatches` prop to an array of colors. This can be done with JavaScript.
+
+```html
+<sl-color-picker></sl-color-picker>
+
+<script>
+  const colorPicker = document.querySelector('sl-color-picker');
+  colorPicker.swatches = ['red', 'orange', 'yellow', 'green', 'blue', 'purple'];
+</script>
+```
+
+### Events
+
+You can listen for standard events such as `click`, `mouseover`, etc. as you normally would. In addition, some components emit custom events. You can listen for custom events the same way. All custom events are prefixed with `sl`.
+
+```html
+<sl-checkbox>Checkbox</sl-checkbox>
+
+<script>
+  const checkbox = document.querySelector('sl-checkbox');
+  checkbox.addEventListener('slChange', event => {
+    console.log('The checkbox has changed');
+  });
+</script>
+```
+
+### Methods
+
+Some components have methods you can call to trigger certain behaviors.
+
+
+### Differences from Native Elements
+
+You might expect similarly named elements to share the same API as native elements. This is not the case. Shoelace components are not designed to be one-to-one replacements for their HTML counterparts.
+
+For example, both `<button>` and `<sl-button>` have a `type` attribute, but they do different things (the former controls whether the button submits the form and the latter controls the button's appearance). Similarly, you can't call `focus()` on a Shoelace input — you need to use the component's `setFocus()` method instead. There are technical reasons for some of these design decisions that are outside the scope of this page.
+
+**TL;DR – Please don't make assumptions about a component's API!** To prevent unexpected behaviors, take the time to review the documentation and make sure you understand what each property, method, and event is actually doing.
+
+## With Frameworks
+
+### React
 
 TODO
 
-## React
+### Vue
 
 TODO
 
-## Vue
-
-TODO
-
-## Angular
+### Angular
 
 TODO