Surface colors

Overview (anchor)

The surface colors combine the system colors Canvas and CanvasText using color-mix values to create a palette of colors that match in contrast across light and dark color-schemes with the default Canvas color designed to be customized to match the page backgrounds to use the surface colors for theme based design.

Variables (anchor)

By default there's no tokens and values for the --surface or --background variables so both fallback to the Canvas color unless custom values are included.

:where(html) {
  --surf-1: color-mix(in srgb, CanvasText 4%, var(--surface, var(--background, Canvas)));
  --surf-2: color-mix(in srgb, CanvasText 8%, var(--surface, var(--background, Canvas)));
  --surf-3: color-mix(in srgb, CanvasText 13%, var(--surface, var(--background, Canvas)));
  --surf-4: color-mix(in srgb, CanvasText 20%, var(--surface, var(--background, Canvas)));
  --surf-5: color-mix(in srgb, CanvasText 28%, var(--surface, var(--background, Canvas)));
  --surf-6: color-mix(in srgb, CanvasText 35%, var(--surface, var(--background, Canvas)));
  --surf-7: color-mix(in srgb, CanvasText 42%, var(--surface, var(--background, Canvas)));
  --surf-8: color-mix(in srgb, CanvasText 50%, var(--surface, var(--background, Canvas)));
  --surf-9: color-mix(in srgb, CanvasText 58%, var(--surface, var(--background, Canvas)));
  --surf-10: color-mix(in srgb, CanvasText 65%, var(--surface, var(--background, Canvas)));
  --surf-11: color-mix(in srgb, CanvasText 72%, var(--surface, var(--background, Canvas)));
}

The var(--background, Canvas) variable is used for color throughout all the styles so if included adapts the surfaces and all other colors used. The theme colors (used on this site) provides custom colors for the variable using light-dark(#eaecee, #1f2428) color values demonstrating exactly how this works.

Alternatively the --surface variable with higher specificity can still be used to customize the surface color palette separately with or without the --background variable being used globally.

Utilities (anchor)

Backgrounds (anchor)

The surface background utilities provide the background colors using the variables and default text colors that can be customized prior to compiling or inline with variables if required.

Borders (anchor)

The border utilities provide border-color values using the variables, they're designed as modifier classes* that can be used with the StyleMods borders or similar utilities.

*No size, style, position and/or radius properties are included.

Custom utilities (anchor)

As with the color utilities, you can also use the surface variables with the color mixin utility to create custom modifiers for StyleMods utilities and components.

Using the module (anchor)

Load StyleMods as demonstrated (change file path as required) then include the Sass mixin anywhere below.

Variables (anchor)

The variables are included by default within a :where(html) pseudo-class wrapper but can be customized with overrides to use :root or your preferred tokens style.

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

You can also bring the variables by themselves to include with others (above or below) within the same wrapper:

@use "stylemods/scss" as *;
:where(html) {
  @include surface-variables;
  <-- other variables -->
}

You can also include the variables as above in your preferred wrapper styles without overriding the default values.

Utilities (anchor)

All can be included with a single mixin:

@use "stylemods/scss" as *;
@include surface-utilities-css;

The backgrounds and borders can also be included individually:

@use "stylemods/scss" as *;
@include surface-backgrounds-css;
@include surface-borders-css;

Combined (anchor)

You can also include both the variables and all the utility modifiers using one mixin:

@use "stylemods/scss" as *;
@include surface-module;

See the using modules page for more information.

Using the framework (anchor)

Using the recommended custom setup enable the styles in an overrides document:

@use "stylemods/scss/configuration" as *;
$enable-surface:             true; // variable tokens
$enable-surface-utilities:   true;

The utilities can also be enabled individually:

@use "stylemods/scss/configuration" as *;
$enable-surface:               true;
$enable-surface-backgrounds:   true;
$enable-surface-borders:       true;

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

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

See using the framework for more information.

Source code (anchor)

The Surface colors source file is included with the color module files, you can view the source code from the latest release (v1.5.0) via the Github link below.

Source document

stylemods/scss/color/surface.scss

View on Github

https://github.com/pmbrown/StyleMods/blob/main/scss/color/surface.scss

Shared documentation about how to customize the default property values for the styles using the Sass and CSS variables is provided on the customizing page.