Theme colors

Customizable theme color variables to use with StyleMods styles, components and utilities.

Overview (anchor)

All the following style modules have theme color options if enabled:

They use the variables included in the styles as follows:

typography.scss
$text-color:        var(--text, CanvasText) !default;
$background-color:  var(--background, Canvas) !default;

To provide custom color tokens to override the fallback values:

styles.css
:where(html) {
  --text: light-dark(#000, #fff);
  --background: light-dark(#eaecee, #1f2428);
}

The typography styles include the text, links and page background colors, the rest of the styles primarily include theme values for properties such as background and border colors using common theme surface colors provided.

Using the module (anchor)

See the links above to view how to include the individual style modules. If you're not including the typography styles (with the page background colors) information is provided below on how to include the background colors with custom styles.

Surface variables (anchor)

Option 1. Includes the 5 surface colors required for the theme styles:

custom.scss
@use "stylemods/scss" as *;
@include theme-surface-colors-css;

Option 2. Includes 12 theme surface colors:

custom.scss
@use "stylemods/scss" as *;
@include theme-surface-colors-palette-css;

Option 3. Includes 12 default surface colors, requires typography styles and theme colors:

custom.scss
@use "stylemods/scss" as *;
@include surface-variables-css;
@include theme-typography-css;
@include typography-css;

Theme variables (anchor)

Using one of surface color options above the theme colors can be included individually:

custom.scss
@use "stylemods/scss" as *;
@include theme-typography-css;
@include theme-forms-buttons-css;
@include theme-tables-css;
@include theme-accordions-css;
@include theme-alert-css;
@include theme-badge-css;
@include theme-border-css;
@include theme-dialog-css;
@include theme-card-css;
@include theme-list-group-css;
@include theme-popover-css;

Or using a single mixin:

custom.scss
@use "stylemods/scss" as *;
@include theme-variables-css;

Grouped (anchor)

You can also include the surface and theme color variables grouped with a single mixin. The following includes all the theme color variables with the base surface palette with 5 colors described in option 1 above:

custom.scss
@use "stylemods/scss" as *;
@include theme-surface-variables-css;

Or with the full palette including 12 colors described in option 2:

custom.scss
@use "stylemods/scss" as *;
@include theme-surface-palette-variables-css;

Background colors (anchor)

If you're not using StyleMods typography (with the page background properties) you can use the base surface color variable for background colors in your own styles if required:

style.css
:where(html) {
  background-color: var(--surface);
}

Token style (anchor)

By default the variables tokens above are including using a :where(html) pseudo-class style. You can customize the token style as detailed on the customizing page or include the variables only in your own pseudo-class style:

custom.scss
@use "stylemods/scss" as *;
:root {
  @include theme-variables;
}

See the using modules page for more information including how to compile the modules in cascade layers and include and reuse them in multiple source files.

Using the framework (anchor)

Using the recommended custom setup enable the styles in an overrides document. See the links above to view how to enable the individual style modules.

Only one of the surface color options below is required, but neither is needed if you're using the typography styles and colors, and the default surface colors.

overrides.scss
@use "stylemods/scss/configuration" as *;
$enable-theme-surface:            true; // 5 colors
$enable-theme-surface-palette:    true; // 12 colors
$enable-theme-typography:         true;
$enable-theme-forms-buttons:      true;
$enable-theme-tables:             true;
$enable-theme-accordions:         true;
$enable-theme-alerts:             true;
$enable-theme-badges:             true;
$enable-theme-borders:            true;
$enable-theme-dialogs:            true;
$enable-theme-dropdowns:          true;
$enable-theme-cards:              true;
$enable-theme-list-groups:        true;
$enable-theme-popovers:           true;

Include the overrides and the framework styles with your custom document for compiling the framework:

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

See using the framework for more information including how the styles can also be compiled within cascade layers.

Source code (anchor)

The modules and the framework follow the same methods for customizing the default values and using the CSS variables to create custom theme documents. See the customizing page for more information.

theme.scss
// ---------------------------------------------------------- 
// Theme colors
// ----------------------------------------------------------
@use "surface" as *;

// Tokens style
$theme-tokens:                ':where(html)' !default;

// Colors
$theme-text:                  light-dark(#000, #fff) !default;
$theme-link:                  light-dark(#1c3db5, #9fbfdf) !default;
$theme-link-visited:          light-dark(#4f6fe3, #b3cce6) !default;
$theme-link-hover:            light-dark(#385de0, #c6d8ec) !default;
$theme-background:            light-dark(#eaecee, #1f2428) !default;

$theme-surface:               var(--background) !default;
$theme-surface-1:             var(--surf-1) !default;
$theme-surface-2:             var(--surf-2) !default;
$theme-surface-3:             var(--surf-3) !default;
$theme-surface-4:             var(--surf-4) !default;
$theme-table-stripes:         color-mix(in srgb, CanvasText 1%, var(--background)) !default;
$theme-table-hover:           color-mix(in srgb, CanvasText 2%, var(--background)) !default;

// Variables
$theme-surfaces: (
  "surface": $theme-background,
  "surf-1": $surface-1,
  "surf-2": $surface-2,
  "surf-3": $surface-3,
  "surf-4": $surface-4,
) !default;

$theme-typography: (
  "text": $theme-text,
  "background": $theme-background,
  "link": $theme-link,
  "visited": $theme-link-visited,
  "hover": $theme-link-hover,
  "kbd-bg": $theme-surface-2,
  "pre-bd-color": $theme-surface-3,
  "pre-bg": $theme-surface-1,
  "blockquote-bd-color": $theme-surface-3,
) !default;

$theme-forms-buttons: (
  "btn-bd-color": $theme-surface-4,
  "btn-bg": $theme-surface-1,
  "btn-hover": $theme-surface-2,
  "form-bd-color": $theme-surface-4,
  "form-bg": $theme-surface,
  "form-accent": $theme-link,
  "focus-color": $theme-surface-4,
) !default;

$theme-tables: (
  "table-bg": $theme-surface,
  "thead-bg": $theme-surface-1,
  "table-bd-color": $theme-surface-3,
  "table-stripes": $theme-table-stripes,
  "table-hover": $theme-table-hover,
) !default;

$theme-accordion: (
  "summary-bg": $theme-surface-1,
  "summary-focus": $theme-surface-2,
  "accordion-bd-color": $theme-surface-3,
) !default;

$theme-alert: (
  "alert-bg": $theme-surface-1,
  "alert-bd-color": $theme-surface-3,
) !default;

$theme-badge: (
  "badge-bg": $theme-surface-1,
  "badge-bd-color": $theme-surface-3,
) !default;

$theme-border: (
  "bd-color": $theme-surface-3,
) !default;

$theme-button: (
  "btn-bd-color": $theme-surface-4,
  "btn-bg": $theme-surface-1,
  "btn-hover": $theme-surface-2,
) !default;

$theme-card: (
  "card-bd-color": $theme-surface-3,
  "card-bg": $theme-surface,
  "card-hover": $theme-surface-1,
  "card-focus-color": $theme-surface-4,
  "card-title-bg": $theme-surface-1,
) !default;

$theme-dialog: (
  "dialog-bg": $theme-surface-1,
  "dialog-bd-color": $theme-surface-3,
  "dialog-title-bg": $theme-surface-2,
) !default;

$theme-dropdown: (
  "dropdown-bg": $theme-surface,
  "dropdown-bd-color": $theme-surface-3,
  "dropdown-btn-bg": $theme-surface-1,
  "dropdown-btn-hover": $theme-surface-2,
  "dropdown-focus-color": $theme-surface-4,
  "dropdown-link-hover": $theme-surface-1,
) !default;

$theme-list-group: (
  "list-group-dt-bg": $theme-surface-2,
  "list-group-hover": $theme-surface-1,
  "list-group-bd-color": $theme-surface-3,
  "list-group-bg": $theme-surface,
) !default;

$theme-popover: (
  "popover-bg": $theme-surface-1,
  "popover-bd-color": $theme-surface-3,
) !default;
color/mixins/theme.scss
// ---------------------------------------------------------- 
// Theme mixins
// ----------------------------------------------------------
@use "../theme" as *;

@mixin theme-surface-variables {
  @each $name, $value in $theme-surfaces {
    --#{$name}: #{$value};
  }
}

@mixin theme-surface-css {
  #{$theme-tokens} {
    @include theme-surface-variables;
  }
}

@mixin theme-typography-variables {
  @each $name, $value in $theme-typography {
    --#{$name}: #{$value};
  }
}

@mixin theme-typography-css {
  #{$theme-tokens} {
    @include theme-typography-variables;
  }
}

@mixin theme-forms-buttons-variables {
  @each $name, $value in $theme-forms-buttons {
    --#{$name}: #{$value};
  }
}

@mixin theme-forms-buttons-css {
  #{$theme-tokens} {
    @include theme-forms-buttons-variables;
  }
}

@mixin theme-tables-variables {
  @each $name, $value in $theme-tables {
    --#{$name}: #{$value};
  }
}

@mixin theme-tables-css {
  #{$theme-tokens} {
    @include theme-tables-variables;
  }
}

@mixin theme-accordions-variables {
  @each $name, $value in $theme-accordion {
    --#{$name}: #{$value};
  }
}

@mixin theme-accordions-css {
  #{$theme-tokens} {
    @include theme-accordions-variables;
  }
}

@mixin theme-alert-variables {
  @each $name, $value in $theme-alert {
    --#{$name}: #{$value};
  }
}

@mixin theme-alert-css {
  #{$theme-tokens} {
    @include theme-alert-variables;
  }
}

@mixin theme-badge-variables {
  @each $name, $value in $theme-badge {
    --#{$name}: #{$value};
  }
}

@mixin theme-badge-css {
  #{$theme-tokens} {
    @include theme-badge-variables;
  }
}

@mixin theme-border-variables {
  @each $name, $value in $theme-border {
    --#{$name}: #{$value};
  }
}

@mixin theme-border-css {
  #{$theme-tokens} {
    @include theme-border-variables;
  }
}

@mixin theme-button-variables {
  @each $name, $value in $theme-button {
    --#{$name}: #{$value};
  }
}

@mixin theme-button-css {
  #{$theme-tokens} {
    @include theme-button-variables;
  }
}

@mixin theme-card-variables {
  @each $name, $value in $theme-card {
    --#{$name}: #{$value};
  }
}

@mixin theme-card-css {
  #{$theme-tokens} {
    @include theme-card-variables;
  }
}

@mixin theme-dialog-variables {
  @each $name, $value in $theme-dialog {
    --#{$name}: #{$value};
  }
}

@mixin theme-dialog-css {
  #{$theme-tokens} {
    @include theme-dialog-variables;
  }
}

@mixin theme-dropdown-variables {
  @each $name, $value in $theme-dropdown {
    --#{$name}: #{$value};
  }
}

@mixin theme-dropdown-css {
  #{$theme-tokens} {
    @include theme-dropdown-variables;
  }
}

@mixin theme-list-group-variables {
  @each $name, $value in $theme-list-group {
    --#{$name}: #{$value};
  }
}

@mixin theme-list-group-css {
  #{$theme-tokens} {
    @include theme-list-group-variables;
  }
}

@mixin theme-popover-variables {
  @each $name, $value in $theme-popover {
    --#{$name}: #{$value};
  }
}

@mixin theme-popover-css {
  #{$theme-tokens} {
    @include theme-popover-variables;
  }
}

@mixin all-theme-variables {
  @include theme-typography-variables;
  @include theme-forms-buttons-variables;
  @include theme-tables-variables;
  @include theme-accordions-variables;
  @include theme-alert-variables;
  @include theme-badge-variables;
  @include theme-border-variables;
  @include theme-dialog-variables;
  @include theme-dropdown-variables;
  @include theme-card-variables;
  @include theme-list-group-variables;
  @include theme-popover-variables;
}

@mixin all-theme-variables-css {
  #{$theme-tokens} {
    @include all-theme-variables;
  }
}

// Use if surface.scss module not included.
@mixin all-theme-surface-variables {
  @include theme-surface-variables;
  @include all-theme-variables;
}

@mixin all-theme-surface-variables-css {
  #{$theme-tokens} {
    @include all-theme-surface-variables;
  }
}