update theme docs

shoelace-style · Aug 6, 2021 · 64b0e63 · 64b0e63
1 parent 95f6841
commit 64b0e63
Show file tree

Hide file tree

Showing 5 changed files with 66 additions and 59 deletions.
diff --git a/docs/getting-started/overview.md b/docs/getting-started/overview.md
@@ -119,7 +119,7 @@ Special thanks to the following projects and individuals that help make Shoelace
 - Component metadata is generated by the [Custom Elements Manifest Analyzer](https://github.com/open-wc/custom-elements-manifest)
 - Documentation is powered by [Docsify](https://docsify.js.org/)
 - CDN services are provided by [jsDelivr](https://www.jsdelivr.com/)
-- The default theme is based on color palettes from [Tailwind](https://tailwindcss.com/)
+- Color primitives are derived from [Tailwind](https://tailwindcss.com/)
 - Icons are courtesy of [Bootstrap Icons](https://icons.getbootstrap.com/)
 - The homepage illustration is courtesy of [unDraw](https://undraw.co/)
 - Positioning of menus, tooltips, et al is handled by [Popper.js](https://popper.js.org/)

diff --git a/docs/getting-started/themes.md b/docs/getting-started/themes.md
@@ -1,56 +1,43 @@
 # Themes
 
-Shoelace ships with a dark theme that complements the default light theme. You can even take things a step further by designing your own custom theme.
+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).
 
-The default theme is included as part of `themes/base.css` and should always be loaded first, even if you want to use another theme exclusively. The default theme contains important base tokens and utilities that many components rely on.
+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.
 
-## Dark Mode
-
-The dark theme uses an "inverted" color scale, so if you're using design tokens correctly, you'll get a decent dark mode for free.
-
-To install the dark theme, add the following to the `<head>` section of your app.
+If you're using the CDN, you can load the base theme by putting this tag in the `<head>` section of your page.
 
 ```html
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/dist/themes/dark.css">
+<!-- Required -->
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/dist/themes/base.css">
 ```
 
-**Themes must be activated after importing!** You can do this by adding the `sl-theme-[name]` class to the `<body>` element.
+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`.
 
-```html
-<body class="sl-theme-dark">
-  ...
-</body>
-```
-
-### Detecting the User's Color Scheme Preference
-
-Shoelace doesn't try to auto-detect the user's light/dark mode preference. This should be done at the application level. As a best practice, to provide a dark theme in your app, you should:
-
-- Check for [`prefers-color-scheme`](https://stackoverflow.com/a/57795495/567486) and use its value by default
-- Allow the user to override the setting in your app
-- Remember the user's preference and restore it on subsequent logins
-
-Shoelace avoids using the `prefers-color-scheme` media query because not all apps support dark mode, and it would break things for the ones that don't.
-
-## Creating a Theme
+## Creating Your Own 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 recommended way to create a theme is to piggyback on top of the default theme, adjusting design tokens and styling components as necessary to achieve the look you want. This makes your theme lightweight and "future proof", as upcoming versions of Shoelace may introduce new design tokens and components that your theme won't support initially. The default theme will account for these so components won't appear to be broken.
-
-Technically, you can roll your own theme from scratch without using the default theme as a baseline, but that approach isn't recommended.
+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.
 
-### Theme Classes
+### Scoping Your Styles
 
 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.
 
-Every selector in a theme must be scoped to the theme's class to ensure interoperability with other 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.
 
-### Design Tokens
+```css
+:host,
+.sl-theme-purple-power {
+  /* ... */
+}
+```
+
+### Customizing Design Tokens
 
-[Design tokens](/getting-started/customizing?id=design-tokens) give you a high-level way to customize Shoelace components. You can customize them in your theme as shown below.
+[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.
 
 ```css
+:host,
 .sl-theme-purple-power { 
   --sl-color-primary-50: #faf5ff;
   --sl-color-primary-100: #f3e8ff;
@@ -59,43 +46,63 @@ Every selector in a theme must be scoped to the theme's class to ensure interope
 }
 ```
 
-?> Avoid scoping design tokens to `:root`. You may notice that the default 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.
+!> 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.
 
-### Components
+### Customizing Components
 
-To customize individual components, use the following syntax. Available "parts" can be found in the CSS Parts section of each component's documentation.
+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.
 
 ```css
 .sl-theme-purple-power sl-button::part(base) {
   /* your custom button styles here */
 }
 ```
 
-?> Pay special attention to each component's CSS Parts API. You almost always need to use a `::part` selector when theming components!
+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.
 
-## Using a Custom Theme
+## Using Themes
 
-If a theme adheres to the guidelines above, you can use it by importing the stylesheet and activating it with the `sl-theme-[name]` class.
+If a theme adheres to the guidelines herein, you can import the stylesheet and activate it with the `sl-theme-{name}` class.
 
 ```html
-<head>
-  ...
-  <link rel="stylesheet" href="path/to/purple-power.css">
-</head>
+<html class="sl-theme-purple-power">
+  <head>
+    ...
+    <link rel="stylesheet" href="path/to/purple-power.css">
+  </head>
+
+  <body>
+    ...
+  </body>
+</html>
+```
+
+If desired, you can import multiple themes and change between them by toggling the class on `<html>`.
 
-<body class="sl-theme-purple-power">
-   ...
-</body>
+## Dark Theme
+
+The built-in dark theme uses an "inverted" color scale, so if you're using design tokens as intended, you'll get a decent dark mode for free. While this isn't the same as a professionally curated dark theme, it provides an excellent baseline for one and you're encouraged to customize it further depending on your specific needs.
+
+To install the dark theme, add the following to the `<head>` section of your page.
+
+```html
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/dist/themes/dark.css">
 ```
 
-If desired, you can import and activate more than one theme on the same page.
+To activate the theme, apply the `sl-theme-dark` class to the `<html>` element.
 
-## Submitting a Theme
+```html
+<html class="sl-theme-dark">
+  ...
+</html>
+```
+
+### Detecting the User's Color Scheme Preference
 
-**I am very interested in showcasing well-designed themes that 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.
+Shoelace doesn't try to auto-detect the user's light/dark mode preference. This should be done at the application level. As a best practice, to provide a dark theme in your app, you should:
 
-Please note the following requirements before submitting a theme.
+- Check for [`prefers-color-scheme`](https://stackoverflow.com/a/57795495/567486) and use its value by default
+- Allow the user to override the setting in your app
+- Remember the user's preference and restore it on subsequent logins
 
-- Themes must be complete and of high quality
-- Themes must be available under an open source license
-- Derivative works must be properly credited
+Shoelace avoids using the `prefers-color-scheme` media query because not all apps support dark mode, and it would break things for the ones that don't.
diff --git a/docs/resources/changelog.md b/docs/resources/changelog.md
@@ -307,7 +307,7 @@ The component API remains the same except for the changes noted below. Thanks fo
 - 🚨 BREAKING: removed the custom elements bundle (you can import ES modules directly)
 - 🚨 BREAKING: removed `getAnimationNames()` and `getEasingNames()` methods from `sl-animation` (you can import them from `utilities/animation.js` instead)
 - 🚨 BREAKING: removed the `sl-icon-library` component since it required imperative initialization (you can import the `registerIconLibrary()` function from `utilities/icon-library.js` instead)
-- 🚨 BREAKING: removed the experimental `sl-theme` component due to limitations (you should set the `sl-theme-[name]` class on the `<body>` instead)
+- 🚨 BREAKING: removed the experimental `sl-theme` component due to limitations (you should set the `sl-theme-{name}` class on the `<body>` instead)
 - 🚨 BREAKING: moved the base stylesheet from `dist/shoelace.css` to `dist/themes/base.css`
 - 🚨 BREAKING: moved `icons` into `assets/icons` to make future assets easier to colocate
 - 🚨 BREAKING: changed `getSymbol` property in `sl-rating` to `symbol` (it now accepts a string or a function that returns an icon name)

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 Default Theme
+### Importing the Base Theme
 
-The next step is to import Shoelace's default theme (stylesheet) in your `_app.js` file:
+The next step is to import Shoelace's base theme (stylesheet) in your `_app.js` file:
 
 ```css
 import '@shoelace-style/shoelace/dist/themes/base.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 Default Theme
+### Importing the Base Theme
 
-The next step is to import Shoelace's default theme (stylesheet) in `app/javascript/stylesheets/application.scss`.
+The next step is to import Shoelace's base theme (stylesheet) in `app/javascript/stylesheets/application.scss`.
 
 ```css
 @import '~@shoelace-style/shoelace/dist/themes/base';