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

Revise and add showcase to Themes doc (#456)

Browse Source 
* 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 <cory@abeautifulsite.net>
This commit is contained in:
Lindsay M
2025-01-08 17:33:09 -05:00
committed by GitHub
parent 21ed4f82b0
commit 6d31db57f6
4 changed files with 316 additions and 32 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
docs/_includes/preset-theme-selector.njk
View File

@@ -5,15 +5,15 @@
<span class="preset-theme-selector__text">Default</span>
</wa-button>
<wa-menu>
<wa-menu-item type="checkbox" value="default">Default</wa-menu-item>
<wa-menu-item type="checkbox" value="classic">Classic</wa-menu-item>
<wa-menu-item type="checkbox" value="awesome">Awesome</wa-menu-item>
<wa-menu-item type="checkbox" value="active">Active</wa-menu-item>
<wa-menu-item type="checkbox" value="brutalist">Brutalist</wa-menu-item>
<wa-menu-item data-alpha="remove" type="checkbox" value="glassy">Glassy</wa-menu-item>
<wa-menu-item type="checkbox" value="mellow">Mellow</wa-menu-item>
<wa-menu-item type="checkbox" value="tailspin">Tailspin</wa-menu-item>
<wa-menu-item data-alpha="remove" type="checkbox" value="playful">Playful</wa-menu-item>
<wa-menu-item data-alpha="remove" type="checkbox" value="premium">Premium</wa-menu-item>
<wa-menu-item type="checkbox" value="default" data-description="Your trusty companion, like a perfectly broken-in pair of jeans.">Default</wa-menu-item>
<wa-menu-item type="checkbox" value="classic" data-description="Timeless elegance that never goes out of style.">Classic</wa-menu-item>
<wa-menu-item type="checkbox" value="awesome" data-description="Punchy and vibrant, the rockstar of themes.">Awesome</wa-menu-item>
<wa-menu-item type="checkbox" value="active" data-description="Energetic and tactile, always in motion.">Active</wa-menu-item>
<wa-menu-item type="checkbox" value="brutalist" data-description="Sharp, raw, and unapologetically bold.">Brutalist</wa-menu-item>
<wa-menu-item data-alpha="remove" type="checkbox" value="glassy" data-description="TODO">Glassy</wa-menu-item>
<wa-menu-item type="checkbox" value="mellow" data-description="Soft and soothing, like a lazy Sunday morning.">Mellow</wa-menu-item>
<wa-menu-item type="checkbox" value="tailspin" data-description="Like a bird in flight, guiding you from there to here.">Tailspin</wa-menu-item>
<wa-menu-item data-alpha="remove" type="checkbox" value="playful" data-description="TODO">Playful</wa-menu-item>
<wa-menu-item data-alpha="remove" type="checkbox" value="premium" data-description="TODO">Premium</wa-menu-item>
</wa-menu>
</wa-dropdown>

13
docs/assets/scripts/preset-theme.js
View File

@@ -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();

3
docs/assets/styles/outline.css
View File

@@ -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;

312
docs/docs/themes.md
View File

@@ -3,57 +3,321 @@ title: Themes
description: Everything you need to know about theming Web Awesome.
layout: page-outline
---
<style>
wa-page > main {
max-width: 140ch;
.max-line-length {
max-width: 80ch;
}
}
.theme-showcase {
container: showcase / inline-size;
background-color: var(--wa-color-surface-lowered);
border-radius: var(--wa-border-radius-l);
min-height: 16lh;
height: 65vh;
max-height: 21lh;
padding: var(--wa-space-xl);
overflow: hidden;
margin-block-end: var(--wa-space-xl);
&.wa-flank {
--content-percentage: 55%;
--flank-size: 20ch;
}
}
.showcase-examples-wrapper {
inline-size: 100%;
block-size: 100%;
}
.showcase-examples {
column-gap: var(--wa-space-xl);
& wa-card {
display: inline-block;
width: 100%;
&:has(+ wa-card) {
margin-block-end: var(--wa-space-xl);
}
}
}
@supports not (zoom: 1) {
.showcase-examples {
column-count: 1;
}
@container showcase (width > 700px) {
.showcase-examples {
column-count: 2;
}
}
@container showcase (width > 900px) {
.showcase-examples {
column-count: 3;
}
}
}
@supports (zoom: 1) {
.showcase-examples {
column-count: 2;
zoom: 40%;
}
@container showcase (width > 400px) {
.showcase-examples {
zoom: 55%;
}
}
@container showcase (width > 700px) {
.showcase-examples {
zoom: 70%;
}
}
@container showcase (width > 800px) {
.showcase-examples {
column-count: 3;
zoom: 70%;
}
}
}
</style>
<div class="theme-showcase wa-flank wa-gap-xl">
<div>
<h2 id="theme-showcase-name" data-theme-name></h2>
<p id="theme-showcase-description" data-theme-description></p>
</div>
<div class="showcase-examples-wrapper">
<div class="showcase-examples">
<wa-card with-header with-footer>
<div slot="header" class="wa-split">
<h3 class="wa-heading-m">Your Cart</h3>
<wa-icon-button name="xmark"></wa-icon-button>
</div>
<div class="wa-stack wa-gap-xl">
<div class="wa-flank">
<wa-avatar shape="rounded" style="--size: 3em; --background-color: var(--wa-color-green-60); --text-color: var(--wa-color-green-95);">
<wa-icon slot="icon" name="sword-laser" family="duotone" style="font-size: 1.5em;"></wa-icon>
</wa-avatar>
<div class="wa-stack wa-gap-xs">
<div class="wa-split wa-gap-xs">
<strong>Initiate Saber</strong>
<strong>$179.99</strong>
</div>
<div class="wa-split wa-gap-xs wa-caption-m">
<span>Green</span>
<a href="#">Remove</a>
</div>
</div>
</div>
<wa-divider></wa-divider>
<div class="wa-flank">
<wa-avatar shape="rounded" style="--size: 3em; --background-color: var(--wa-color-teal-60); --text-color: var(--wa-color-teal-95);">
<wa-icon slot="icon" name="robot-astromech" family="duotone" style="font-size: 1.5em;"></wa-icon>
</wa-avatar>
<div class="wa-stack wa-gap-xs">
<div class="wa-split wa-gap-xs">
<strong>Repair Droid</strong>
<strong>$3,049.99</strong>
</div>
<div class="wa-split wa-gap-xs wa-caption-m">
<span>R-series</span>
<a href="#">Remove</a>
</div>
</div>
</div>
</div>
<div slot="footer" class="wa-stack">
<div class="wa-split">
<strong>Subtotal</strong>
<strong>$3,229.98</strong>
</div>
<span class="wa-caption-m">Shipping and taxes calculated at checkout.</span>
<wa-button variant="brand">
<wa-icon slot="prefix" name="shopping-bag"></wa-icon>
Checkout
</wa-button>
</div>
</wa-card>
<wa-card>
<wa-avatar shape="rounded" style="--size: 1.9lh; float: left; margin-right: var(--wa-space-m);">
<wa-icon slot="icon" name="hat-wizard" family="duotone" style="font-size: 1.75em;"></wa-icon>
</wa-avatar>
<p class="wa-body-l" style="margin: 0;">&ldquo;All we have to decide is what to do with the time that is given to us. There are other forces at work in this world, Frodo, besides the will of evil.&rdquo;</p>
</wa-card>
<wa-card>
<div class="wa-stack">
<h3 class="wa-heading-m">Sign In</h3>
<wa-input label="Email" placeholder="ddjarin@mandalore.gov">
<wa-icon slot="prefix" name="envelope" variant="regular"></wa-icon>
</wa-input>
<wa-input label="Password" type="password">
<wa-icon slot="prefix" name="lock" variant="regular"></wa-icon>
</wa-input>
<wa-button variant="brand">Sign In</wa-button>
<a href="#" class="wa-body-s">I forgot my password</a>
</div>
</wa-card>
<wa-card with-footer>
<div class="wa-stack">
<div class="wa-split">
<h3 class="wa-heading-m">To-Do</h3>
<wa-icon-button name="plus" label="Add task"></wa-icon-button>
</div>
<wa-checkbox checked>Umbrella for Adelard</wa-checkbox>
<wa-checkbox checked>Waste-paper basket for Dora</wa-checkbox>
<wa-checkbox checked>Pen and ink for Milo</wa-checkbox>
<wa-checkbox>Mirror for Angelica</wa-checkbox>
<wa-checkbox>Silver spoons for Lobelia</wa-checkbox>
</div>
<div slot="footer">
<a href="">View all completed</a>
</div>
</wa-card>
<wa-card>
<div class="wa-stack">
<div class="wa-frame wa-border-radius-m" style="align-self: center; max-inline-size: 25ch;">
<img src="https://images.unsplash.com/photo-1667514627762-521b1c815a89?q=20" alt="Album art">
</div>
<div class="wa-flank:end wa-align-items-start">
<div class="wa-stack wa-gap-3xs">
<div class="wa-cluster wa-gap-xs" style="height: 2.25em;">
<strong>The Stone Troll</strong>
<small><wa-badge variant="neutral" appearance="filled">E</wa-badge></small>
</div>
<span class="wa-caption-m">Samwise G</span>
</div>
<wa-icon-button name="ellipsis" label="Options"></wa-icon-button>
</div>
<div class="wa-stack wa-gap-2xs">
<wa-progress-bar value="34" style="height: 0.5em"></wa-progress-bar>
<div class="wa-split">
<span class="wa-caption-xs">1:01</span>
<span class="wa-caption-xs">-1:58</span>
</div>
</div>
<div class="wa-grid wa-align-items-center" style="--min-column-size: 1em; justify-items: center;">
<wa-icon-button name="backward" label="Skip backward"></wa-icon-button>
<wa-icon-button name="pause" style="font-size: var(--wa-font-size-2xl);" label="Pause"></wa-icon-button>
<wa-icon-button name="forward" label="Skip forward"></wa-icon-button>
</div>
</div>
</wa-card>
<wa-card>
<div class="wa-stack">
<h3 class="wa-heading-m">Chalmun's Spaceport Cantina</h3>
<div class="wa-cluster wa-gap-xs">
<wa-rating value="4.6" read-only></wa-rating>
<strong>4.6</strong>
<span>(419 reviews)</span>
</div>
<div class="wa-cluster wa-gap-xs">
<div class="wa-cluster wa-gap-3xs">
<wa-icon name="dollar" style="color: var(--wa-color-green-60);"></wa-icon>
<wa-icon name="dollar" style="color: var(--wa-color-green-60);"></wa-icon>
<wa-icon name="dollar" style="color: var(--wa-color-green-60);"></wa-icon>
</div>
<span class="wa-caption-m">&bull;</span>
<wa-tag size="small">Cocktail Bar</wa-tag>
<wa-tag size="small">Gastropub</wa-tag>
<wa-tag size="small">Local Fare</wa-tag>
<wa-tag size="small">Gluten Free</wa-tag>
</div>
<div class="wa-flank wa-gap-xs">
<wa-icon name="location-dot"></wa-icon>
<a href="#" class="wa-caption-m">Mos Eisley, Tatooine</a>
</div>
</div>
</wa-card>
</div>
</div>
</div>
<div class="max-line-length">
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 <wa-badge>Pro</wa-badge>:
- **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
<link rel="stylesheet" href="{% cdnUrl 'styles/themes/default.css' %}" />
```
## 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 `<head>` 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 `<head>` of your page to import the **default** theme:
```html
<link rel="stylesheet" href="https://early.webawesome.com/webawesome@3.0.0-alpha.4/dist/styles/themes/default.css" />
<link rel="stylesheet" href="{% cdnUrl 'styles/themes/default.css' %}" />
```
Or import the **classic** theme:
Or the **Classic** theme:
```html
<link rel="stylesheet" href="https://early.webawesome.com/webawesome@3.0.0-alpha.4/dist/styles/themes/classic.css" />
<link rel="stylesheet" href="{% cdnUrl 'styles/themes/classic.css' %}" />
```
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 `<html>` element on your page, like this example for the default theme:
Or any of our Pro themes, like **Brutalist**:
```html
<link rel="stylesheet" href="{% cdnUrl 'styles/themes/brutalist.css' %}" />
```
To activate the dark color scheme of any theme, apply the class `wa-dark` to the `<html>` element on your page, like this example for the default theme:
```html
<html class="wa-theme-default wa-dark">
<head>
@@ -66,7 +330,7 @@ When importing either theme, the light color scheme is activated by default.
</html>
```
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
<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.
</div>