History: Updating a Theme for Tiki 26
Preview of version: 3
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:
| New variable name | Default value | Variables file section | Used for |
| $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 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.
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.)