SCSS

Clay CSS Framework provides some utilities for you to work with SCSS(https://sass-lang.com) and reuse it in your classes.

Variables
- Default Flag
- Sass Maps
Mixins
- Extending With Mixins
Functions

Variables

Think of variables as a way to store information that you want to reuse throughout your stylesheet. You can store things like colors, font stacks, or any CSS value you think you'll want to reuse. Sass uses the $ symbol to make something a variable.

Example:

// Alert Dismissible

$alert-dismissible-padding-bottom: null !default;
$alert-dismissible-padding-left: null !default;
$alert-dismissible-padding-right: 2.5rem !default; // 40px
$alert-dismissible-padding-top: null !default;

All variables available

Default Flag

All variables provided by Clay CSS are defined with the !default flag. Default values in Sass are only assigned if the variable isn't defined or its value is null. This allows Clay CSS variables to be overwritten by variables placed or imported at the top of base.scss and atlas.scss.

Unfortunately, Clay CSS variables with the !default flag can't be overwritten with a null !default value due to the Sass spec. We work around this with Sass maps. Nested Sass map values don't use the !default flag allowing us to skirt the rule.

The snippet below illustrates how values get assigned to variables in Sass:

// Overwrites

$primary: red !default;
$secondary: null !default;
$info: #2e5aac !default;
$success: null;
$danger: #da1414 !default;

// Original Values

$primary: #0b5fff !default;
$secondary: #6b6c7e !default;
$info: null !default;
$success: #287d3c !default;
$danger: null;

Result:

$primary   => red
$secondary => #6b6c7e
$info      => #2e5aac
$success   => #287d3c
$danger    => null

Sass Maps

Clay CSS heavily leverages Sass maps. The main reason is to be able to reset values to null since Sass doesn't output a CSS declaration if its value is null. This is a great feature. It lets us reuse CSS rulesets instead of having to redeclare and overwrite. This saves a lot in terms of file size.

Assigning a null value to a CSS Custom Property (CSS Variable) generated with Sass will still be output.

The map-merge is a Sass function that takes two maps as parameters and combines them. The second parameter wins over the first. This means, if there are duplicate keys, the key value pair in the second map will win. We pass in our default values as the first parameter and an empty map as the second. The empty map $my-component: () !default can be filled with overwrites that will win over the defaults.

If we start with the code below:

$my-component: () !default;
$my-component: map-merge(
	(
		background-color: null,
		color: #000,
	),
	$my-component
);

.my-component {
	background-color: map-get($my-component, background-color);
	color: map-get($my-component, color);
}

Output:

.my-component {
	color: #000;
}

We can overwrite the original $my-component: () !default; with our new Sass map below. This tells Sass to output no properties.

// Overwrite

$my-component: (
	background-color: null,
	color: null,
) !default;

// Original

$my-component: () !default;
$my-component: map-merge(
	(
		background-color: null,
		color: #000,
	),
	$my-component
);

.my-component {
	background-color: map-get($my-component, background-color);
	color: map-get($my-component, color);
}

Output:

/* Nothing is output because both values are `null` */

Mixins

Sass mixins are used in Clay CSS to define custom CSS components, such as .btn, .dropdown-menu, and .label. Mixins help normalize the CSS selector output and are mostly used to generate variants of an existing CSS component. Take clay-button-variant for example, it accepts a Sass map as a parameter with several predefined keys. We can create our own purple btn variant in our _custom.scss with:

_custom.scss

$btn-custom: (
	background-color: #6200ee,
	color: #fff,
	font-size: 0.875rem,
	letter-spacing: 0.0892857143em,
	text-transform: uppercase,
	hover: (
		background-color: #651fff,
		color: #fff,
	),
	focus: (
		background-color: #7c4dff,
	),
	active: (
		background-color: #b388ff,
	),
	disabled: (
		background-color: #e0e0e0,
		color: #9e9e9e,
	),
);

.btn-custom {
	@include clay-button-variant($btn-custom);
}

Output:

.btn-custom {
	background-color: #6200ee;
	color: #fff;
	font-size: 0.875rem;
	letter-spacing: 0.08928571em;
	text-transform: uppercase;
}

.btn-custom:hover {
	background-color: #651fff;
	color: #fff;
}

.btn-custom:focus,
.btn-custom.focus {
	background-color: #7c4dff;
}

.btn-custom:active,
.btn-custom.active,
.show > .btn-custom.dropdown-toggle {
	background-color: #b388ff;
}

.btn-custom:disabled,
.btn-custom.disabled {
	background-color: #e0e0e0;
	color: #9e9e9e;
}

Your html:

<button class="btn btn-custom" type="button">Custom Btn</button>
<a class="btn btn-custom" href="#" role="button"
	>Custom Anchor that Looks Like a Button</a
>

Modifying the btn or variant classes like btn-primary directly can have unintended consequences. Liferay uses these classes in all admin controls, modifying them will change styles there as well. We recommend extending by creating your own modifier classes.

Extending With Mixins

The proper way to extend components in your theme is to piggy back of the base class and add modifier classes to change them. We will continue with our Custom Button example. In Atlas Theme (Classic), btn is 40px tall by default. If we want to make our default btn shorter (36px) and narrower we can create our own base modifier.

$my-btn-base: (
	padding: 0.40625rem 0.5rem,
);

$btn-custom: (...);

.my-btn-base {
	@include clay-button-variant($my-btn-base);
}

.btn-custom {
	@include clay-button-variant($btn-custom);
}

Your html:

<button class="btn my-btn-base btn-custom" type="button">Custom Btn</button>
<a class="btn my-btn-base btn-custom" href="#" role="button"
	>Custom Anchor that Looks Like a Button</a
>

This gives us the most compatibility with default Liferay styles and our custom styles. This pattern will also make it a lot easier to integrate with Clay React Components.

If you are up for the task of unifying admin controls with your site's theme, go ahead and modify all our components directly.

You can find all mixins available by component if you want to create a component extension.

All mixins available

Functions

Clay CSS Sass functions are generally only for internal use. Many of our functions were written so we could comply with Bootstrap 4's patterns as well as providing support for variable themeing.

We do provide some functions that may help you be more productive. Some of the noteworthy ones are clay-icon($name, $color), clay-svg-url($svg), and math-sign($num).

The function clay-icon($name, $color) takes a Clay SVG icon name and color. It returns the icon as a data uri to be used as a background-image.

.check-icon-bg {
	background-image: clay-icon(
		check,
		orange
	); // check svg icon as background image
	background-repeat: no-repeat;
	background-size: contain;
	display: inline-block;
	margin-bottom: 10px;
	margin-right: 15px;
	padding-left: 28px;
}

clay-svg-url($svg) accepts an SVG as a parameter. The SVG must be wrapped in single quotes ('') or double quotes ("") depending on whether attributes are delimited by double quotes or single quotes.

.check-icon-bg {
	background-image: clay-svg-url(
		'<svg id="check" viewBox="0 0 512 512"><path class="lexicon-icon-outline" d="M192.9,429.5c-8.3,0-16.4-3.3-22.3-9.2L44.5,294.1C15,263.2,62.7,222,89.1,249.5L191.5,352l230-258.9 c27.2-30.5,74.3,11.5,47.1,41.9L216.4,418.9c-5.8,6.5-14,10.3-22.6,10.6C193.5,429.5,193.2,429.5,192.9,429.5z"></path>
</svg>'
	);
	background-repeat: no-repeat;
	background-size: contain;
	display: inline-block;
	margin-bottom: 10px;
	margin-right: 15px;
	padding-left: 28px;
}

math-sign($number) takes a number as a parameter and returns the opposite value, generally used for null values so Sass doesn't output a value -null This is useful for offseting border-width among other things.

.offset-border {
	padding-top: math-sign(0.5rem - $border-top-width);
}

All functions available