History: Updating a Theme for Tiki 26

• «
• »

            Tiki 26 uses Bootstrap 5.3, which introduces color modes, the ability to have web pages respond to the browser color preference, if set, and to the user choice by means of a switch on the page. Because the color modes are using CSS custom properties (CSS variables), the color change is instant -- no need for a page refresh. Themes made for previous versions of Tiki need some specific updating to take advantage of this feature. 

For background, see [https://getbootstrap.com/docs/5.3/customize/color/] and [https://getbootstrap.com/docs/5.3/customize/color-modes/]. For more about CSS variables, please see ((CSS Variables in Tiki)). 

!! Procedure used for the Tiki package themes
To update a theme for Bootstrap 5.3 and color modes, these steps are suggested. This is what was done to update the themes in the Tiki package.
* Add the default _variables-dark.scss file to the theme's scss directory
* The dark-mode colors may be adjusted in the future, to optimize or enhance for each theme, but for now the variables have the default value.
* Edit the theme's main file (themename.scss, etc.) to add the import statement for _variables-dark.scss, just after _variables.scss.
* To enable color mode switching of the top and topbar module zones and the Unified Admin Backend pages, add -+ @import "../../base_files/scss/_tiki-pagetop_colors.scss"; +- after the import statement for ../../base_files/scss/_tiki-selectors.scss. 
* The theme will need a scss/_css-variables.scss file for color mode switching to work.
* The CSS variables file contains rules mainly for the top and topbar sections of pages, as well as for the Unified Admin Backend screens. 
* Depending on how the author organizes the theme files, the content of _css-variables.scss don't have to be in that specific file as long as the variables are defined properly.
* It's probably easiest to copy the _css-variables.scss file from another Tiki 26 theme for the new theme. Note that the variables are defined in different ways in the various themes, and either use color values directly or refer to other variable definitions for colors, etc. These other variables might need to be defined in the theme being updated.

With the new files added and their import statements added, the next step is to compile the theme, but there will be errors due to undefined variables. These are variables that typically need to be in the variables.scss file and properly defined:

|| Variable name | Default value | Variables file section | Used for
$prefix | -bs | Options | Used for :root CSS variables
$link-shade-percentage | 20% | Links | Calculation of hover color relative to link color (this is the default, replacing the specifying of a hover color).
$code-color | $body-color (was $pink) | Code | The text color of code examples, etc. Many of Tiki's packaged themes didn't have this specified but it's necessary.  
$pink | #d63384 | Color system (formerly Colors) | Needed for $code-color (if $code-color: $pink). __UPDATE:__ The default code color [https://gitlab.com/tikiwiki/tiki/-/commit/8d2b7a52cb0494ab00b922fb6df358b1a06efe2e?page=2|was changed] from pink to whatever the theme's body color ($body-color) is, so $pink no longer needs to be present or defined.
$green-300 |  tint-color($green, 40%) | Color system | Form validation text - valid
$green | #198754 | Color system | Needed for $green-300.
$red-300 | tint-color($red, 40%) | Color system | Form validation text - invalid 
$red | #dc3545 | Color system | Needed for $red-300. ||
The theme should compile after all these variables are in the theme's variables file.

^
__Update:__ . A change was made in each theme's top SCSS file (ex: amelia.scss) to fix the problem of missing new Bootstrap variable definitions [https://gitlab.com/tikiwiki/tiki/-/commit/09650025546c76cc97e1b4adb92e6b8cb783b659|last November]. This change adds an import statement for the default Bootstrap variables and variables-dark along with their values, following the theme's own variables files. Coming first, the theme variables files specify the theme values, then the default file adds any missing ones, so it should cover cases like $mark-color-dark, which was added in a point upgrade of Bootstrap, and the stylesheet should compile, or if it doesn't. it's not because of an undefined variable. Note that the new variables will have the default Bootstrap value which may or may not be appropriate for the theme; if not, the variable should be copied to the theme's variables (or variables-dark) file and redefined.

A typical themename.scss file now looks like this:

{CODE()}
@import "../../base_files/scss/_tiki-bootstrap_functions";
@import "../scss/variables"; // Needs to come first, to override Bootstrap defaults.
@import "../../default/scss/variables"; // Bootstrap default variables, with a few Tiki overrides
@import "../scss/variables-dark"; // New in Bootstrap 5.3
@import "../../default/scss/variables-dark"; // Bootstrap dark mode default variables
@import "../../base_files/scss/_tiki-variables.scss"; // Values/definitions for Tiki variables (outside of Bootstrap variables) such as _tiki-selectors.scss.
@import "../../base_files/scss/_tiki-bootstrap_layout_and_components";
@import "../scss/css-variables"; // Needs to be loaded after default variables to override them
@import "../../base_files/scss/_tiki-selectors.scss";
@import "../../base_files/scss/_tiki-pagetop_colors.scss"; // Import if needed (almost always) to specify top and topbar zone colors in more detail
@import "../scss/_tiki-selectors.scss";
@import "../../base_files/scss/_external-scripts.scss";
@import "../../base_files/scss/_select2-tiki_colors.scss";
{CODE}
^

For more complete color mode switching, these variables may also need to be defined:

|| $popover-bg | var(--#{$prefix}body-bg) | Popovers | This and the following need to be defined for popovers to respond to color mode switching.
$popover-border-color | var(--#{$prefix}border-color-translucent) | Popovers |
$popover-header-bg | var(--#{$prefix}secondary-bg) | Popovers |
$popover-header-color | $headings-color | Popovers |
$popover-body-color | var(--#{$prefix}body-color) | Popovers |
$headings-color | inherit | Typography | Needed for popover heading color. ||

!! Troubleshooting
After the above changes are made in the theme and it's compiling ok, there may be variable definitions or CSS rules interfering with color mode changes. 

Check the theme's _tiki-selectors.scss file for CSS like this: -+ body { background: #fff url('#{$imagePath}grey-bg.png') repeat-x; } +- . In this example, ''light'' mode will be ok, but ''dark'' mode will continue to apply this rule rather than the alternative dark background specified by -+$body-bg-dark+- (in _variables-dark.scss). Updating the rule to -+ body { background: var(--bs-body-bg) url('#{$imagePath}grey-bg.png') repeat-x; } +- will probably solve the problem.

(More details coming.)