#Configuration

Almost every aspect of Cirrus can be customized. You can modify existing component styles, add new utility classes, turn off some default styles, and more with the brand new configuration file.

#Schema

Before we get started on how to use Cirrus with configuration, let's talk about what the configuration object is. At its core, the structure of the default configuration object is shown below.

$default-config: (
    // Turn on/off generating viewport classes to save on size.
    viewports: (),
    // Extend all existing styles here
    extend: (),
    // Turn off certain features from being loaded. If left blank, all components are generated by default.
    excludes: (),
    // Enable certain classes to be generated. Takes precedence over $EXCLUDE.
    includes: (),

    // COMPONENTS //
    // Avatar sizes
    avatar-sizes: (...),
    ...

    // UTILITIES //
    absolute: (...),
    ...
) !default;

#Basics

The framework uses a primary configuration file in _config.scss to store defaults. Customization is as easy as loading a module with configuration as shown below:

@use "cirrus-ui/src/cirrus-ext" as * with (
    $config: (
        excludes: (
            ABSOLUTES,
        ),
        opacity: null, // Disable default opacity classes
        extend: (
            // Add your own
            opacity: (
                25: .25,
                50: .5,
                75: .75,
            )
        )
    ),
);

The with keyword allows us to pass in the $config object we want to use when generating the classes. The * simply allows us to reference all forwarded members within the framework after the @use statement.

All mixins, functions, etc. from the internal folder are forwarded so you can use them without additional imports.

@use "cirrus-ui/src/cirrus-ext" as * with (...);

// Example use of Cirrus internal APIs
@screen-above($md) {
    .my-class {
        background-color: rgba(#{hex-to-rgb(fill('blue', '600'))}, .25);
    }
}

#Viewports

The viewport field is used to set generating viewports for classes on and off. You can turn off some of the already enabled viewport classes to same on memory if needed.

A viewport variant is simply a variation of an existing class suffixed with a breakpoint, which follows the pattern (class)-[xs|sm|md|lg|xl].

For instance, if I enable the viewport variants for flex, then every flexbox associated utility class will also have viewport variant classes as well.

@use "cirrus-ui/src/cirrus-ext" as * with (
    $config: (
        viewports: (
            'FLEX': true
        ),
    )
);

.u-flex-column { ... }

@media screen and (min-width: 640px) {
    .u-flex-column-sm { ... }
}
@media screen and (min-width: 768px) {
    .u-flex-column-md { ... }
}
...

A full list of the supported flags can be found here.

#Extend

The extend field is used to generate additional classes or override defaults within the framework. For instance, I can add additional utility classes I want to generate for colors in this entry.

@use "cirrus-ui/src/cirrus-ext" as * with (
    $config: (
        extend: (
            colors: (
                semantic: (
                    'primary': #0066FF,
                    'midnight': #121062,
                )
            )
        )
    )
);

This config change will do 2 things:

1. Override the default primary color with #0066FF.
2. Add a new color called midnight.

Cirrus will then generate the following classes.

.bg-primary { background-color: #0066FF !important; }
.text-primary { color: #0066FF !important; }
...
.bg-midnight { background-color: #121062 !important; }
.text-midnight { color: #121062 !important; }
...

A full list of the supported extend entries can be found here.

#Clearing Default Settings

To clear defaults defined in Cirrus's default configuration, all we need to do is set the value of the classes you want to disable generation of defaults for to null. The example below replaces all the old semantic colors with a custom defined set of colors.

@use "cirrus-ui/src/cirrus-ext" as * with (
    $config: (
        semantic: null,
        extend: (
            // Replace with custom colors
            colors: (
                semantic: (
                    'white': '#ffffff',
                    'purple': '#3f3cbc',
                    'midnight': '#121062',
                    'metal': '#565684',
                    'tahiti': '#3ab7cf',
                    'silver': '#ececff',
                    'bubble-gum': '#ff77d9',
                    'bermuda': '#73dcca',
                )
            )
        )
    )
);

.bg-white { ... };
.bg-purple { ... };
.bg-midnight { ... };
...

#Excludes

The excludes field is used to disable features in Cirrus. For instance, if I add 'AVATAR' in this list, then Cirrus will skip generating all classes associated with the Avatar component.

@use "cirrus-ui/src/cirrus-ext" as * with (
    $config: (
        excludes: (
            'AVATAR'
        )
    )
);

Note that there is a special keyword, 'ALL', that would disable generation of all classes that are not within the base folder.

@use "cirrus-ui/src/cirrus-ext" as * with (
    $config: (
        excludes: (
            'ALL'
        )
    )
);

A full list of the supported feature flags to exclude can be found here.

#Includes

The includes field is used to enable features in Cirrus. This can happen if you were extending from a custom configured version of Cirrus that disabled some things you wanted to have. For instance, if I add 'AVATAR' in this list, then Cirrus will generate all classes associated with the Avatar component.

@use "cirrus-with-avatar-off" as * with (
    $config: (
        includes: (
            'AVATAR'
        )
    )
);

Another use case is if we decide to turn off all features except for a couple. The includes field is applied after Cirrus process excludes.

@use "cirrus-ui/src/cirrus-ext" as * with (
    $config: (
        excludes: ( 'ALL' ), // Disable everything not in base folder
        includes: (
            'AVATAR' // Only enable AVATAR component
        )
    )
);

Note that there is a special keyword, 'ALL', that would enable generation of all classes supported for that build (.e.g. core vs ext).

@use "cirrus-with-some-features-off" as * with (
    $config: (
        includes: (
            'ALL'
        )
    )
);