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 you're using modules or using the framework you can customize the default Sass property values using overrides loaded before StyleMods when compiling.

@use 'stylemods/scss' with (
  $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 or in the StyleMods repository.

Using modules overrides (anchor)

If using modules in a single document you can include the overrides in the document:

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

You can also include the overrides in an external document:

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

If you're using modules in multiple documents you can also include overrides within each file to keep specific styles self-contained.

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

Then include with your styles and if required still use global overrides for other elements with no impact on the isolated styles:

@use "overrides";
@use "reset";
@use "stylemods/scss" as *;
@include dialogs-css;
@include popovers-css;
<-- etc. -->

Using framework overrides (anchor)

Include your overrides as shown above in an external document. If required this can also be used to enable elements for compiling enabling you to keep all your custom overrides self-contained within a single document.

If you're compiling the framework from stylemods.scss you can add the overrides to it for compiling, this only requires adding it again when/if updating StyleMods to a newer version so wouldn't be difficult to maintain.

@use "overrides";
@use "configuration" as *;
@use "framework" as *;

If using the framework in a custom setup you simply include the overrides before StyleMods for compiling:

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

If compiling the framework the same overrides document can be used to enable elements for compiling

Colors (anchor)

The colors 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 the tints values can still be customized individually if required.

@use 'stylemods/scss' with (
  $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)

Where CSS variable tokens mixins are provided by default contained within a :where(html) pseudo-class wrapper style the default value can also be customized to use :root or another selector if preferred or required:

@use 'stylemods/scss' with (
  $color-tokens: ':root',
  $theme-tokens: ':root',
  $grid-tokens: ':root',
  $svg-icon-tokens: ':root',
);

Grid values (anchor)

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

@use 'stylemods/scss' with (
  $grid-column-values: 6,
  $grid-row-values: 3,
);

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

@use 'stylemods/scss' with (
  $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' with (
  $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' with (
  $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)

The color, utilities and layout modules all use Sass maps to help generate the individual styles and variables, as does the icons to help generate the SVG icon variable tokens. These are all included as !default value maps so can be used to control and customize what's included as well as expanding existing styles.

You can customize the values directly instead of using overrides for the Sass variables as described above:

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

To add a single value to a default map you can use map-set values with a variable to include for compiling:

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

For multiple values you can create a custom map and use map-merge to combine it with the default map to compile both sets of values:

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

Wherever maps use common values such as the gaps, margins and padding you can merge a custom map with all three to ensure utility modifiers included are consistent:

@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);
@include gaps-css;
@include margins-css;
@include padding-css;

Alternatively instead of merging maps you could also just 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;
@include gaps-css;
@include margins-css;
@include padding-css;

External maps (anchor)

The custom maps can be included with the styles as shown above or using a different document if preferred:

@use "stylemods/scss" as *;
@use "maps" as *;
<-- mixin modules -->

@use "sass:map";
@use "stylemods/scss" as *;
<-- maps -->

Like the Sass and CSS variables there's nothing stopping you from creating a reusable global Sass maps document for use with multiple projects. 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/