update theme docs

shoelace-style · Aug 10, 2021 · c356ec4 · c356ec4
1 parent 23a7268
commit c356ec4
Show file tree

Hide file tree

Showing 5 changed files with 80 additions and 53 deletions.
diff --git a/docs/_sidebar.md b/docs/_sidebar.md
@@ -2,8 +2,8 @@
   - [Overview](/)
   - [Installation](/getting-started/installation)
   - [Usage](/getting-started/usage)
-  - [Customizing](/getting-started/customizing)
   - [Themes](/getting-started/themes)
+  - [Customizing](/getting-started/customizing)
 
 - Resources
   - [Community](/resources/community)

diff --git a/docs/getting-started/themes.md b/docs/getting-started/themes.md
@@ -1,83 +1,110 @@
 # Themes
 
-Shoelace is designed to be highly customizable through pure CSS. A simple, pleasing base theme is provided as well as an official [dark theme](#dark-mode).
+Shoelace is designed to be highly customizable through pure CSS. Out of the box, you can choose from a light or dark theme. Alternatively, you can design your own theme from scratch.
 
-The base theme must always be loaded first, even if you want to use another theme exclusively. It contains important, reusable design tokens that many components rely on.
+A theme is nothing more than a stylesheet that uses the Shoelace API to define design tokens and apply custom styles to 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).
 
-If you're using the CDN, you can load the base theme by putting this tag in the `<head>` section of your page.
+For developers, built-in themes are also available as JavaScript modules that export [Lit CSSResult](https://lit.dev/docs/api/styles/#CSSResult) objects. You can find them in `dist/themes/*.styles.js`.
 
-```html
-<!-- Required -->
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/dist/themes/base.css">
+## Theme Basics
+
+All themes are scoped to classes using the `sl-theme-{name}` convention, where `{name}` is a lowercase, hyphen-delimited value representing the name of the theme. The included light and dark themes use `sl-theme-light` and `sl-theme-dark`, respectively. A custom theme called "Purple Power", for example, would use the `sl-theme-purple-power` class. 
+
+Every selector must be scoped to the theme's class to ensure interoperability with other themes. You should also scope them to `:host` so they can be imported and applied to custom element shadow roots.
+
+```css
+:host,
+.sl-theme-purple-power {
+  /* ... */
+}
 ```
 
-For developers, themes are also available as JavaScript modules that export [Lit CSSResult](https://lit.dev/docs/api/styles/#CSSResult) objects. You can find them in `dist/themes/*.styles.js`.
+### Activating Themes
 
-## Creating Your Own Theme
+To activate a theme, import it and apply the theme's class to the `<html>` element. This example imports and activates the dark theme, or "dark mode."
 
-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).
+```html
+<html class="sl-theme-dark">
+  <head>
+    <link rel="stylesheet" href="path/to/shoelace/dist/themes/dark.css">
+  </head>
 
-The recommended way to create a theme is with a separate stylesheet that piggybacks on top of the base theme. You can [customize design tokens](/getting-started/customizing#design-tokens) and [style components](/getting-started/customizing#component-parts) to achieve the look you want. By working _with_ the base theme instead of replacing it, your theme will remain lightweight and "future proof", as upcoming versions of Shoelace may introduce new design tokens that your theme won't have.
+  <body>
+    ...
+  </body>
+</html>
+```
 
-### Scoping Your Styles
+?> There is one exception to this rule — the light theme _does not_ need to be activated. For convenience, the light theme is scoped to `:root` and will be activated by default when imported.
 
-All theme classes must use the `sl-theme-{name}` convention, where `{name}` is a lowercase, hyphen-delimited value representing the name of your theme. For example, a theme called "Purple Power" would use the `sl-theme-purple-power` class.
+### Using Multiple Themes
 
-Every selector in a theme must be scoped to the theme's class as to ensure interoperability with other themes. You should also scope them to `:host` so they can easily be imported and applied to third-party components.
+You can activate themes on various containers throughout the page. This example uses the light theme with a dark-themed sidebar.
 
-```css
-:host,
-.sl-theme-purple-power {
-  /* ... */
-}
+```html
+<html>
+  <head>
+    <link rel="stylesheet" href="path/to/shoelace/dist/themes/light.css">
+    <link rel="stylesheet" href="path/to/shoelace/dist/themes/dark.css">
+  </head>
+
+  <body>
+    <nav class="sl-theme-dark">
+      <!-- dark-themed sidebar -->
+    </nav>
+
+    <!-- light-themed content -->
+  </body>
+</html>
 ```
 
-### Customizing Design Tokens
+## Creating Themes
+
+There are two ways to create themes. The easiest way is to customize a built-in theme. The advanced way is to create a new theme from scratch. Which method you choose depends on your project's requirements and the amount of effort you're willing to commit to.
+
+### Customizing a Built-in Theme
+
+The easiest way to customize Shoelace is to override one of the built-in themes. You can do this by importing the light or dark theme as-is, then creating a separate stylesheet that overrides the [design tokens](/getting-started/customizing#design-tokens) and adds [component styles](/getting-started/customizing#component-parts) to your liking. You must import your theme _after_ the built-in theme.
 
-[Design tokens](/getting-started/customizing#design-tokens) give you a high-level way to customize Shoelace components. You can override them in your theme as shown below.
+If you're customizing the light theme, you should scope your styles to the following selectors.
 
 ```css
-:host,
-.sl-theme-purple-power { 
-  --sl-color-primary-50: #faf5ff;
-  --sl-color-primary-100: #f3e8ff;
-  --sl-color-primary-200: #e9d5ff;
-  /* ... */
+:root, 
+:host, 
+.sl-theme-light {
+  /* your custom styles here */
 }
 ```
 
-!> Avoid scoping design tokens to `:root`. You may notice that the base theme does this, but that's because it's not technically a theme — it's a set of design tokens and base styles that themes can use as a foundation to build upon.
-
-### Customizing Components
-
-To customize individual components, use the following syntax to target [component parts](/getting-started/customizing#component-parts). Available parts can be found in the "CSS Parts" section of each component's documentation.
+If you're customizing the dark theme, you should scope your styles to the following selectors.
 
 ```css
-.sl-theme-purple-power sl-button::part(base) {
-  /* your custom button styles here */
+:host,
+.sl-theme-dark {
+  /* your custom styles here */
 }
 ```
 
-Some components offer additional customizations through [custom properties](http://localhost:4000/#/getting-started/customizing?id=custom-properties). If available, they will be listed in the "CSS Custom Properties" section of the documentation.
+By customizing a built-in theme, you'll maintain a smaller stylesheet containing only the changes you've made. Contrast this to [creating a new theme](#creating-a-new-theme), where you need to explicitly define every design token required by the library. This approach is more "future-proof," as new design tokens that emerge in subsequent versions of Shoelace will be accounted for by the built-in theme.
 
-## Using Themes
+While this may be easier to maintain, the drawback is that your theme modifies a built-in theme and thus can't be activated independently.
 
-If a theme adheres to the guidelines herein, you can import the stylesheet and activate it with the `sl-theme-{name}` class.
+### Creating a New Theme
 
-```html
-<html class="sl-theme-purple-power">
-  <head>
-    ...
-    <link rel="stylesheet" href="path/to/purple-power.css">
-  </head>
+Creating a new theme is more of an undertaking than [customizing an existing one](#customizing-a-built-in-theme). At a minimum, you must implement all of the required design tokens. The easiest way to do this is by "forking" one of the built-in themes and modifying it from there.
 
-  <body>
-    ...
-  </body>
-</html>
+Start by changing the selector to match your theme's name. Assuming your new theme is called "Purple Power", your theme should be scoped like this.
+
+```css
+:host,
+.sl-theme-purple-power {
+  /* your custom styles here */
+}
 ```
 
-If desired, you can import multiple themes and change between them by toggling the class on `<html>`.
+By creating a new theme, you won't be relying on a built-in theme as a foundation. Because the theme is decoupled from the built-ins, you can activate it independently as an alternative to the built-ins. This is the recommended approach if you're looking to open source your theme for others to use.
+
+You will, however, need to maintain your theme more carefully, as new versions of Shoelace may introduce new design tokens that your theme won't have accounted for. Because of this, it's recommended that you clearly specify which version(s) of Shoelace your theme is designed to work with and keep it up to date as new versions of Shoelace are released.
 
 ## Dark Theme
 

diff --git a/docs/getting-started/usage.md b/docs/getting-started/usage.md
@@ -145,7 +145,7 @@ Fortunately, there's a package called [@shoelace-style/react](https://www.npmjs.
 npm install @shoelace-style/react
 ```
 
-Include the base theme and any components you want to use in your app.
+Include the default theme and any components you want to use in your app.
 
 ```jsx
 import '@shoelace-style/shoelace/dist/themes/light.css';

diff --git a/docs/tutorials/integrating-with-nextjs.md b/docs/tutorials/integrating-with-nextjs.md
@@ -17,9 +17,9 @@ To get started using Shoelace with NextJS, the following packages must be instal
 yarn add @shoelace-style/shoelace @shoelace-style/react-wrapper copy-webpack-plugin next-compose-plugins next-transpile-modules
 ```
 
-### Importing the Base Theme
+### Importing the Default Theme
 
-The next step is to import Shoelace's base theme (stylesheet) in your `_app.js` file:
+The next step is to import Shoelace's default theme (stylesheet) in your `_app.js` file:
 
 ```css
 import '@shoelace-style/shoelace/dist/themes/light.css';

diff --git a/docs/tutorials/integrating-with-rails.md b/docs/tutorials/integrating-with-rails.md
@@ -18,9 +18,9 @@ To get started using Shoelace with Rails, the following packages must be install
 yarn add @shoelace-style/shoelace copy-webpack-plugin
 ```
 
-### Importing the Base Theme
+### Importing the Default Theme
 
-The next step is to import Shoelace's base theme (stylesheet) in `app/javascript/stylesheets/application.scss`.
+The next step is to import Shoelace's default theme (stylesheet) in `app/javascript/stylesheets/application.scss`.
 
 ```css
 @import '~@shoelace-style/shoelace/dist/themes/base';