webawesome/docs/_layouts/theme.njk

{% set hasSidebar = true %}
{% set hasOutline = true %}
{# {% set forceTheme = page.fileSlug %} #}

{% extends '../_includes/base.njk' %}

{% block head %}
<script>
globalThis.wa_data ??= {};
wa_data.baseTheme = "{{ page.fileSlug }}";
wa_data.themes = {
  {% for theme in collections.theme -%}
  "{{ theme.fileSlug }}": {
    "title": "{{ theme.data.title }}",
    "palette": "{{ theme.data.palette }}",
    "brand": "{{ theme.data.brand }}"
  },
  {% endfor %}
};
wa_data.palettes = {
  {% for palette in collections.palette -%}
  "{{ palette.fileSlug }}": {
    "title": "{{ palette.data.title }}",
  },
  {% endfor %}
};
</script>
<link href="/docs/themes/remix.css" rel="stylesheet">
<script src="/docs/themes/remix.js" type="module"></script>
{% endblock %}

{% block header %}

<iframe src='{{ page.url }}demo.html' id="demo"></iframe>

<wa-details id="mix_and_match" class="wa-gap-m" >
  <h4 slot="summary" data-no-anchor data-no-outline id="remix">
    <wa-icon name="arrows-rotate"></wa-icon>
    Remix this theme
    <wa-icon id="what-is-remixing" href="#remixing" name="circle-question" slot="suffix" variant="regular"></wa-icon>
    <wa-tooltip for="what-is-remixing">Customize this theme by changing its colors and/or remixing it with design elements from other themes!</wa-tooltip>
  </h4>

  <wa-select name="colors" label="Colors from…" value="" clearable>
    <wa-icon name="palette" slot="prefix" variant="regular"></wa-icon>
    {% for theme in collections.theme | sort %}
      {% set currentTheme = theme.fileSlug == page.fileSlug %}
      <wa-option label="{{ theme.data.title }}" value="{{ theme.fileSlug if not currentTheme }}" {{ (theme.fileSlug if currentTheme) | attr('data-id') }}>
        <wa-card with-header>
          <div slot="header">
          {% include "svgs/theme-color.njk" %}
          </div>
          <span class="page-name">
            {{ theme.data.title }}
            {% if theme.data.isPro %}<wa-badge class="pro">PRO</wa-badge>{% endif %}
            {% if currentTheme %}<wa-badge variant="neutral" appearance="outlined">This theme</wa-badge>{% endif %}
          </span>
        </wa-card>
      </wa-option>
    {% endfor %}
  </wa-select>

  <wa-select name="palette" label="Palette" clearable>
    <wa-icon name="swatchbook" slot="prefix" variant="regular"></wa-icon>
    {% set defaultPalette = palette %}
    {% for palette in collections.palette | sort %}
      {% set currentPalette = palette.fileSlug == defaultPalette %}
      <wa-option label="{{ palette.data.title }}" value="{{ palette.fileSlug if not currentPalette }}" {{ (palette.fileSlug if currentPalette) | attr('data-id') }}>
        <wa-card with-header>
          <div slot="header">
          {% include "svgs/" + (palette.data.icon or "thumbnail-placeholder") + ".njk" ignore missing %}
          </div>
          <span class="page-name">
            {{ palette.data.title }}
            {% if palette.data.isPro %}<wa-badge class="pro">PRO</wa-badge>{% endif %}
            {% if currentPalette %}<wa-badge variant="neutral" appearance="outlined">Theme default</wa-badge>{% endif %}
          </span>
        </wa-card>
      </wa-option>
    {% endfor %}
    {% set palette = defaultPalette %}
  </wa-select>

  <wa-select name="brand" label="Brand color" value="" clearable>
    <div class="selected-swatch" slot="prefix"></div>
    {% for hue in hues %}
      {% set currentBrand = hue == brand %}
      <wa-option label="{{ hue | capitalize }}" value="{{ hue if not currentBrand }}" {{ (hue if currentBrand) | attr('data-id') }} style="--color: var(--wa-color-{{ hue }})">
        {{ hue | capitalize }}
        {% if currentBrand %}<wa-badge variant="neutral" appearance="outlined">Theme default</wa-badge>{% endif %}
      </wa-option>
    {% endfor %}
  </wa-select>

  <wa-select name="typography" label="Typography from…" clearable>
    <wa-icon name="font-case" slot="prefix"></wa-icon>
    {% for theme in collections.theme | sort %}
      {% set currentTheme = theme.fileSlug == page.fileSlug %}
      <wa-option label="{{ theme.data.title }}" value="{{ theme.fileSlug if not currentTheme }}" {{ (theme.fileSlug if currentTheme) | attr('data-id') }}>
        <wa-card with-header>
          <div slot="header">
          {% include "svgs/theme-typography.njk" %}
          </div>
          <span class="page-name">
            {{ theme.data.title }}
            {% if theme.data.isPro %}<wa-badge class="pro">PRO</wa-badge>{% endif %}
            {% if currentTheme %}<wa-badge variant="neutral" appearance="outlined">This theme</wa-badge>{% endif %}
          </span>
        </wa-card>
      </wa-option>
    {% endfor %}
  </wa-select>
</wa-details>

<h2>Color</h2>
{% set paletteURL = '/docs/palettes/' + palette + '/' %}


<div class="index-grid">
  {% set themePage = page %}
  {% set page = paletteURL | getCollectionItemFromUrl %}
  {% set pageSubtitle = "Default color palette" %}
  {% include 'page-card.njk' %}
  {% set page = themePage %}

  <wa-card style="--header-background: var(--wa-color-{{ brand }})" class="wa-palette-{{ palette }}">
    <div slot="header"></div>
    <div class="page-name">{{ brand | capitalize }}</div>
    <div class="wa-caption-s">Default brand color</div>
  </wa-card>
</div>
{% endblock %}

{% block afterContent %}

<h2 id="usage">How to use this theme</h2>

{% markdown %}
You can import this theme from the Web Awesome CDN.

{% set stylesheet = 'styles/themes/' + page.fileSlug + '.css' %}
{% include 'import-stylesheet-code.md.njk' %}

## 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.

Assuming the user's preference is in a variable called `colorScheme` (values: `auto`, `light`, `dark`),
you can use the following JS snippet to apply the `wa-dark` class to the `<html>` element accordingly:

```js
const systemDark = window.matchMedia('(prefers-color-scheme: dark)');
const applyDark = function (event = systemDark) {
  const isDark = colorScheme === 'auto' ? event.matches : colorScheme === 'dark';
  document.documentElement.classList.toggle('wa-dark', isDark);
};
systemDark.addEventListener('change', applyDark);
applyDark();
```

{% endmarkdown %}
{% endblock %}