Deprecate old theme variables and remove them from code and docs

scss/_patterns_buttons.scss

@@ -54,18 +54,10 @@
     @extend %vf-button-base;
 
     // Theming
-    @if ($theme-default-p-button == 'dark') {
-      @extend %p-button--brand-dark;
-
-      &.is-light {
-        @extend %p-button--brand-light;
-      }
-    } @else {
-      @extend %p-button--brand-light;
+    @extend %p-button--brand-light;
 
-      &.is-dark {
-        @extend %p-button--brand-dark;
-      }
+    &.is-dark {
+      @extend %p-button--brand-dark;
     }
 
     @extend %vf-button-white-success-icon;

scss/_settings_themes.scss

@@ -1,11 +1,14 @@
+// deprecated
+// the following SCSS variables are deprecated and will be removed in a future release
+// they are not used to switch themes anymore, instead use the CSS theme class names `is-light`, `is-dark` or `is-paper`
 $theme-default-forms: 'light' !default;
-$theme-default-hr: 'light' !default; // deprecated -- use new theme classes instead
+$theme-default-hr: 'light' !default;
 $theme-default-nav: 'light' !default;
-$theme-default-p-side-navigation: 'light' !default; // deprecated -- use new theme classes instead
+$theme-default-p-side-navigation: 'light' !default;
 $theme-default-p-search-box: 'light' !default;
-$theme-default-p-divider: 'light' !default; // deprecated -- use new theme classes instead
-$theme-default-p-contextual-menu: 'light' !default; // deprecated -- use new theme classes instead
-$theme-default-p-inline-list--middot: 'light' !default; // deprecated -- use new theme classes instead
+$theme-default-p-divider: 'light' !default;
+$theme-default-p-contextual-menu: 'light' !default;
+$theme-default-p-inline-list--middot: 'light' !default;
 $theme-default-p-button: 'light' !default;
 $theme-default-p-chip: 'light' !default;
-$theme-default-p-tabs: 'light' !default; // deprecated -- use new theme classes instead
+$theme-default-p-tabs: 'light' !default;

templates/docs/patterns/contextual-menu/index.md

@@ -48,10 +48,7 @@ Please ensure the `aria-control` attribute matches an ID of an element. If `aria
 
 ## Theming
 
-The contextual menu uses Vanilla's light theme by default. There are two ways to switch between the light and the dark themes:
-
-- Change the default: go to `_settings_themes.scss` and set `$theme-default-p-contextual-menu` to `dark`
-- Override the default by adding a state to `p-contextual-menu`: `is-dark` when the default navigation is light, or `is-light` when the default has been changed to dark:
+The contextual menu uses the default inherited theme of the page or parent element. To override the default add `is-dark` or `is-light` class to the contextual menu.
 
 <div class="embedded-example"><a href="/docs/examples/patterns/contextual-menu/dark" class="js-example">
 View example of the contextual menu with an is-dark class

templates/docs/patterns/divider.md

@@ -17,9 +17,7 @@ View example of lists with a responsive divider
 The responsive divider is available in a light and a dark theme. The colours used by both themes in the [colour settings file](https://github.com/canonical/vanilla-framework/blob/main/scss/_settings_colors.scss).
 Overriding the colours of individual elements of the responsive is discouraged, as this may lead to accessibility issues, or inconsistencies with other components that use the same theme.
 
-By default, the responsive divider uses the light theme. To change the global default, set `$theme-default-p-divider` to `dark`.
-
-To change the appearance of an individual instance of the responsive divider pattern, you can use the `is-dark` class.
+By default, the responsive divider uses the current theme of the page or its parent element. To change the appearance of an individual instance of the responsive divider pattern, you can use the `is-dark` class.
 
 For more details about themes in Vanilla refer to the [Color theming](/docs/settings/color-settings#color-theming) section of the documentation.
 

templates/docs/patterns/navigation/index.md

@@ -191,9 +191,7 @@ For more information, read the dedicated [application layout documentation](/doc
 The side navigation is available in a light and a dark theme. The colours used by both themes in the [colour settings file](https://github.com/canonical/vanilla-framework/blob/main/scss/_settings_colors.scss).
 Overriding the colours of individual elements of the side navigation is discouraged, as this may lead to accessibility issues, or inconsistencies with other components that use the same theme.
 
-By default, the side navigation uses the light theme. To change the global default, set `$theme-default-p-side-navigation` to `dark`.
-
-To change the appearance of an individual instance of the side navigation, you can use the `is-dark` class.
+By default, the side navigation uses the current theme of the page. To change the appearance of an individual instance of the side navigation, you can use the `is-dark` class.
 
 For more details about themes in Vanilla refer to the [Color theming](/docs/settings/color-settings#color-theming) section of the documentation.
 

templates/docs/patterns/tabs/index.md

@@ -37,10 +37,7 @@ View example of the tabs content pattern
 
 ## Theming
 
-Tabs use Vanilla's light theme by default. There are two ways to switch between the light and the dark themes:
-
-To change the default, go to `_settings_themes.scss` and set `$theme-default-p-tabs` to `dark`.
-To override the default, add a state to `p-tabs`: `is-dark` when the default tabs theme is light, or `is-light` when the default has been changed to dark:
+Tabs use the default inherited theme of the page or parent element. To override the default add `is-dark` or `is-light` class to the contextual menu.
 
 <div class="embedded-example"><a href="/docs/examples/patterns/tabs/content-dark" class="js-example">
 View example of the dark tabs content pattern

templates/docs/settings/color-settings.md

@@ -163,7 +163,7 @@ Starting with the [2.3.0](https://github.com/canonical/vanilla-framework/release
 | Side navigation     | `$theme-default-p-side-navigation`     | `light`       |
 | Search box          | `$theme-default-p-search-box`          | `light`       |
 
-The `_settings_themes.scss` file contains a list of variables that define the default theme for a subset of elements and components. Starting with Vanilla 4.8.0 this type of theming is deprecated.
+The `_settings_themes.scss` file contains a list of variables that used to define the default theme for a subset of elements and components. Starting with Vanilla 4.8.0 this type of theming is deprecated.
 
 With new theming mechanism based on CSS custom properties, the default theme for all components remains light. To change the theme of given element and all its children, add `is-dark` or `is-light` class to it.