1. INTRODUCTION

SCSS lets you use variables and nested rules when writing styles. Kristal Framework compiles these files into CSS for the browser using scssphp.

You’ll work in these folders:

• App/media/css/scss/: Shared styles, including files in subfolders.
• App/media/css/themes/: Theme variables, such as colors.
• App/media/css/: The generated CSS files.

2. ENABLING COMPILATION

Edit these settings in config/config.php:

define("PRODUCTION_MODE", false);
define("AUTO_COMPILE_SCSS", true);
define("COMPILED_CSS_TYPE", "compressed");
define("DEFAULT_THEME", "dark");
define("PRINT_COMPILE_DATE_CSS", true);

compressed creates smaller CSS files. Choose expanded if you want the output to be easier to read. PRINT_COMPILE_DATE_CSS adds a comment showing when the file was compiled.

Save your SCSS changes and reload a page to generate the CSS.

3. WRITING STYLES

Create App/media/css/scss/components/welcome-card.scss:

.welcome-card {
    padding: 1.5rem;
    border-radius: 0.5rem;
    border: 1px solid currentColor;

    h2 {
        margin-top: 0;
    }

    a:hover {
        text-decoration: underline;
    }
}

All SCSS files in the scss/ folder and its subfolders are included automatically. You don’t need to import each one into main.scss.

4. CREATING THEMES

Let’s add an Ocean theme. Start by copying an existing theme to App/media/css/themes/ocean.scss so it includes the variables your shared styles need.

Add these two variables to the new file:

$welcome-background: #eaf7ff;
$welcome-text: #15334a;

Add the same variable names to your other themes with their own colors. For example, in dark.scss:

$welcome-background: #19222b;
$welcome-text: #edf5fc;

Then use them in welcome-card.scss:

.welcome-card {
    background: $welcome-background;
    color: $welcome-text;
}

Kristal Framework combines each theme with the shared styles, producing files such as ocean.css and dark.css.

If you have no theme files, Kristal Framework creates one stylesheet named after DEFAULT_THEME. In that case, define the needed variables in your shared styles before using them.

5. LOADING A THEME

The shared header chooses the session’s theme, or DEFAULT_THEME if none is saved. It uses this approach:

<?php $theme = Session::get("theme", DEFAULT_THEME); ?>
<link rel="stylesheet" href="<?= esc_url(css($theme)); ?>">

To select the Ocean theme you created, save its name in the session before the header is rendered:

Session::add("theme", "ocean");

The next stylesheet link will use ocean.css. To offer a theme choice through a form, use a form handler and check that the submitted name matches one of your themes before saving it.

6. PRODUCTION AND TROUBLESHOOTING

Generate all theme stylesheets before enabling PRODUCTION_MODE, then upload the CSS files. Edit your SCSS sources when making changes; compilation replaces the generated CSS.

If the styles don’t update:

• Check that compilation is enabled and PHP can write to the CSS folder.
• Make sure every theme defines the variables used by your styles.
• Look for SCSS errors in the debug output or log.

The compiler compares source times with the newest output CSS file. This can cause it to overlook one missing or older theme. To rebuild in development, remove the generated theme CSS files and make sure your SCSS changes are newer than any remaining CSS files, then reload a page.

Use SCSS syntax supported by the installed scssphp package. The configured version is 1.13.0.