add custom element documentation

site/content/docs/03-run-time.md

@@ -907,7 +907,54 @@ app.count += 1;
 
 ### Custom element API
 
-* TODO
+---
+
+Svelte components can also be compiled to custom elements (aka web components) using the `customElements: true` compiler option. You should specify a tag name for the component using the [`<svelte:options>`](docs#svelte_options) element.
+
+```html
+<svelte:options tag="my-element">
+
+<script>
+	export let name = 'world';
+</script>
+
+<h1>Hello {name}!</h1>
+<slot></slot>
+```
+
+---
+
+Alternatively, use `tag={null}` to indicate that the consumer of the custom element should name it.
+
+```js
+import MyElement from './MyElement.svelte';
+
+customElements.define('my-element', MyElement);
+```
+
+---
+
+By default, custom elements are compiled with `accessors: true`, which means that any [props](docs#Attributes_and_props) are exposed as properties of the DOM element (as well as being readable/writable as attributes, where possible).
+
+To prevent this, add `accessors={false}` to `<svelte:options>`.
+
+```js
+const el = document.querySelector('my-element');
+
+// get the current value of the 'name' prop
+console.log(el.name);
+
+// set a new value, updating the shadow DOM
+el.name = 'everybody';
+```
+
+Custom elements can be a useful way to package components for consumption in a non-Svelte app, as they will work with vanilla HTML and JavaScript as well as [most frameworks](https://custom-elements-everywhere.com/). There are, however, some important differences to be aware of:
+
+* Styles are *encapsulated*, rather than merely *scoped*. This means that any non-component styles (such as you might have in a `global.css` file) will not apply to the custom element, including styles with the `:global(...)` modifier
+* Instead of being extracted out as a separate .css file, styles are inlined into the component as a JavaScript string
+* Custom elements are not generally suitable for server-side rendering, as the shadow DOM is invisible until JavaScript loads
+* Polyfills are required to support older browsers
+
 
 
 ### Server-side component API