js/webawesome
1
0
Fork 0
mirror of https://github.com/shoelace-style/webawesome.git synced 2026-01-12 12:09:26 +00:00
Code Issues Packages Projects Releases Wiki Activity

update Themes doc

Browse Source
This commit is contained in:
lindsaym-fa
2024-06-13 17:59:50 -04:00
parent 089265a022
commit c37f86bbd6
1 changed files with 19 additions and 41 deletions
Download Patch File Download Diff File Expand all files Collapse all files

60
docs/docs/themes.md
View File

@@ -4,9 +4,9 @@ description: Everything you need to know about theming Web Awesome.
layout: page.njk
---
Web Awesome 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.
Web Awesome is designed to be highly customizable through pure CSS. Out of the box, the default theme includes both light and dark styles. Alternatively, you can design your own theme.
A theme is nothing more than a stylesheet that uses the Web Awesome 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).
In essence, a theme is a stylesheet that uses the Web Awesome API to define custom properties 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).
:::info
For component 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 `/%NPMDIR%/themes/*.styles.js`.
@@ -14,7 +14,7 @@ For component developers, built-in themes are also available as JavaScript modul
## Theme Basics
All themes are scoped to classes using the `wa-theme-{name}` convention, where `{name}` is a lowercase, hyphen-delimited value representing the name of the theme. The included light and dark themes use `wa-theme-default-light` and `wa-theme-default-dark`, respectively. A custom theme called "Purple Power", for example, would use a class called `wa-theme-purple-power`
All themes are scoped to classes using the format `wa-theme-{name}`, where `{name}` is a lowercase, hyphen-delimited value representing the name of the theme. The included theme uses `wa-theme-default-light` and `wa-theme-default-dark` for light and dark styles, respectively. A custom theme called "Purple Power", for example, would use a class called `wa-theme-purple-power`.
All selectors 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.
@@ -25,14 +25,16 @@ All selectors must be scoped to the theme's class to ensure interoperability wit
}
```
In the default theme, all CSS custom properties that make up Web Awesome's theming API, from colors to transitions, are scoped to both `:root` and `wa-theme-default-light`. `wa-theme-default-dark`, on the other hand, only defines a subset of custom properties for colors. This ensures that non-color styles only need to be defined once for the theme, regardless of whether the color scheme is light or dark.
### Activating Themes
To activate a theme, import it and apply the theme's class to the `<html>` element. This example imports and activates the built-in dark theme.
To activate a theme, import it and apply the theme's class to the `<html>` element. This example imports and activates the default theme with dark styles.
```html
<html class="wa-theme-default-dark">
<head>
<link rel="stylesheet" href="path/to/shoelace/%NPMDIR%/themes/dark.css" />
<link rel="stylesheet" href="path/to/webawesome/%NPMDIR%/themes/default.css" />
</head>
<body>
@@ -42,18 +44,17 @@ To activate a theme, import it and apply the theme's class to the `<html>` eleme
```
:::info
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.
There is one exception to this rule — the default light styles _do not_ need to be activated. For convenience, these styles are scoped to `:root` and will be activated by default when imported.
:::
### Using Multiple Themes
You can activate themes on various containers throughout the page. This example uses the light theme with a dark-themed sidebar.
You can activate different themes and styles on various containers throughout the page. This example uses the default theme with a dark sidebar.
```html
<html>
<head>
<link rel="stylesheet" href="path/to/shoelace/%NPMDIR%/themes/default.css" />
<link rel="stylesheet" href="path/to/shoelace/%NPMDIR%/themes/dark.css" />
</head>
<body>
@@ -70,13 +71,13 @@ It's for this reason that themes must be scoped to specific classes.
## 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.
There are two ways to create themes. The easiest way is to customize the default 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 invest.
### Customizing a Built-in Theme
The easiest way to customize Web Awesome 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 [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.
Overriding the default theme is the easiest way to customize Web Awesome. You can do this by importing the default theme as-is, then creating a separate stylesheet that overrides [the theming API](/getting-started/customizing#design-tokens) and adds [component styles](/getting-started/customizing#component-parts) to your liking. You must import your theme _after_ the default theme.
If you're customizing the light theme, you should scope your styles to the following selectors.
If you're customizing the default light styles, scope your styles to the following selectors.
```css
:root,
@@ -86,7 +87,7 @@ If you're customizing the light theme, you should scope your styles to the follo
}
```
If you're customizing the dark theme, you should scope your styles to the following selectors.
If you're customizing the default dark styles, scope your styles to the following selectors.
```css
:host,
@@ -95,13 +96,13 @@ If you're customizing the dark theme, you should scope your styles to the follow
}
```
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 Web Awesome will be accounted for by the built-in theme.
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 custom property required by the library. This approach is more "future-proof," as new design tokens that emerge in subsequent versions of Web Awesome will be accounted for by built-in themes.
While this approach is easier to maintain, the drawback is that your theme can't be activated independently — it's tied to the built-in theme you're extending.
### Creating a New Theme
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.
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 custom properties. The easiest way to do this is by "forking" a built-in theme and modifying it from there.
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.
@@ -112,36 +113,13 @@ Start by changing the selector to match your theme's name. Assuming your new the
}
```
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.
By creating a new theme, you won't be relying on a built-in theme as a foundation. Because of this, you can activate it independently as an alternative to the default theme. 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 Web Awesome 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 Web Awesome your theme is designed to work with and keep it up to date as new versions of Web Awesome are released.
You will, however, need to maintain your theme more carefully, as new versions of Web Awesome change the theming API in ways that your theme won't have accounted for. It's recommended that you clearly specify which version(s) of Web Awesome your theme is designed to work with and keep it up to date as new versions of Web Awesome are released.
## Dark Theme
## Detecting Color Scheme Preference
The built-in dark theme uses an inverted color scale so, if you're using design tokens as intended, you'll get 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 depending on your needs.
The dark theme works by taking the light theme's [color tokens](/tokens/color) and "flipping" the scale so 100 becomes 900, 200 becomes 800, 300 becomes 700, etc. Next, the luminance of each primitive was fine-tuned to avoid true black, which is often undesirable in dark themes, and provide a richer experience. The result is a custom dark palette that complements the light theme and makes it easy to offer light and dark modes with minimal effort.
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%/%CDNDIR%/themes/dark.css"
/>
```
To activate the theme, apply the `wa-theme-default-dark` class to the `<html>` element.
```html
<html class="wa-theme-default-dark">
...
</html>
```
### Detecting the User's Color Scheme Preference
Web Awesome 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:
Web Awesome's default theme has both light and dark styles built in. However, Web Awesome 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