From 6d31db57f63cfb9b0a54688ce1f6c36d633468f7 Mon Sep 17 00:00:00 2001 From: Lindsay M <126139086+lindsaym-fa@users.noreply.github.com> Date: Wed, 8 Jan 2025 17:33:09 -0500 Subject: [PATCH] Revise and add showcase to Themes doc (#456) * Initial progress * Make responsive * quick fix to show theme name/description * Small styling tweaks * Documentation updates * Revisions and improvements * Avoid using static URLs 'cause that's ridiculous --------- Co-authored-by: Cory LaViska --- docs/_includes/preset-theme-selector.njk | 20 +- docs/assets/scripts/preset-theme.js | 13 + docs/assets/styles/outline.css | 3 + docs/docs/themes.md | 312 +++++++++++++++++++++-- 4 files changed, 316 insertions(+), 32 deletions(-) diff --git a/docs/_includes/preset-theme-selector.njk b/docs/_includes/preset-theme-selector.njk index df7a7ad3a..e4793d6eb 100644 --- a/docs/_includes/preset-theme-selector.njk +++ b/docs/_includes/preset-theme-selector.njk @@ -5,15 +5,15 @@ Default - Default - Classic - Awesome - Active - Brutalist - Glassy - Mellow - Tailspin - Playful - Premium + Default + Classic + Awesome + Active + Brutalist + Glassy + Mellow + Tailspin + Playful + Premium diff --git a/docs/assets/scripts/preset-theme.js b/docs/assets/scripts/preset-theme.js index ef868db01..c8162704b 100644 --- a/docs/assets/scripts/preset-theme.js +++ b/docs/assets/scripts/preset-theme.js @@ -64,6 +64,12 @@ }); } + // Updates any element on the page with [data-theme-name] and [data-theme-description] with the current themes info + function updateThemeNameAndDescription(name, description) { + document.querySelectorAll('[data-theme-name]').forEach(el => (el.textContent = name)); + document.querySelectorAll('[data-theme-description]').forEach(el => (el.textContent = description)); + } + let presetTheme = window.getPresetTheme(); // Selection is not preserved when changing page, so update when opening dropdown @@ -78,8 +84,15 @@ const menu = event.target.closest('.preset-theme-selector wa-menu'); if (!menu) return; setPresetTheme(event.detail.item.value); + updateThemeNameAndDescription(event.detail.item.textContent, event.detail.item.getAttribute('data-description')); }); + // Set the initial preset name/description in the UI by grabbing it from the dropdown (ugly, but quick) + const currentTheme = document.querySelector(`.preset-theme-selector wa-menu-item[value="${presetTheme}"]`); + if (currentTheme) { + updateThemeNameAndDescription(currentTheme.textContent, currentTheme.getAttribute('data-description')); + } + // Update the color scheme when the preference changes window.matchMedia('(prefers-preset-theme: dark)').addEventListener('change', () => setPresetTheme(presetTheme)); updateSelection(); diff --git a/docs/assets/styles/outline.css b/docs/assets/styles/outline.css index 954d60b68..164a2b087 100644 --- a/docs/assets/styles/outline.css +++ b/docs/assets/styles/outline.css @@ -31,6 +31,9 @@ } @media screen and (max-width: 1199px) { + wa-page [slot='aside'] { + display: none; + } #outline { padding-block: 0.25rem; margin-block-end: -1rem; diff --git a/docs/docs/themes.md b/docs/docs/themes.md index be11b5a65..abd3a8af9 100644 --- a/docs/docs/themes.md +++ b/docs/docs/themes.md @@ -3,57 +3,321 @@ title: Themes description: Everything you need to know about theming Web Awesome. layout: page-outline --- + + +
+
+

+

+
+
+
+ + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
Themes are collections of pre-defined CSS custom properties that thread through every Web Awesome component and pattern. -Web Awesome includes two pre-made themes: -- **Default** for a clean look that prioritizes accessibility and performance -- **Classic** for the look and feel of Shoelace with more accessible color pairings +Web Awesome Free includes these pre-made themes: +- **Default** (`default.css`) for a clean look that prioritizes accessibility and performance +- **Classic** (`classic.css`) for the look and feel of Shoelace with more accessible color pairings +- **Awesome** (`awesome.css`) for the familiar, vibrant styles from your friends at Font Awesome + +Even more themes are available with Web Awesome Pro: +- **Active** (`active.css`) +- **Brutalist** (`brutalist.css`) +- **Mellow** (`mellow.css`) +- **Tailspin** (`tailspin.css`) + +To get started right away, include the following in your project, replacing `default.css` at the end with your preferred pre-made theme: +```html + +``` + ## What's a Theme? -Themes are a standard collection of [CSS custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/--*) that cover all styles from colors to transitions. We use these custom properties throughout Web Awesome components to ensure a cohesive look and feel. Our [Theming pages](/docs/theming/) document these styles so that you can use them freely throughout your project and customize them as needed. +Themes are a collection of standardized [CSS custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/--*) that cover a range of styles from colors to transitions. We use these custom properties throughout Web Awesome components for a cohesive look and feel. Our [Theming pages](/docs/theming/) document these styles so that you can use them freely throughout your project and customize them as needed. + +Themes are scoped to unique classes, such as `wa-theme-default` or `wa-theme-classic`. Scoping to unique classes allows you to import multiple themes and use them interchangeably without collisions. + +Each theme may also include both light and dark color schemes with the classes `wa-light` and `wa-dark`. +You can use these classes to apply a specific color scheme to an entire page or just a section. +In pre-made themes, we use a light color scheme by default. -Themes are scoped to unique classes for each color scheme, such as `wa-theme-default`. -You can apply the dark version of each theme by using the class `wa-dark`. -Scoping to unique classes allows you to import multiple themes and use them interchangeably without collisions, while scoping to `:host` ensures the styles are applied to the shadow roots of custom elements. Additionally, styles may be scoped to the `:root` selector to be activated automatically. -For pre-made themes, *all* custom properties are scoped to both `:root` and the theme class (`wa-theme-default` or `wa-theme-classic`), -activating the light color scheme by default. +For pre-made themes, *all* custom properties are scoped to `:root`, the theme class, and `wa-light`. + +Finally, we scope themes to `:host` and `:host-context()` to ensure the styles are applied to the shadow roots of custom elements. For example, the default theme is set up like this: ```css :root, :host, -.wa-theme-default { +.wa-theme-default, +.wa-light { /* all CSS custom properties for color, typography, space, etc. */ } .wa-dark, :host-context(.wa-dark) { - /* subset of CSS custom properties for color */ + /* subset of CSS custom properties for a dark color scheme */ } ``` ## Using Themes -You can import the default and classic themes from the Web Awesome CDN. Simply add the following code to the `` of your page to import the **default** theme: +You can import pre-made themes from the Web Awesome CDN. Simply add the following code to the `` of your page to import the **default** theme: ```html - + ``` -Or import the **classic** theme: +Or the **Classic** theme: ```html - + ``` -Both the default and classic themes include both light and dark color schemes. -When importing either theme, the light color scheme is activated by default. - To activate the dark color scheme, apply the class `wa-dark` to the `` element on your page, like this example for the default theme: +Or any of our Pro themes, like **Brutalist**: + +```html + +``` + + To activate the dark color scheme of any theme, apply the class `wa-dark` to the `` element on your page, like this example for the default theme: ```html @@ -66,7 +330,7 @@ When importing either theme, the light color scheme is activated by default. ``` -Because themes are scoped to specific classes, you can activate different color schemes or entire themes on different containers throughout the page. This example uses the default theme with a dark sidebar. +Because themes are scoped to specific classes, you can use different color schemes or even different themes throughout the page. Here, we use the default theme with a dark sidebar: ```html @@ -97,7 +361,8 @@ If you're customizing the default light styles, scope your styles to the followi ```css :root, :host, -.wa-theme-default { +.wa-theme-default, +.wa-light { /* your custom styles here */ } ``` @@ -111,7 +376,7 @@ If you're customizing the default dark styles, scope your styles to the followin } ``` -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. +By customizing a built-in theme, you'll maintain a smaller stylesheet containing only your changes. 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. @@ -122,8 +387,10 @@ Creating a new theme is more of an undertaking than [customizing an existing one 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 +:root, :host, -.wa-theme-purple-power { +.wa-theme-purple-power, +.wa-light { /* your custom styles here */ } ``` @@ -141,3 +408,4 @@ Web Awesome's default theme has both light and dark styles built in. However, We - Remember the user's preference and restore it on subsequent logins Web Awesome 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. +
\ No newline at end of file