Overwriting CSS

In Totara most of the CSS has been written using SCSS. This provides a large number of benefits when creating and modifying themes.

Adding a CSS file to your theme

Adding a minor change to a few small areas can done by placing a CSS file in theme/<your theme name>/styles directory and adding the name of the css stylesheet to the $THEME->sheets array within your theme's config.php file (note: this will need to include RTL declarations if required). This will not require SCSS compilation (but changes wont take effect until the cache is cleared unless the themedesignermode setting is enabled).

Compiling SCSS

Make sure you have the npm packages installed by running npm ci or npm install in the server directory.

Then run npx grunt css in the server directory.

Modifying SCSS

We want to make use of SCSS variables, so the regular Moodle approach to CSS inheritance (include CSS from all themes starting from parent working down) won't work. Instead we:

• Disable Moodle CSS inheritance using $THEME->parents_exclude_sheets

• Within scss/totara.scss, include theme/variables and theme/styles from the parent theme(s) - if major customisation is required, it may be beneficial to copy the file from the parent theme and remove import directives for some components.

• Create scss/theme/variables.scss and scss/theme/styles.scss files, and add the imports to scss/totara.scss.

• The imports should be grouped such that all variables imports come first, followed by all styles imports.

• Add any theme-specific SCSS imports to the two files you created in scss/theme

• Finally override any variables set by the parent theme that you want to change (see next section on overriding)

There are some notable differences between LESS, used in Totara < 13 and SCSS, which makes the correct order of files critical.

Overriding Totara-specific styles

Many configurable aspects are exposed as CSS variables, such as colours and font sizes. If there’s a CSS variable exposed, it’s usually better to override the value of that rather than directly targeting an element.

Many of the same names of variables are used between the server directory and Tui, so you should also set the variables in the Tui component of your theme.

CSS variables you can override include:

• Colours

• Gap base

• Font size and line height bases

• Font sizes, weights, families, etc for body and heading fonts

Check the server/theme/legacy/scss/totara/css_variables/ directory to see the existing variables.