Background info on CSS variables

Custom properties (sometimes referred to as CSS variables or cascading variables) are entities defined by CSS authors that contain specific values to be reused throughout a document. They are set using custom property notation (e.g., --main-color: black;) and are accessed using the var() function (e.g., color: var(--main-color); ).
-- https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties

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

Top and topbar module zones (navbars)


For Tiki 26, the CSS variables used for the top and topbar module zones (navbars) have been reorganized. Instead of CSS variables with specific color ("light" or "dark") names, in Tiki 26 the variable names don't mention color themselves. Instead, neutral-color names are used in each combination of color and location — 1) light / top, 2) light / topbar, 3) dark / top, and 4) dark / topbar. This will facilitate using them with whole-website color mode switching in Tiki 26, which uses Bootstrap 5.3.

Selector (Bold) and Variable Name Description
.tiki-top-nav-light { Top module zone, light option (set in Look and Feel admin)
.tiki-top-nav-dark { Top module zone, dark option (set in Look and Feel admin)
--tiki-top-bg Top module zone background color (CSS color, gradient, image, etc.)
--tiki-top-color Links in top module zone
--tiki-top-hover-color Hover color for "
--tiki-top-hover-bg Color of link background during pointer hover
Link active color isn't implemented . . . . . . but can be if requested.
Link active background isn't implemented . . . . . . but can be if requested.
--tiki-top-text-color Applies to text such as log-in form labels in header mode (added for Tiki 26.1).
--tiki-top-border Style and color of border on the top zone, such as solid black
--tiki-top-border-width Width of border on the top zone, such as 2px
--tiki-top-box-shadow Box shadow on the top zone, such as 0px 2px 5px grey . Note that "0" requires a unit (px, etc.) in a CSS variable. Also, normally there is no space around the top navbar so a shadow is not likely to be visible unless spacing is configured for it.
}
.tiki-topbar-nav-light { Topbar module zone, light option (set in Look and Feel admin)
.tiki-topbar-nav-dark { Topbar module zone, light option (set in Look and Feel admin)
--tiki-topbar-bg Topbar background color (CSS color, gradient, image, etc.)
--tiki-topbar-color Color of text, etc. other than links. This is available but not currently used. Covers only immediate child elements.
--tiki-topbar-hover-color Hover color for "
Link active color isn't implemented . . . . . . but can be if requested.
--tiki-topbar-hover-bg Color of link background during pointer hover
Link active background color isn't implemented . . . . . . but can be if requested.
--tiki-topbar-text-color Applies to text such as log-in form labels in header mode (added for Tiki 26.1).
--tiki-topbar-border Style and color of border on the topbar zone, such as solid black
--tiki-topbar-border-width Width of border on the top zone, such as 2px
--tiki-topbar-box-shadow Box shadow on the top zone, such as 0px 2px 5px grey . Note that "0" requires a unit (px, etc.) in a CSS variable. Also, a shadow may not be visible unless spacing is configured for it.
}

Site Title and Subtitle (Logo module)

Selector (Bold) and Variable Name Description
:root { Use ":root" for global application (all layouts and pages, etc.)
--tiki-site-title-font-size Font size and weight (this row and below) for the logo module in the Classic Tiki and Single Container layouts. (These variables are used in themes/base_files/scss/_tiki-modules.scss.)
--tiki-site-title-font-weight
--tiki-site-subtitle-font-size
--tiki-site-subtitle-font-weight
--tiki-fixed-top-site-title-font-size Font size and weight (this row and below) for the logo module in the Classic Bootstrap (layout_social, fixed-top) layout (likely smaller than for the static position).
--tiki-fixed-top-site-title-font-weight
--tiki-fixed-top-site-subtitle-font-size
--tiki-fixed-top-site-subtitle-font-weight
--tiki-site-title-color (These variables are used in an inline style in templates/modules/mod-logo.tpl.)
--tiki-site-subtitle-color
}

Unified Admin Backend

The variables below are used on the new (Unified Admin Backend) admin pages for the top and side navbars and menus. (The top navbar's background is specified separately with a different selector, below.*)

Selector (Bold) and Variable Name Description
.tiki .tiki-admin-top-nav-light,
.tiki .tiki-admin-aside-nav-light {
Selectors used by "Admin navbar background color" Light option
.tiki .tiki-admin-top-nav-dark,
.tiki .tiki-admin-aside-nav-dark {
Selectors used by "Admin navbar background color" Dark option
--tiki-admin-top-nav-color Link color (link labels and icons) in the top navbar
--tiki-admin-top-nav-hover-color Link color when pointer hovers, in the top navbar
--tiki-admin-top-nav-hover-bg Color of link background when pointer hovers
--tiki-admin-aside-nav-bg Background color of side-column menu. Normally specified by the theme to be the same as top navbar background color but, like all of these selectors, it can be overridden.
--tiki-admin-aside-nav-color Link color (text and icons) in the side menu
--tiki-admin-aside-nav-hover-color Link color when pointer hovers, in the side menu
--tiki-admin-dropdown-bg Background color of top navbar menu dropdowns, including the login module, etc., and of the side menu dropdown sections.
--tiki-admin-dropdown-link-color Link color (link labels and icons) in the menu dropdowns
--tiki-admin-dropdown-link-hover-color Link label and icon color when pointer hovers, in the menu dropdowns
--tiki-admin-dropdown-link-hover-bg Link background color when pointer hovers, in the menu dropdowns
}
.tiki.tiki-admin .top_modules.navbar-light-parent { Selector used by "Admin navbar background color" Light option
.tiki.tiki-admin .top_modules.navbar-dark-parent { Selectos used by "Admin navbar background color" Dark option
--tiki-admin-top-nav-bg Background color of the top navbar
}

Miscellaneous

Selector (Bold) and Variable Name Description
:root { Applies globally.
--tiki-page-content-top-margin To create white space at the top of the content area, below the site header, input code just like this in the Look & Feel admin CSS Customization form, with a pixel, em, or rem size. Example: :root { --tiki-page-content-top-margin: 15px; }. Other global CSS variables can also be placed in this array (between the curly braces).
}

Selector and Variable Name Notes
:root {
--tiki-top-bg-light
--tiki-top-light-color
--tiki-top-light-link-color
--tiki-top-light-link-hover-color
--tiki-top-light-link-hover-bg
--tiki-top-light-box-shadow
--tiki-topbar-bg-light
--tiki-topbar-light-color
--tiki-topbar-light-link-color
--tiki-topbar-light-link-hover-color
--tiki-topbar-light-link-hover-bg
--tiki-topbar-light-box-shadow
--tiki-topbar-light-border
--tiki-topbar-border-width for light and dark topbars
--tiki-top-bg-dark
--tiki-top-dark-color
--tiki-top-dark-link-color
--tiki-top-dark-link-hover-color
--tiki-top-dark-link-hover-bg
--tiki-top-dark-box-shadow
--tiki-top-dark-border
--tiki-top-border-width
--tiki-topbar-bg-dark
--tiki-topbar-dark-color
--tiki-topbar-dark-link-color
--tiki-topbar-dark-link-hover-color
--tiki-topbar-dark-link-hover-bg
--tiki-topbar-dark-box-shadow
--tiki-topbar-dark-border
--tiki-static-top-light-border this and the following, for Classic Tiki and Single Container layouts
--tiki-static-top-dark-border
}
header.navbar.fixed-top { These are very explicit because they are used in the calculation of the site logo image; their scope is limited to header.fixed-top.
--tiki-fixed-top-border-top-width
--tiki-fixed-top-border-right-width
--tiki-fixed-top-border-bottom-width
--tiki-fixed-top-border-left-width
--tiki-top-light-border-color
--tiki-top-dark-border-color
}


Related, there are also these CSS variables for the site title and subtitle, in fixed-top position (Basic Bootstrap layout) and static position (Classic Tiki and Single Container layouts) and their default values:

    --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:

From the Feb12 theme's _tiki-selectors.scss file
Copy to clipboard
.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:

From the Feb12 theme's _css-variables.scss file
Copy to clipboard
: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: