Add basic themes documentation

canonical · Oct 10, 2024 · 44baf1b · 44baf1b
1 parent 852f4fb
commit 44baf1b
Show file tree

Hide file tree

Showing 5 changed files with 39 additions and 30 deletions.
diff --git a/redirects.yaml b/redirects.yaml
@@ -9,6 +9,7 @@
 /docs/upgrade-guide-v3: /docs/migration-guide-to-v3
 /docs/examples/patterns/x-small-capitalised: /docs/examples/patterns/text-small-caps
 /docs/base/separators: /docs/patterns/rule
+/docs/base/paper: /docs/base/themes
 
 # redirects based on class names
 /docs/patterns/code-snippet: /docs/base/code

diff --git a/side-navigation.yaml b/side-navigation.yaml
@@ -21,10 +21,10 @@
       url: /docs/base/reset
     - title: Tables
       url: /docs/base/tables
+    - title: Themes
+      url: /docs/base/themes
     - title: Typography
       url: /docs/base/typography
-    - title: Paper background
-      url: /docs/base/paper
 - heading: Components
   ordering: alphabetical
   subheadings:

diff --git a/templates/docs/base/paper.md b/templates/docs/base/paper.md
diff --git a/templates/docs/base/themes.md b/templates/docs/base/themes.md
@@ -0,0 +1,23 @@
+---
+wrapper_template: '_layouts/docs.html'
+context:
+  title: Themes | Base elements
+---
+
+Vanilla (since version 4.8.0) supports client-side theming based on CSS properties (instead of previously used build-time SCSS based theming).
+
+We currently support the following themes:
+
+- light (default, or provided by `is-light` class)
+- paper (provided by `is-paper` class, recommended for websites) which extents the light theme, but uses a light grey background
+- dark (provided by `is-dark` class)
+
+It's recommended to apply the theme on the page level, by adding the relevant class name to the `body` element. Theme can also be set on any other element and will apply to that element and any of its descendants (via CSS inheritance).
+
+```html
+<body class="is-paper">
+  ...
+</body>
+```
+
+[See an example page in paper theme](/docs/examples/brochure/index).
diff --git a/templates/docs/settings/color-settings.md b/templates/docs/settings/color-settings.md
@@ -131,6 +131,19 @@ It’s important for us to meet all web accessibility standards. Vanilla encoura
 
 ## Color theming
 
+Vanilla (since version 4.8.0) supports client-side theming based on CSS properties (instead of previously used build-time SCSS based theming).
+
+See our [themes documentation](/docs/base/themes) for more details on how to use the new theming system.
+
+### Setting the default color theme per element / component {{ status("deprecated")}}
+
+<div class="p-notification--caution">
+  <div class="p-notification__content">
+    <h5 class="p-notification__title">Deprecated</h5>
+    <span class="p-notification__message">Setting default theme via SCSS variables is now deprecated. Use the new <a href="/docs/base/themes">theming class names</a> instead.</span>
+  </div>
+</div>
+
 Starting with the [2.3.0](https://github.com/canonical/vanilla-framework/releases/tag/v2.3.0) release, Vanilla framework introduces a theming mechanism. The current default for all components is referred to as the light theme. A subset of elements and components now offer a dark theme:
 
 - [Checkbox](/docs/base/forms#checkbox) and [radio](/docs/base/forms#radio-button) form inputs
@@ -142,15 +155,6 @@ Starting with the [2.3.0](https://github.com/canonical/vanilla-framework/release
 - [Side navigation](/docs/patterns/navigation#side-navigation)
 - [Search box](/docs/patterns/search-box)
 
-### Setting the default color theme per element / component
-
-<div class="p-notification--caution">
-  <div class="p-notification__content">
-    <h5 class="p-notification__title">Deprecated</h5>
-    <span class="p-notification__message">Setting default theme via SCSS variables is now deprecated. Use <code>is-dark</code> or <code>is-light</code> class names in HTML instead.</span>
-  </div>
-</div>
-
 | Element / Component | Variable                               | Default value |
 | ------------------- | -------------------------------------- | ------------- |
 | checkbox            | `$theme-default-forms`                 | `light`       |