webawesome/docs/_layouts/theme.njk

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

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

{% block head %}
<link href="{{ page.url }}../remix.css" rel="stylesheet">
<script type="module" src="{{ page.url }}../edit/index.js"></script>
{% endblock %}

{% block header %}
<script>
if (location.pathname.endsWith('/custom/') && !location.search) {
  location.href = "../edit/";
}
</script>
<div id="theme-app" data-theme-id="{{ page.fileSlug }}">

<iframe ref="preview" :src="'{{ page.url }}demo.html' + urlParams" src='{{ page.url }}demo.html' id="demo"></iframe>

{% if page.fileSlug !== 'custom' %}
<wa-details id="mix_and_match" class="wa-gap-m" :open="saved || unsavedChanges">
  <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="palette" label="Color palette" with-clear v-model="theme.palette">
    <wa-icon name="swatchbook" slot="prefix" variant="regular"></wa-icon>
    <wa-option v-for="(palette, paletteId) in palettes" :label="palette.title" :value="paletteId === baseTheme.palette ? '' : paletteId">
      <palette-card :palette="paletteId" size="small">
        <template #extra>
          <wa-badge v-if="paletteId === baseTheme.palette" variant="neutral" appearance="outlined">Theme default</wa-badge>
        </template>
      </palette-card>
    </wa-option>
  </wa-select>

  <color-select :model-value="computed.brand" @update:model-value="value => theme.brand = value" label="Brand color"
                :values="hues"></color-select>

  <wa-select name="colors" class="theme-colors-select" label="Color contrast from…" value="" with-clear v-model="theme.colors">
    <wa-icon name="palette" slot="prefix" variant="regular"></wa-icon>
    <template v-for="(themeMeta, themeId) in themes">
      <wa-option v-if="themeId !== 'custom'" :label="themeMeta.title" :value="themeId === computed.colors ? '' : themeId">
        <theme-card :theme="themeId" type="colors" :rest="{base: computed.base, palette: computed.palette, brand: computed.brand}" size="small">
          <template #extra>
          <wa-badge v-if="themeId === theme.base" variant="neutral" appearance="outlined">This theme</wa-badge>
        </template>
        </theme-card>
      </wa-option>
    </template>
  </wa-select>

  <wa-select name="typography" label="Typography from…" with-clear v-model="theme.typography">
    <wa-icon name="font-case" slot="prefix"></wa-icon>

    <wa-option v-for="(themeMeta, themeId) in themes" :label="themeMeta.title" :value="themeId === theme.base ? '' : themeId">
      <fonts-card :theme="themeId" size="small">
        <template #extra>
          <wa-badge v-if="themeId === theme.base" variant="neutral" appearance="outlined">This theme</wa-badge>
        </template>
      </fonts-card>
    </wa-option>
  </wa-select>
</wa-details>
{% endif %}
<h2>Color</h2>

<div class="index-grid">
  {% if page.fileSlug === 'custom' %}
    <palette-card :palette="computed.palette" subtitle="Color palette"></palette-card>
  {% else %}
    {% set themePage = page %}
    {% set paletteURL = '/docs/palettes/' + palette + '/' %}
    {% set page = paletteURL | getCollectionItemFromUrl %}
    {% set pageSubtitle = "Default color palette" %}
    {% include 'page-card.njk' %}
    {% set page = themePage %}
  {% endif %}
  <wa-card class="wa-palette-{{ palette }}"          style="--header-background: var(--wa-color-{{ brand }})"
          :class="`wa-palette-${computed.palette}`" :style="{'--header-background': palettes[computed.palette]?.colors[computed.brand]?.key}">
    <div slot="header"></div>
    <div class="page-name" v-content="capitalize(computed.brand)">{{ brand | capitalize }}</div>
    <div class="wa-caption-s">{{ 'Brand color' if page.fileSlug === 'custom' else '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' %}

<wa-tab-group class="import-stylesheet-code">
<wa-tab panel="html">In HTML</wa-tab>
<wa-tab panel="css">In CSS</wa-tab>
<wa-tab-panel name="html">

Add the following code to the `<head>` of your page:
```html { v-content:html="code.html.highlighted" }
<link rel="stylesheet" href="{% cdnUrl stylesheet %}" />
```
</wa-tab-panel>
<wa-tab-panel name="css">

Add the following code at the top of your CSS file:
```css { v-content:html="code.css.highlighted" }
@import url('{% cdnUrl stylesheet %}');
```
</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.

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

</div> {# end theme app #}
{% endmarkdown %}
{% endblock %}