Customizing CSS

If you’re a beginner/intermediate user of CSS you may look under the hood of Mai Theme and see things look a little stranger than you’re used to when it comes to our CSS. Mai Theme makes extensive use of “custom properties,” also known as “CSS variables” to allow much more efficient overrides when customizing your theme, and much less overall code in our themes themselves.

Understanding Custom Properties (CSS Variables)

An easy way to think about custom properties is to think of them as variables you can “intercept” before the element itself is declared. Many of our custom properties are there purely for this reason; they aren’t even used in our code. We offer the property, but just use the default. If you change a setting or intercept the property in your own CSS code, that is what’s used instead.

The CSS doesn’t need to cascade or override because the custom property value itself has been changed before it’s used.

Let’s look at a real example in our themes.

All of our menus have font weight, size, and family custom properties available, though they aren’t used in every theme. See below (don’t copy this snippet):

.menu {
    font-weight: var(--menu-font-weight, inherit);
    font-size: var(--menu-font-size, var(--font-size-md));
    font-family: var(--menu-font-family, inherit);
}Copy

Since these properties are not used, you can just intercept them early on, in the root of the document like this:

:root {
    --menu-font-size: 16px;
    --menu-font-family: var(--heading-font-family);
    --menu-font-weight: var(--heading-font-weight);
}Copy

The above code tells all of our menus to use the heading font family and weight (as selected in the Customizer) and a font size of 16px.

If you want to only apply these changes to a specific menu, you can target that menu only, like this:

.nav-header {
    --menu-font-size: 16px;
    --menu-font-family: var(--heading-font-family);
    --menu-font-weight: var(--heading-font-weight);
}Copy

Code Snippets

Also note, any code on the :root element can be combined. So the following CSS

:root {
    --menu-font-family: var(--heading-font-family);
    --menu-font-weight: var(--heading-font-weight);
}

:root {
    --button-letter-spacing: 2px;
    --button-text-transform: uppercase;
}Copy

can be combined into:

:root {
    --menu-font-family: var(--heading-font-family);
    --menu-font-weight: var(--heading-font-weight);
    --button-letter-spacing: 2px;
    --button-text-transform: uppercase;
}Copy

Navigation Menus

.nav-header {
    --menu-font-size: 16px;
    --menu-font-family: var(--heading-font-family);
    --menu-font-weight: var(--heading-font-weight);
    --menu-letter-spacing: 1px;
    --menu-text-transform: uppercase;
    --menu-item-link-color: var(--color-black);
    --menu-item-link-color-hover: var(--color-primary);
    --menu-item-link-text-decoration: none;
    --menu-item-link-text-decoration-hover: none;   
}Copy

.nav-after-header {
    background: var(--color-primary);
    --menu-font-size: 16px;
    --menu-font-family: var(--heading-font-family);
    --menu-font-weight: var(--heading-font-weight);
    --menu-letter-spacing: 1px;
    --menu-text-transform: uppercase;
    --menu-item-link-color: var(--color-white);
    --menu-item-link-color-hover: var(--color-white);
    --menu-item-link-background-hover: var(--color-primary-dark);
    --menu-item-link-text-decoration: none;
    --menu-item-link-text-decoration-hover: none;   
}Copy

Site Header

.site-header {
    color: var(--color-white);
    --site-header-background: var(--color-heading);
    --mobile-menu-background: var(--color-heading);
    --title-area-color: var(--color-white);
    --link-color-hover: var(--color-white); /* Site title text hover */
    --heading-color: var(--color-white);
    --menu-item-link-color: var(--color-white);
    --menu-item-link-color-hover: var(--color-primary);
    --menu-item-link-text-decoration: none;
    --menu-item-link-text-decoration-hover: none; /* optionally add underline here */
}Copy

.has-sticky-header.header-stuck .site-header {
    --site-header-background: var(--color-heading);
    --menu-item-link-color: var(--color-white);
    --menu-item-link-color-hover: var(--color-primary);
}Copy

Mobile Menu Toggle Icon

.menu-toggle {
    --menu-item-link-color: var(--color-primary);
    --menu-item-link-color-hover: var(--color-primary-dark);
}Copy

.has-sticky-header.header-stuck .menu-toggle {
    --menu-item-link-color: var(--color-primary);
    --menu-item-link-color-hover: var(--color-primary-dark);
}Copy

Mobile Menu

.mobile-menu {
    color: var(--color-white);
    --mobile-menu-background: var(--color-heading);
    --heading-color: var(--color-white);
    --menu-item-link-color: var(--color-white);
    --menu-item-link-color-hover: var(--color-white);
    --menu-item-link-text-decoration: none;
    --menu-item-link-text-decoration-hover: underline;
}Copy

Buttons

:root {
    --button-font-size: 0.8em;
    --button-font-family: var(--heading-font-family);
    --button-font-weight: var(--heading-font-weight);
    --button-letter-spacing: 2px;
    --button-text-transform: uppercase;
    --button-color: var(--color-white);
    --button-color-hover: var(--color-white);
    --button-background: var(--color-custom-1); /* Custom color 1 set in Customizer > Theme Settings > Colors */
    --button-background-hover: var(--color-custom-2); /* Custom color 2 set in Customizer > Theme Settings > Colors */
}Copy

:root {
    --button-secondary-color: var(--color-white);
    --button-secondary-color-hover: var(--color-white);
    --button-secondary-background: var(--color-custom-1); /* Custom color 1 set in Customizer > Theme Settings > Colors */
    --button-secondary-background-hover: var(--color-custom-2); /* Custom color 2 set in Customizer > Theme Settings > Colors */
}Copy

.entry-more-link {
    --button-color: #515151;
    --button-color-hover: #515151;
    --button-background: #ebe9eb;
    --button-background-hover: #dad8da;
}Copy

Font Sizes (Scaling System)

Mai Theme is built on a scaling system for font sizes and spacing. Instead of thinking about specific heading levels and sizes, it’s better to think of the scale itself.

Font Sizes

The default font sizing system is as follows:

:root {
    --font-size-base: 16px;
    --font-scale: 1.25;
    --font-scale-responsive: 0.15vw;

    --font-size-xs: calc(var(--font-size-sm) / var(--font-scale));
    --font-size-sm: calc(var(--font-size-md) / var(--font-scale));
    --font-size-md: calc(var(--font-size-base) + var(--font-scale-responsive));
    --font-size-lg: calc(var(--font-size-md) * var(--font-scale));
    --font-size-xl: calc(var(--font-size-lg) * var(--font-scale));
    --font-size-xxl: calc(var(--font-size-xl) * var(--font-scale));
    --font-size-xxxl: calc(var(--font-size-xxl) * var(--font-scale));
    --font-size-xxxxl: calc(var(--font-size-xxxl) * var(--font-scale));
}Copy

The only thing you should need to change are the first two or three properties.

–font-base

This is the base font size used before adding the scales.

–font-scale

The --font-scale property is the ratio at which heading sizes are scaled up from, according to the base font size. A couple of great visual examples of this are the Type Scale and Module Scale websites. If you change the base, or the scale, you can see the font sizes adjust accordingly.

–font-scale-responsive

The --font-scale-responsive property is also used to help the overall sizes to scale slightly smaller/larger on mobile devices vs larger desktop monitors.

:root {
    --font-scale: 1.125; /* Major Second */
}Copy

Body

To customize the body font size without altering the scale for headings, you can use the following:

:root {
    --body-font-size: 18px;
}Copy

Or adjust the line-height:

:root {
    --body-line-height: 1.625;
}Copy

Headings

If you want to set a specific font size for a specific heading level, this is very easily done by intercepting the heading level custom properties.

:root {
    --h1-font-size: 2em;
    --h2-font-size: 1.75em;
}Copy

Or, override a specific heading, like the page header title, like so:

.page-header-title {
    --h1-font-size: 2.5em;
}Copy

Or adjust the line-height for all headings:

:root {
    --heading-line-height: 1.32;
}Copy

Subheadings

.is-style-subheading {
    --heading-font-size: var(--font-size-lg);
    --heading-text-transform: uppercase;
    --heading-letter-spacing: 1px;
}Copy

Mai Theme also provides a “Subheading” block style for the Heading and Paragraph blocks. You can easily add some custom styling by adjusting our custom properties. The default values in Mai Engine are as follows.

Page Header

Mai Themes like Mai Delight have custom boxed styling on the Page Header inner container. The code below is an example of what you see in Mai Delight.

.page-header-inner:not(:empty) {
     --page-header-inner-background: rgba(255, 255, 255, 0.9);
     --page-header-inner-padding: var(--spacing-xl) var(--spacing-xl);
     --page-header-inner-border-radius: var(--border-radius);
     --page-header-inner-box-shadow: var(--box-shadow);
 }Copy

If you want to change the Page Header inner styling, you can modify the code above. If you want to completely remove the inner styling you can use the following code.

.page-header-inner {
    --page-header-inner-background: none;
    --page-header-inner-padding: 0;
    --page-header-inner-border-radius: 0;
    --page-header-inner-box-shadow: 0;
}Copy