Customizing

Customize default property values with Sass overrides, with CSS variables before and after compiling, or use the Sass maps for expanding, customizing and creating new styles.

Sass variables (anchor)

Whether using modules or using the framework you customize the default Sass property values using overrides the same way.

@use "stylemods/scss" as *;
$body-font-size:          1.1rem;
$button-padding-inline:   0.75rem;
$table-padding-inline:    0.75rem;

All the Sass variables are self-contained within the associated style module, you can view the source code for each on the individual docs pages on the website or in the StyleMods repository.

Using modules (anchor)

If using modules you load the overrides before the styles for compiling:

@use "overrides";
@use "stylemods/scss" as *;
@include typography-css;
@include forms-buttons-css;
@include tables-css;

Or if preferred you can also include the overrides with the styles:

@use "stylemods/scss" as *;
$body-font-size:          1.1rem;
$button-padding-inline:   0.75rem;
$table-padding-inline:    0.75rem;
@include typography-css;
@include forms-buttons-css;
@include tables-css;

You can also include multiple overrides documents and include them separately for compiling:

@use "content-overrides";
@use "component-overrides";
@use "stylemods/scss" as *;
@include all-content-css;
@include all-components-css;

Using the framework (anchor)

If using the framework the overrides document is also loaded before the styles for compiling:

@use "overrides";
@use "stylemods/scss/stylemods";

Or if preferred you can also include the overrides with the styles if you're not customizing a lot of values:

@use "stylemods/scss" as *;
$body-font-size:          1.1rem;
$button-padding-inline:   0.75rem;
$table-padding-inline:    0.75rem;
@use "stylemods/scss/stylemods";

You can also include multiple overrides and include them separately for compiling:

@use "content-overrides";
@use "component-overrides";
@use "stylemods/scss/stylemods";

Depending on how you're using the framework the same overrides document for customizing can also be used to enable the elements for compiling, or like above these could also be setup as separate overrides for different modules.

@use "stylemods/scss" as *;
$body-font-size:          1.1rem;
$button-padding-inline:   0.75rem;
$table-padding-inline:    0.75rem;

@use "stylemods/scss/configuration" as *;
$enable-typography:       true;
$enable-forms-buttons:    true;
$enable-tables:           true;

Colors (anchor)

The color variables use color-mix() values to create the tints using the default base HEX colors provided so customizing the base color will automatically adjust the tint colors accordingly, but if required the tints values can still be customized individually.

@use "stylemods/scss" as *;
$blue:  Navy;
$red:   FireBrick;
$green: DarkGreen;

If preferred you can change the color palettes to use alternative color values than the default HEX and color-mix() included.

Token styles (anchor)

By default the different sets of CSS variable tokens are compiled within :where(html) pseudo-class styles (shown below) that can be customized with overrides to use :root or another selector if preferred or required:

@use "stylemods/scss" as *;
$color-tokens:      ':where(html)';
$theme-tokens:      ':where(html)';
$semantic-tokens:   ':where(html)';
$grid-tokens:       ':where(html)';
$svg-icon-tokens:   ':where(html)';

Grid values (anchor)

The default 12 columns and 6 rows included with the grid layouts can be customized with variable overrides:

@use "stylemods/scss" as *;
$grid-column-values:  6;
$grid-row-values:     3;

The same with the 12 columns provided by default with the grid templates:

@use "stylemods/scss" as *;
$fraction-grid-values:  6;
$auto-grid-values:      6;

Component icons (anchor)

The default SVG icons used with the accordions and alerts components can also be customized with overrides to use icon options provided with each of the modules. The Sass variables from the icons can also be used the same way.

@use "stylemods/scss" as *;
$open-accordion:    $accordion-caret-down-icon;
$close-accordion:   $accordion-caret-up-icon;
$close-alert:       $alert-close-box-icon;

If included the icons token variables can be used to replace the Sass variables to save replicating the values in two places.

@use "stylemods/scss" as *;
$open-accordion:    var(--plus);
$close-accordion:   var(--minus);
$close-alert:       var(--close);

CSS variables (anchor)

A majority of the styles use property values inherited through fallbacks for empty CSS variables. As fallback values these are also not dependent on global variables unless you choose to include them. If the method doesn't suit, or you want to change the variable names and/or default fallback values, you can use overrides to customize the Sass variables as shown above.

$text-color:        var(--text, CanvasText) !default;
$background-color:  var(--background, Canvas) !default;
etc.
$h1-font-size:      var(--h1-fs, 2.125rem) !default;
$h2-font-size:      var(--h2-fs, 1.75rem) !default;
etc.

Global variables (anchor)

With no preset values the variables can be used globally for theme design. The optional theme colors leverage the color value variables used in the styles this way to create the tokens to override the default fallback values with (customizable) theme colors.

:where(html) {
  --text: light-dark(#444, #eee)
  --background: light-dark(PowderBlue, MidnightBlue)
  --h1-fs: 2.2rem;
  --h2-fs: 1.8rem;
}

Component variables (anchor)

You can also use the variables to create custom component styles using semantic elements, classes or ID styles. The color utilities leverage the variables this way to create the optional colored modifier classes for StyleMods components and utilities.

article {
  --h1-fs: 3rem;
  --h2-fs: 2rem;
  --heading-lh: 1.2;
  --heading-mb: 1rem;
  --para-fs: 1.1rem;
  --para-mb: 1.5rem;
  --para-tw: balance;
}
section {
  --h2-fs: 1.75rem;
  --heading-fw: 500;
  --heading-mb: 0.25rem;
}
aside {
  --h2-fs: 1.3rem;
  --list-mb: 0.5rem;
  --li-ps: 0.5rem;
  --marker: 'square';
}

Inline styles (anchor)

You can use the variables with inline HTML styles to customize individual elements on-the-fly:

<h1 style="--h1-fs:4rem;">Hello world!</h1>

Like the component variables you can use an inline style on a container to customize child elements:

<section style="--h2-fs:2rem; --para-fs:1.2rem; --marker:'square';">
<h2>More info</h2>
<p>The quick brown fox jumps over the lazy dog.</p>
<ul>
  <li>Item 1</li>
  <li>Item 2</li>
  <li>Item 3</li>
</ul>
</section>

Sass maps (anchor)

Whether using modules or the framework the Sass maps used with some styles can be used to control and customize and/or expand existing styles. They can be included with the same overrides documented above or in a maps overrides document loaded the same way.

The default maps can be used with custom values:

@use "sass:map";
@use "stylemods/scss" as *;
$gap-sizes: (
  "1": 0.5rem,
  "2": 1rem,
  "3": 1.5rem,
);

You can add a single value to a default map with map-set values within a variable:

@use "sass:map";
@use "stylemods/scss" as *;
$gap-sizes: map.set($gap-sizes, "6", 3rem);

You can add multiple values in a custom map and use map-merge to combine it with the default map values:

@use "sass:map";
@use "stylemods/scss" as *;
$expanded-sizes: (
  "6": 3rem,
  "7": 4rem,
);
$gap-sizes: map.merge($gap-sizes, $expanded-sizes);

Where maps use common values you can merge them with a custom map to provide consistent custom values:

@use "sass:map";
@use "stylemods/scss" as *;
$expanded-sizes: (
  "6": 3rem,
  "7": 4rem,
);
$gap-sizes: map.merge($gap-sizes, $expanded-sizes);
$margins-sizes: map.merge($margins-sizes, $expanded-sizes);
$padding-sizes: map.merge($padding-sizes, $expanded-sizes);

You could also create a custom map to use for common values:

@use "sass:map";
@use "stylemods/scss" as *;
$custom-sizes: (
  "1": 0.5rem,
  "2": 1rem,
  "3": 1.5rem,
);
$gap-sizes: $custom-sizes;
$margins-sizes: $custom-sizes;
$padding-sizes: $custom-sizes;

For more information about using Sass maps see the documentation on their website:

• https://sass-lang.com/documentation/values/maps/
• https://sass-lang.com/documentation/modules/map/