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

Themes category in docs (#477)

Browse Source 
Co-authored-by: Lindsay M <126139086+lindsaym-fa@users.noreply.github.com>
Co-authored-by: lindsaym-fa <dev@lindsaym.design>
This commit is contained in:
Lea Verou
2025-01-13 13:14:12 -05:00
committed by GitHub
parent 6822b25772
commit a07f6280a3
30 changed files with 623 additions and 474 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/_includes/base.njk
View File

@@ -6,7 +6,7 @@
<script type="module" src="/assets/scripts/code-examples.js"></script>
<script type="module" src="/assets/scripts/copy-code.js"></script>
<script type="module" src="/assets/scripts/theme-picker.js"></script>
<script type="module" src="/assets/scripts/scroll.js"></script>
<script type="module" src="/assets/scripts/turbo.js"></script>
<script type="module" src="/assets/scripts/search.js"></script>

2
docs/_includes/head.njk
View File

@@ -28,6 +28,7 @@
{# Web Awesome #}
<script type="module" src="/dist/webawesome.ssr-loader.js"></script>
<script type="module" src="/assets/scripts/theme-picker.js"></script>
{# Preset Theme #}
<link id="theme-stylesheet" rel="stylesheet" id="theme-stylesheet" href="/dist/styles/themes/{{ forceTheme or 'default' }}.css" render="blocking" fetchpriority="high" />
{% if not forceTheme %}
@@ -44,6 +45,7 @@ if (localStorage.presetTheme) {
link.after(newLink);
}
</script>
<script type="module" src="/assets/scripts/preset-theme-picker.js"></script>
{% endif %}
<link rel="stylesheet" href="/dist/styles/webawesome.css" />

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

@@ -1,14 +1,9 @@
{# Preset theme selector #}
<wa-select appearance="filled" size="small" value="default" pill class="preset-theme-selector">
<wa-icon slot="prefix" name="paintbrush" variant="regular"></wa-icon>
<wa-option value="default" data-description="Your trusty companion, like a perfectly broken-in pair of jeans.">Default</wa-option>
<wa-option value="classic" data-description="Timeless elegance that never goes out of style.">Classic</wa-option>
<wa-option value="awesome" data-description="Punchy and vibrant, the rockstar of themes.">Awesome</wa-option>
<wa-option value="active" data-description="Energetic and tactile, always in motion.">Active</wa-option>
<wa-option value="brutalist" data-description="Sharp, square, and unapologetically bold.">Brutalist</wa-option>
<wa-option data-alpha="remove" value="glassy" data-description="TODO">Glassy</wa-option>
<wa-option value="mellow" data-description="Soft and soothing, like a lazy Sunday morning.">Mellow</wa-option>
<wa-option value="tailspin" data-description="Like a bird in flight, guiding you from there to here.">Tailspin</wa-option>
<wa-option data-alpha="remove" value="playful" data-description="TODO">Playful</wa-option>
<wa-option data-alpha="remove" value="premium" data-description="TODO">Premium</wa-option>
{% for theme in collections.theme | sort %}
<wa-option value="{{ theme.page.fileSlug }}"{{ ' data-alpha="remove"' if theme.noAlpha }}>
{{ theme.data.title }}
</wa-option>
{% endfor %}
</wa-select>

2
docs/_includes/sidebar.njk
View File

@@ -3,7 +3,6 @@
<ul>
<li><a href="/docs/installation">Installation</a></li>
<li><a href="/docs/usage">Usage</a></li>
<li><a href="/docs/themes">Themes</a></li>
<li><a href="/docs/customizing">Customizing</a></li>
<li><a href="/docs/form-controls">Form Controls</a></li>
<li><a href="/docs/localization">Localization</a></li>
@@ -20,6 +19,7 @@
</ul>
{% for tag, title in {
'themes': 'Themes',
'components': 'Components',
'native': 'Native Styles',
'utilities': 'Style Utilities',

14
docs/_includes/status.njk
View File

@@ -1,25 +1,25 @@
{% if since -%}
<wa-badge variant="neutral">Since {{ since }}</wa-badge>
{%- endif %}
{% endif -%}
{% if status -%}
{%- if status %}
{%- if status == "wip" %}
<wa-badge variant="danger">
<wa-icon name="pickaxe"></wa-icon>
Work In Progress
</wa-badge>
{%- elif status == "experimental" -%}
{%- elif status == "experimental" %}
<wa-badge variant="warning">
<wa-icon name="flask"></wa-icon>
Experimental
</wa-badge>
{%- elif status == "stable" -%}
{%- elif status == "stable" %}
<wa-badge variant="brand">Stable</wa-badge>
{%- else %}
<wa-badge>{{ status}}</wa-badge>
{%- endif %}
{%- endif -%}
{%- endif %}
{% if isPro -%}
{%- if isPro %}
<wa-badge class="pro">PRO</wa-badge>
{%- endif %}
{%- endif -%}

144
docs/_includes/theme-showcase.njk Normal file
View File

@@ -0,0 +1,144 @@
<div class="showcase-examples-wrapper" aria-hidden="true" data-no-outline>
<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" tabindex="-1"></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-2xs">
<div class="wa-split wa-gap-2xs">
<strong>Initiate Saber</strong>
<strong>$179.99</strong>
</div>
<div class="wa-split wa-gap-2xs wa-caption-m">
<span>Green</span>
<a href="#" tabindex="-1">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-2xs">
<div class="wa-split wa-gap-2xs">
<strong>Repair Droid</strong>
<strong>$3,049.99</strong>
</div>
<div class="wa-split wa-gap-2xs wa-caption-m">
<span>R-series</span>
<a href="#" tabindex="-1">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 tabindex="-1" 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 tabindex="-1" label="Email" placeholder="ddjarin@mandalore.gov">
<wa-icon slot="prefix" name="envelope" variant="regular"></wa-icon>
</wa-input>
<wa-input tabindex="-1" label="Password" type="password">
<wa-icon slot="prefix" name="lock" variant="regular"></wa-icon>
</wa-input>
<wa-button tabindex="-1" variant="brand">Sign In</wa-button>
<a href="#" tabindex="-1" 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 tabindex="-1" name="plus" label="Add task"></wa-icon-button>
</div>
<wa-checkbox tabindex="-1" checked>Umbrella for Adelard</wa-checkbox>
<wa-checkbox tabindex="-1" checked>Waste-paper basket for Dora</wa-checkbox>
<wa-checkbox tabindex="-1" checked>Pen and ink for Milo</wa-checkbox>
<wa-checkbox tabindex="-1">Mirror for Angelica</wa-checkbox>
<wa-checkbox tabindex="-1">Silver spoons for Lobelia</wa-checkbox>
</div>
<div slot="footer">
<a href="" tabindex="-1">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 tabindex="-1" 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 tabindex="-1" name="backward" label="Skip backward"></wa-icon-button>
<wa-icon-button tabindex="-1" name="pause" style="font-size: var(--wa-font-size-2xl);" label="Pause"></wa-icon-button>
<wa-icon-button tabindex="-1" 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" tabindex="-1">Mos Eisley, Tatooine</a>
</div>
</div>
</wa-card>
</div>
</div>

85
docs/_layouts/theme.njk Normal file
View File

@@ -0,0 +1,85 @@
{% set hasSidebar = true %}
{% set hasOutline = true %}
{# {% set forceTheme = page.fileSlug %} #}
{% extends '../_includes/base.njk' %}
{% block header %}
<iframe src='{{ page.url }}demo.html'></iframe>
{% endblock %}
{% block afterContent %}
{% markdown %}
## How to use this theme
You can import this theme from the Web Awesome CDN.
<wa-tab-group>
<wa-tab panel="html">In HTML</wa-tab>
<wa-tab panel="css">In CSS</wa-tab>
<wa-tab-panel name="html">
Simply add the following code to the `<head>` of your page:
```html
<link rel="stylesheet" href="{% cdnUrl 'styles/themes/' + page.fileSlug + '.css' %}" />
```
</wa-tab-panel>
<wa-tab-panel name="css">
Simply add the following code at the top of your CSS file:
```css
@import url('{% cdnUrl 'styles/themes/' + page.fileSlug + '.css' %}');
```
</wa-tab-panel>
</wa-tab-group>
## Dark mode
To activate the dark color scheme of the theme on any element and its contents, apply the class `wa-dark` to it.
This means you can use different color schemes throughout the page.
Here, we use the default theme with a dark sidebar:
```html
<html>
<head>
<link rel="stylesheet" href="path/to/web-awesome/dist/styles/themes/default.css" />
</head>
<body>
<nav class="wa-dark">
<!-- dark-themed sidebar -->
</nav>
<!-- light-themed content -->
</body>
</html>
```
You can apply the class to the `<html>` element on your page to activate the dark color scheme for the entire page.
```html
<html class="wa-dark">
<head>
<link rel="stylesheet" href="path/to/web-awesome/dist/styles/themes/{{ page.fileSlug }}.css" />
<!-- other links, scripts, and metadata -->
</head>
<body>
<!-- page content -->
</body>
</html>
```
### Detecting Color Scheme Preference
Web Awesome's themes have 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
- 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.
{% endmarkdown %}
{% endblock %}

3
docs/_utils/filters.js
View File

@@ -167,6 +167,9 @@ export function sort(arr, by = { 'data.order': 1, 'data.title': '' }) {
* @returns { Object.<string, object[]> } An object with keys for each tag, and an array of items for each tag.
*/
export function groupByTags(collection, tags) {
if (!collection) {
console.error(`Empty collection passed to groupByTags() to group by ${JSON.stringify(tags)}`);
}
if (!tags) {
// Default to grouping by union of all tags
tags = Array.from(new Set(collection.flatMap(item => item.data.tags)));

64
docs/assets/scripts/preset-theme-picker.js Normal file
View File

@@ -0,0 +1,64 @@
import { domChange, nextFrame, ThemeAspect } from './theme-picker.js';
const presetTheme = new ThemeAspect({
defaultValue: 'default',
key: 'presetTheme',
picker: 'wa-select.preset-theme-selector',
applyChange() {
const oldStylesheets = [...document.querySelectorAll('#theme-stylesheet')];
const oldStylesheet = oldStylesheets.pop();
if (oldStylesheets.length > 0) {
// Remove all but the last one
for (let stylesheet of oldStylesheets) {
stylesheet.remove();
}
}
const href = `/dist/styles/themes/${this.value}.css`;
if (!oldStylesheet || oldStylesheet.getAttribute('href') !== href) {
const newStylesheet = document.createElement('link');
Object.assign(newStylesheet, { href, id: 'theme-stylesheet', rel: 'preload', as: 'style' });
oldStylesheet.after(newStylesheet);
newStylesheet.addEventListener(
'load',
e => {
domChange(
async instant => {
// Swap stylesheets
newStylesheet.rel = 'stylesheet';
if (instant) {
// If no VT, delay by 1 frame to make it smoother
await nextFrame();
}
oldStylesheet.remove();
},
{ behavior: 'smooth' },
);
},
{ once: true },
);
}
},
});
/**
* Without this, there's a flash of the incorrect preset theme.
*/
function updateSelectionBeforeTurboLoad(e) {
const newElement = e.detail.newBody || e.detail.newFrame || e.detail.newStream;
if (newElement) {
presetTheme.syncUI(newElement);
}
}
['turbo:before-render', 'turbo:before-stream-render', 'turbo:before-frame-render'].forEach(eventName => {
document.addEventListener(eventName, updateSelectionBeforeTurboLoad);
});
window.presetTheme = presetTheme;

37
docs/assets/scripts/sync-iframe-height.js Normal file
View File

@@ -0,0 +1,37 @@
/**
* Sync iframe height with its content page (for same-origin iframes)
* NOT CURRENTLY USED ANYWHERE
*/
for (let iframe of document.querySelectorAll('iframe')) {
if (iframe.contentDocument) {
// Already loaded
syncIframeHeight(iframe);
}
iframe.onload = () => {
console.log('iframe loaded');
if (iframe.contentDocument) {
// Same origin
iframe.contentWindow.iframe = iframe;
syncIframeHeight(iframe);
const resizeObserver = new ResizeObserver(entries => {
for (let entry of entries) {
if (entry.target === iframe.contentDocument.body) {
syncIframeHeight(iframe);
}
}
});
resizeObserver.observe(iframe.contentDocument.body);
window.addEventListener('turbo:render', syncIframeHeight(iframe));
}
};
}
function syncIframeHeight(iframe) {
iframe.style.height = '0px';
requestAnimationFrame(() => {
iframe.style.height = iframe.contentDocument.body.scrollHeight + 'px';
});
}

87
docs/assets/scripts/theme-picker.js
View File

@@ -10,7 +10,7 @@ export function domChange(fn, { behavior = 'smooth' } = {}) {
}
}
function nextFrame() {
export function nextFrame() {
return new Promise(resolve => requestAnimationFrame(resolve));
}
@@ -75,55 +75,6 @@ export class ThemeAspect {
}
}
const presetTheme = new ThemeAspect({
defaultValue: 'default',
key: 'presetTheme',
picker: 'wa-select.preset-theme-selector',
applyChange() {
const oldStylesheets = [...document.querySelectorAll('#theme-stylesheet')];
const oldStylesheet = oldStylesheets.pop();
if (oldStylesheets.length > 0) {
// Remove all but the last one
for (let stylesheet of oldStylesheets) {
stylesheet.remove();
}
}
const href = `/dist/styles/themes/${this.value}.css`;
if (!oldStylesheet || oldStylesheet.getAttribute('href') !== href) {
const newStylesheet = document.createElement('link');
Object.assign(newStylesheet, { href, id: 'theme-stylesheet', rel: 'preload', as: 'style' });
oldStylesheet.after(newStylesheet);
newStylesheet.addEventListener(
'load',
e => {
domChange(
async instant => {
// Swap stylesheets
newStylesheet.rel = 'stylesheet';
if (instant) {
// If no VT, delay by 1 frame to make it smoother
await nextFrame();
}
oldStylesheet.remove();
},
{ behavior: 'smooth' },
);
},
{ once: true },
);
nextFrame().then(_ => updateThemeNameAndDescription());
}
},
});
const colorScheme = new ThemeAspect({
defaultValue: 'auto',
key: 'colorScheme',
@@ -152,23 +103,6 @@ const colorScheme = new ThemeAspect({
// Update the color scheme when the preference changes
window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', () => colorScheme.set());
/**
* Without this, there's a flash of the incorrect preset theme.
*/
function updateSelectionBeforeTurboLoad(e) {
const newElement = e.detail.newBody || e.detail.newFrame || e.detail.newStream;
if (newElement) {
presetTheme.syncUI(newElement);
colorScheme.syncUI(newElement);
}
}
['turbo:before-render', 'turbo:before-stream-render', 'turbo:before-frame-render'].forEach(eventName => {
document.addEventListener(eventName, updateSelectionBeforeTurboLoad);
});
document.addEventListener('turbo:render', updateThemeNameAndDescription);
// Toggle color scheme with backslash
document.addEventListener('keydown', event => {
if (
@@ -179,22 +113,3 @@ document.addEventListener('keydown', event => {
colorScheme.set(theming.colorScheme.resolvedValue === 'dark' ? 'light' : 'dark');
}
});
// Temp hack for theme switcher
function updateThemeNameAndDescription() {
let selectedOption = document.querySelector(`.preset-theme-selector wa-option[value="${presetTheme.value}"]`);
if (selectedOption) {
let title = selectedOption.textContent;
let description = selectedOption.dataset.description;
for (let element of document.querySelectorAll('[data-theme-name]')) {
element.textContent = title;
}
for (let element of document.querySelectorAll('[data-theme-description]')) {
element.textContent = description;
}
}
}
updateThemeNameAndDescription();
window.presetTheme = presetTheme;

17
docs/assets/styles/docs.css
View File

@@ -455,3 +455,20 @@ wa-page > main:has(> .index-grid) {
padding: var(--wa-space-3xl);
}
}
.layout-theme {
wa-page > main {
max-width: 140ch;
.max-line-length {
max-width: 80ch;
}
}
iframe {
width: 100%;
min-height: 16lh;
height: 65vh;
max-height: 21lh;
}
}

2
docs/docs/components/page.md
View File

@@ -1,7 +1,7 @@
---
title: Page
description: Pages offer an easy way to scaffold entire page layouts using minimal markup.
tags: [organization, layout]
tags: [pro, organization, layout]
isPro: true
order: 0
# icon: page

2
docs/docs/customizing.md
View File

@@ -15,7 +15,7 @@ Because these custom properties live at the page level, they're prefixed with `-
To customize a theme, simply override any of these custom properties in your own stylesheet by scoping your styles to `:root`, `:host`, and, if needed, the class for the specific theme you want to override. Here's an example that changes the default brand color (blue) to violet in the light theme using existing [literal colors](/docs/theming/color/#literal-colors).
```css
:root,
:where(:root),
:host,
.wa-theme-default {
/* Changes the brand color to violet across the library */

6
docs/docs/themes/active.md vendored Normal file
View File

@@ -0,0 +1,6 @@
---
title: Active
description: Energetic and tactile, always in motion.
isPro: true
tags: pro
---

5
docs/docs/themes/awesome.md vendored Normal file
View File

@@ -0,0 +1,5 @@
---
title: Awesome
description: Punchy and vibrant, the rockstar of themes.
order: 0.2
---

6
docs/docs/themes/brutalist.md vendored Normal file
View File

@@ -0,0 +1,6 @@
---
title: Brutalist
description: Sharp, square, and unapologetically bold.
isPro: true
tags: pro
---

5
docs/docs/themes/classic.md vendored Normal file
View File

@@ -0,0 +1,5 @@
---
title: Classic
description: Timeless elegance that never goes out of style.
order: 0.1
---

59
docs/docs/themes/creating.md vendored Normal file
View File

@@ -0,0 +1,59 @@
---
title: Creating Themes
layout: page-outline
order: 999
override:tags: [themes]
---
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
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](/docs/customizing#design-tokens) and adds [component styles](/docs/customizing#css-parts) to your liking. You must import your theme _after_ the default theme.
If you're customizing the default light styles, scope your styles to the following selectors.
```css
:where(:root),
:host,
.wa-theme-default,
.wa-light {
/* your custom styles here */
}
```
If you're customizing the default dark styles, scope your styles to the following selectors.
```css
.wa-dark,
:is(:host-context(.wa-dark)) {
/* your custom styles here */
}
```
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.
## 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 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.
```css
:where(:root),
:host,
.wa-theme-purple-power,
.wa-light {
/* your custom styles here */
}
```
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 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.

5
docs/docs/themes/default.md vendored Normal file
View File

@@ -0,0 +1,5 @@
---
title: Default
description: Your trusty companion, like a perfectly broken-in pair of jeans.
order: 0
---

40
docs/docs/themes/demo.njk vendored Normal file
View File

@@ -0,0 +1,40 @@
---
layout: blank
pagination:
data: collections.theme
size: 1
alias: theme
permalink: '/docs/themes/{{ theme.fileSlug }}/demo.html'
eleventyExcludeFromCollections: true
override:tags: []
eleventyComputed:
forceTheme: "{{ theme.fileSlug }}"
---
<script>
document.getElementById('theme-stylesheet').href = '/dist/styles/themes/{{ theme.fileSlug }}.css';
</script>
<script type=module>
document.getElementById('theme-stylesheet').href = '/dist/styles/themes/{{ theme.fileSlug }}.css';
</script>
<link rel="stylesheet" href="/dist/styles/themes/{{ theme.fileSlug }}.css" />
<link rel="stylesheet" href="/docs/themes/showcase.css" />
{% set content %}
<header>
{% include 'breadcrumbs.njk' %}
<h1 class="title">{{ theme.data.title }}</h1>
<p>{% include 'status.njk' %}</p>
<p id="theme-showcase-description">{{ theme.data.description | inlineMarkdown | safe }}</p>
</header>
{% include 'theme-showcase.njk' %}
{% endset %}
<wa-image-comparer style="width: 100%" position="90">
<div slot="after" class="theme-showcase wa-gap-xl">
{{ content | safe }}
</div>
<div slot="before" class="theme-showcase wa-gap-xl wa-invert">
{{ content | safe }}
</div>
</wa-image-comparer>

7
docs/docs/themes/glassy.md vendored Normal file
View File

@@ -0,0 +1,7 @@
---
title: Glassy
description: Smooth, sleek, and reflective.
isPro: true
tags: pro
noAlpha: true
---

328
docs/docs/themes/index.md vendored
View File

@@ -1,328 +0,0 @@
---
title: Themes
description: Everything you need to know about theming Web Awesome.
layout: page-outline
---
<link rel="stylesheet" href="{{ page.url }}showcase.css" />
<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-2xs">
<div class="wa-split wa-gap-2xs">
<strong>Initiate Saber</strong>
<strong>$179.99</strong>
</div>
<div class="wa-split wa-gap-2xs 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-2xs">
<div class="wa-split wa-gap-2xs">
<strong>Repair Droid</strong>
<strong>$3,049.99</strong>
</div>
<div class="wa-split wa-gap-2xs 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 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 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.
Additionally, styles may be scope to the `:root` selector to be activated automatically.
For pre-made themes, *all* custom properties are scoped to `:where(:root)`, the theme class, and `wa-light`.
:::info
We use `:where(:root)` to give these styles 0 [specificity](https://developer.mozilla.org/en-US/docs/Web/CSS/Specificity) so that they can be easily overridden. If you plan on using multiple themes in your project, we recommend doing the same for your custom themes.
:::
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
:where(:root),
:host,
.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 a dark color scheme */
}
```
## Using Themes
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="{% cdnUrl 'styles/themes/default.css' %}" />
```
Or the **Classic** theme:
```html
<link rel="stylesheet" href="{% cdnUrl 'styles/themes/classic.css' %}" />
```
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>
<link rel="stylesheet" href="path/to/web-awesome/dist/styles/themes/default.css" />
<!-- other links, scripts, and metadata -->
</head>
<body>
<!-- page content -->
</body>
</html>
```
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>
<head>
<link rel="stylesheet" href="path/to/web-awesome/dist/styles/themes/default.css" />
</head>
<body>
<nav class="wa-dark">
<!-- dark-themed sidebar -->
</nav>
<!-- light-themed content -->
</body>
</html>
```
## Creating Themes
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
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](/docs/customizing#design-tokens) and adds [component styles](/docs/customizing#css-parts) to your liking. You must import your theme _after_ the default theme.
If you're customizing the default light styles, scope your styles to the following selectors.
```css
:root,
:host,
.wa-theme-default,
.wa-light {
/* your custom styles here */
}
```
If you're customizing the default dark styles, scope your styles to the following selectors.
```css
.wa-dark,
:is(:host-context(.wa-dark)) {
/* your custom styles here */
}
```
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.
### 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 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.
```css
:root,
:host,
.wa-theme-purple-power,
.wa-light {
/* your custom styles here */
}
```
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 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.
## Detecting Color Scheme Preference
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
- 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>

55
docs/docs/themes/index.njk vendored Normal file
View File

@@ -0,0 +1,55 @@
---
title: Themes
description: Themes are collections of pre-defined CSS custom properties that thread through every Web Awesome component and pattern.
layout: overview
override:tags: []
forTag: theme
categories:
other: Free
pro: Pro
---
<div class="max-line-length">
{% markdown %}
## What's a Theme?
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.
Please note that if you import multiple themes, the last one will be the default that will apply if no class is used.
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.
Additionally, styles may be scoped to the `:root` selector to be activated automatically.
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
:where(:root),
:host,
.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 a dark color scheme */
}
```
## Using Themes
You can import pre-made themes from the Web Awesome CDN.
Refer to each theme’s page for copyable code snippets.
{% endmarkdown %}
</div>

6
docs/docs/themes/mellow.md vendored Normal file
View File

@@ -0,0 +1,6 @@
---
title: Mellow
description: Soft and soothing, like a lazy Sunday morning.
isPro: true
tags: pro
---

7
docs/docs/themes/playful.md vendored Normal file
View File

@@ -0,0 +1,7 @@
---
title: Playful
description: Fun, colorful, and full of personality.
isPro: true
tags: pro
noAlpha: true
---

7
docs/docs/themes/premium.md vendored Normal file
View File

@@ -0,0 +1,7 @@
---
title: Premium
description: The ultimate in sophistication and style.
isPro: true
tags: pro
noAlpha: true
---

75
docs/docs/themes/showcase.css vendored
View File

@@ -1,26 +1,40 @@
wa-page > main {
max-width: 140ch;
html {
background: transparent;
}
.max-line-length {
max-width: 80ch;
}
html,
body,
.theme-showcase {
height: 100vh;
overflow: hidden;
}
.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);
box-sizing: border-box;
overflow: hidden;
margin-block-end: var(--wa-space-xl);
&.wa-flank {
--content-percentage: 60%;
--flank-size: 25ch;
@media (width < 500px) {
flex-flow: column;
}
header {
min-width: min(25ch, 100vw);
align-self: center;
h1 {
margin-bottom: var(--wa-space-2xs);
}
wa-breadcrumb-item:not(:first-of-type, :last-of-type) {
display: none;
}
p:empty {
display: none;
}
}
}
@@ -40,54 +54,37 @@ wa-page > main {
margin-block-end: var(--wa-space-xl);
}
}
}
@supports not (zoom: 1) {
.showcase-examples {
@supports not (zoom: 1) {
column-count: 1;
}
@container showcase (width > 750px) {
.showcase-examples {
@media (width > 750px) {
column-count: 2;
}
}
@container showcase (width > 950px) {
.showcase-examples {
@media (width > 950px) {
column-count: 3;
}
}
}
@supports (zoom: 1) {
.showcase-examples {
@supports (zoom: 1) {
column-count: 1;
zoom: 40%;
}
@container showcase (width > 350px) {
.showcase-examples {
@media (width > 350px) {
column-count: 2;
}
}
@container showcase (width > 450px) {
.showcase-examples {
@media (width > 450px) {
zoom: 55%;
}
}
@container showcase (width > 750px) {
.showcase-examples {
@media (width > 750px) {
zoom: 70%;
}
}
@container showcase (width > 950px) {
.showcase-examples {
@media (width > 950px) {
column-count: 3;
zoom: 70%;
}
}
}

6
docs/docs/themes/tailspin.md vendored Normal file
View File

@@ -0,0 +1,6 @@
---
title: Tailspin
description: Like a bird in flight, guiding you from there to here.
isPro: true
tags: pro
---

4
docs/docs/themes/themes.json vendored Normal file
View File

@@ -0,0 +1,4 @@
{
"layout": "theme.njk",
"tags": ["themes", "theme"]
}