Update theme docs

docs/_sidebar.md

@@ -4,6 +4,7 @@
   - [Installation](/getting-started/installation.md)
   - [Usage](/getting-started/usage.md)
   - [Customizing](/getting-started/customizing.md)
+  - [Themes](/getting-started/themes.md)
   - [Roadmap](/getting-started/roadmap.md)
   - [Community](/getting-started/community.md)
 

docs/getting-started/customizing.md

@@ -98,26 +98,3 @@ Alternatively, you can set them inline directly on the element.
 ```
 
 Not all components expose CSS custom properties. For those that do, they can be found in the component's API documentation.
-
-## Writing a Theme
-
-Customizing Shoelace is fairly easy, but you can take things a step further and create a full-blown theme if you want. A theme is nothing more than a stylesheet that uses the APIs described above to customize Shoelace's design tokens and components.
-
-It's a good practice to include `shoelace.css` in your app and add your theme's stylesheet directly below it. That way, when an update introduces a new design token, your theme will still work with the default design token value.
-
-### Submitting a Theme
-
-**I am very interested in offering well-designed themes to complement this library.** To submit a theme for review, please open an issue on GitHub with the theme attached. Once approved, your theme will be showcased in the project's documentation (that section is coming soon).
-
-Themes that are in high demand include:
-
-- Dark mode ([details](https://github.com/shoelace-style/shoelace/issues/98))
-- High contrast ([details](https://github.com/shoelace-style/shoelace/issues/99))
-
-**I am willing to contribute a minimum of $200 USD to commission each of the themes listed above.** 
-
-Please note the following requirements before submitting a theme.
-
-- Themes must be complete and of high quality
-- Themes must be available under the same open source license as Shoelace
-- If a theme is not original, the derivative work must have a license that is compatible with Shoelace's license

docs/getting-started/themes.md

@@ -0,0 +1,76 @@
+## Themes
+
+Customizing Shoelace is easy, but you can take things a step further and create an entire theme. The following themes have been designed or vetted by the Shoelace team and are available under an open source license.
+
+## Available Themes
+
+- [Shoelace Dark](#) by [@claviska](https://twitter.com/claviska)
+
+## Creating a Theme
+
+A theme is nothing more than a stylesheet that uses the Shoelace API to customize design tokens and/or components. To create a theme, you will need a decent understanding of CSS, including [CSS Custom Properties](https://developer.mozilla.org/en-US/docs/Web/CSS/--*) and the [`::part` selector](https://developer.mozilla.org/en-US/docs/Web/CSS/::part).
+
+The easiest way to create a theme is to piggyback on top of the default theme, adjusting design tokens and styling components only where necessary to achieve the look you want. This makes your theme ligher and more "future proof", as future Shoelace versions may introduce new components that you might not have accounted for.
+
+Technically, you can roll your own theme from scratch without using the default theme as a baseline, but that approach isn't recommended.
+
+### Design Tokens
+
+Themes should be scoped to a class using the following convention, where `name` represents the name of your theme. To customize design tokens, for example, use the following syntax.
+
+```css
+.sl-theme-name { 
+  --sl-color-primary-hue: 290;
+  --sl-color-primary-saturation: 80%;
+
+  /* more design token customizations here */
+}
+```
+
+?> Your theme should avoid scoping custom properties to `:root`. The default theme does this to provide base styles that will apply to the page when no `sl-theme-` class is applied. If you want to be able to switch themes with classes, avoid using `:root` in your theme.
+
+### Components
+
+To customize individual components, use the following syntax.
+
+```css
+.sl-theme-name sl-button {
+  /* your custom button styles here */
+}
+```
+
+## Using a Theme
+
+If your theme adheres to the guidelines above, you can use it by importing the stylesheet adding the `sl-theme-name` class you chose to the `<body>` tag.
+
+```html
+<head>
+  <link rel="stylesheet" href="path/to/dark.css">
+</head>
+
+<body class="sl-theme-dark">
+  <!-- Everything inside will use the dark theme -->
+</body>
+```
+
+In fact, you can apply a theme class to any element on the page, not just the body. This lets you use multiple themes on the same page. Whether or not this is a good practice is left to the discretion of the designer.
+
+### Detecting the User's Color Scheme Preference
+
+Shoelace doesn't try to auto-detect light/dark mode preferences and, if you plan on distributing your theme, neither should yours. This should be done at the application level. As a best practice, to provide a dark theme in your own app, you should:
+
+- Try checking for [`prefers-color-scheme`](https://stackoverflow.com/a/57795495/567486) and use its value by default
+- Allow the user to override it in your app
+- Remember the user's preference and restore it on subsequent logins
+
+Not all apps support dark mode, so themes that use the `prefers-color-scheme` media query won't look right when the user prefers dark mode (e.g. light chrome and dark components). For distributed themes, avoid auto-detect and let users opt in to your theme.
+
+## Submitting a Theme
+
+**I am very interested in offering well-designed themes to complement this library.** To submit a theme for review, please [open an issue](https://github.com/shoelace-style/shoelace/issues/new) on GitHub with the theme linked or attached. Once approved, your theme will be showcased on this page.
+
+Please note the following requirements before submitting a theme.
+
+- Themes must be complete and of high quality
+- Themes must be available under a compatible open source license
+- If a theme is not original, the derivative work must be properly credited