Pagetop Styles and CSS Variables

The arrangement of Tiki's navbars

The standard Bootstrap navbar element is normally a single navbar and isn't used in combination with another one. On the other hand, Tiki's top and topbar elements evolved from pre-Bootstrap portal-style layouts. The way Bootstrap is implemented in Tiki's page-top elements often puts one navbar element inside another — one for the entire module zone, and often one for a menu contained in a module in that module zone. If both navbars, the outer and inner one, have solid-color backgrounds, and it's the same color, then there's no problem with appearance. But if a gradient or image is specified for the background, then the navbar-on-navbar effect is obvious and usually unattractive.

Even if there were just one navbar, but it was contained in one or more divs that have content in addition to the navbar, there would still be a styling problem to deal with, involving color consistency, borders, shadows, and so on, this area.

Navbar colors also applied to parent divs

Some time ago, the parent divs of a navbar in the top module zone were given CSS classes such as bg-light-parent or bg-dark-parent . When the color preference of the navbar is switched in Look & Feel Admin, the colors of these parent divs are also switched, along with the colors of the navbar they contain, with the thinking that this is the desired behavior to prevent a patchwork of colors in these zones. (Of course this can be overridden by custom CSS or a theme stylesheet if desired.) That was one step to coordinate pagetop color styling.

The basic idea of tiki-pagetop_colors.scss

Assuming the navbar's parent divs and the navbar have the same color scheme, to prevent "gradient-on-gradient" or "bordered box or box-shadowed box inside bordered box or box-shadowed box," with tiki-pagetop_colors.scss , the styling is applied only to the topmost or outermost element, such as .navbar.fixed-top in the Basic Bootstrap layout, and then any nested div.bg-*-parent and the navbar itself is give a transparent background and borders and box-shadows are given a none value.

A caveat here: The assumption with this discussion is that a common background color or treatment is wanted for the entire top module zone or topbar module zone. In the case of a design where the module zone has one background color or gradient or image and a menu in that module zone has a different one, then theme designer shouldn't import themes/base_files/scss/tiki-pagetop_colors . The purpose of the file is to make uniform the background and foreground colors of the relevant divs and enable easy modification of these properties.

I found myself repeatedly writing a lot of CSS to style these page elements, especially when linear gradients or images are used for backgrounds. [Show example code.] I asked myself why do I need to do this for every theme with this type of color scheme? Not only aftermarket or custom themes but also some in the Tiki package like Darkroom and FiveAlive, and some Bootswatch themes like Cerulean have potential "gradient on gradient" problems if special CSS isn't written to counteract it.

First step: tiki-pagetop_colors

I had earlier created an SCSS file for color-variant child themes like those in FiveAlive and FiveAlive-lite, to avoid having to write the same CSS color rules for each theme. I used the same idea for the pagetop colors file that could be used by any theme, and the color-variant child themes could also use this file.

I made the file by collecting the "tiki-selectors" SCSS rules of themes that have relatively complex top and topbar zone color styles, and then simplified the rules, eliminating redundancies, and so on; initially this was just for background colors but then it was extended to cover background gradients and background images also. It addresses both top and topbar module zones (and parent divs) and both dark and light navbar options. (As of Bootstrap 5.2, the navbar-light and bg-light classes are retired, but are still used in Tiki unless there is a good reason to change.)

Pagetop styles and CSS variables

As the tiki-pagetop_colors file was progressing, SCSS variables were used to set values for the properties, as with most of Tiki's theme files. But it was apparent that this would be a natural and very useful place to use CSS variables, which to be honest I was just starting to get a handle on, so this was really a learning experience for me. So I replaced the SCSS variables in this file with CSS variable equivalents, and found the location in the theme files to define the CSS variables. This was tested first with the Utopias theme and since then I'm working my way through the other themes.

Example of CSS variable use in themes/base_files/_tiki-pagetop_colors.scss:

// Topbar module zone and parent divs - dark color
.layout_basic .topbar_modules.bg-dark,         // Single Container layout -- Topbar, which probably includes another nav menu
.layout_classic .topbar.bg-dark-parent,           // Classic Tiki layout -- Parent of the topbar module zone
.layout_social .topbar-wrapper.navbar-dark-parent.bg-dark-parent     // Classic Bootstrap topbar wrapper
{
    background: var(--tiki-topbar-bg-dark) !important;
    color: var(--tiki-topbar-dark-color);
    a:not(.dropdown-item),
    .btn.btn-link  {
        color: var(--tiki-topbar-dark-link-color);
        &:hover {
            color: var(--tiki-topbar-dark-link-hover-color);
        }
    }
}

Included page CSS Variables in Tiki:

Background info on CSS variables

See also: https://css-tricks.com/a-complete-guide-to-custom-properties/

CSS variables in Bootstrap

There were just 28 CSS variables in Bootstrap 4 (https://getbootstrap.com/docs/4.0/getting-started/theming/#css-variables). As of Bootstrap 5.2, this number, for root CSS variables, is up to approximately 70 (https://getbootstrap.com/docs/5.2/customize/css-variables/#root-variables). Root CSS variables have global scope. There are also component variables, with narrow scope, such as those used for tables and navbars, and as shown below in the examples of the top and topbar zone CSS variables.

The Tiki CSS variable syntax

To distinguish SCSS variables created specifically for Tiki from Bootstrap or other SCSS variables, they have a $tiki- prefix (implementation of this is a work in progress). The same pattern is used for Tiki's CSS variables, with --tiki- . (The prepended two hyphens are the standard notation for CSS variables.)

CSS variables currently used by Tiki

    --tiki-fixed-top-site-title-font-size: 1.8rem;          // Fixed-top position (Basic Bootstrap layout)
    --tiki-fixed-top-site-title-font-weight: 700;
    --tiki-fixed-top-site-subtitle-font-size: 1.4rem;
    --tiki-fixed-top-site-subtitle-font-weight: 400;

    --tiki-site-title-font-size: 2rem;                      // Static position (Classic Tiki and Single Container layouts)
    --tiki-site-title-font-weight: 700;
    --tiki-site-subtitle-font-size: 1.5rem;
    --tiki-site-subtitle-font-weight: 400; 

Theme-specific CSS variables

CSS variables are used by some Tiki themes already for color mode compliance or for situations where site admins might want to configure the theme's appearance or behavior in a particular way.

Background image path

A CSS variable can represent the path to an image file used for the background of some page element, like this:

.middle {
    background: var(--tiki-feb12-middle-bg);
    padding-bottom: 20px;
}

Then --tiki-feb12-middle-bg is specified differently, to fetch different files, or one file or no file, depending on whether light or dark color mode is being used:

:root {
    --tiki-feb12-middle-bg: #ffffff url(../images/page.jpg) repeat-x;
}
[data-bs-theme="dark"] {
    --tiki-feb12-middle-bg: transparent;

Defining CSS variables

As the docs on CSS variables show, they are placed in one or more arrays, each headed by a selector. These arrays, for a theme, are usually in the theme's _css-variables.scss file, or they can be placed at the end of the theme's _variables.scss file. This positions the arrays after the SCSS variables are defined, which CSS variables may require.

Using Look & Feel CSS Customization

To redefine one or more of the CSS variables, the variable name and the new value for it can be input in the Look & Feel admin customization text area, inside the :root array or under another appropriate selector, as indicated in the tables above. This could also be in a custom.css file.

Future possibilities

• A dedicated Look & Feel "CSS Variables" text area provided so that just the variables could be entered and the root array syntax would be added on the backend.
• New Tiki CSS variables in addition to those listed above — what other Tiki page elements should easy customization be enabled for?
• Site color controls (or other controls) available to site users on the public side, such as for dark mode, like switching themes but not needed a page refresh. — This is implemented in Bootstrap 5.3 and will be in the upcoming Tiki 26 release.

References:

• https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties
• https://css-tricks.com/a-complete-guide-to-custom-properties/
• https://blog.getbootstrap.com/2022/05/16/using-bootstrap-css-vars/
• https://getbootstrap.com/docs/5.3/customize/color-modes/ (This is already in development for Tiki.)
• https://getbootstrap.com/docs/5.2/customize/css-variables/
• https://getbootstrap.com/docs/4.0/getting-started/theming/#css-variables
• https://pedromarquez.dev/blog/2022/7/dark-mode-css