Surface colors

Customizable surface color variables for mono or themed light-dark accent colors.

Overview (anchor)

The surface colors combine the system colors Canvas and CanvasText using color-mix values to create a palette of colors that adapt to keep the same contrast across light and dark color-schemes. The default Canvas color can be customized to match the page backgrounds to enable using the variables and/or utilities for color-scheme based theme design.

Variables (anchor)

The --surface color matches the page background so the border is provided for definition.

--surface

--surf-1

--surf-2

--surf-3

--surf-4

--surf-5

--surf-6

--surf-7

--surf-8

--surf-9

--surf-10

--surf-11

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

The (optional) theme colors used on this site provide values for the --background variable, so as demonstrated above the surface colors use the default light-dark(#eaecee, #1f2428) background color values provided with the theme colors.

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.

.bg-surf-1

.bg-surf-2

.bg-surf-3

.bg-surf-4

.bg-surf-5

.bg-surf-6

.bg-surf-7

.bg-surf-8

.bg-surf-9

.bg-surf-10

.bg-surf-11

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.

.bd-surf-1

.bd-surf-2

.bd-surf-3

.bd-surf-4

.bd-surf-5

.bd-surf-6

.bd-surf-7

.bd-surf-8

.bd-surf-9

.bd-surf-10

.bd-surf-11

*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.

custom.scss

@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:

custom.scss

@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:

custom.scss

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

The backgrounds and borders can also be included individually:

custom.scss

@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:

custom.scss

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

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:

overrides.scss

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

The utilities can also be enabled individually:

overrides.scss

@use "stylemods/scss/configuration" as *;
$enable-surface:               true;
$enable-surface-backgrounds:   true;
$enable-surface-backgrounds:   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.

color/surface.scss

// ---------------------------------------------------------- 
// Surface
// ----------------------------------------------------------
$surface:      var(--background, Canvas) !default;
$surface-1:    color-mix(in srgb, CanvasText 4%, var(--surface)) !default;
$surface-2:    color-mix(in srgb, CanvasText 8%, var(--surface)) !default;
$surface-3:    color-mix(in srgb, CanvasText 13%, var(--surface)) !default;
$surface-4:    color-mix(in srgb, CanvasText 20%, var(--surface)) !default;
$surface-5:    color-mix(in srgb, CanvasText 28%, var(--surface)) !default;
$surface-6:    color-mix(in srgb, CanvasText 35%, var(--surface)) !default;
$surface-7:    color-mix(in srgb, CanvasText 42%, var(--surface)) !default;
$surface-8:    color-mix(in srgb, CanvasText 50%, var(--surface)) !default;
$surface-9:    color-mix(in srgb, CanvasText 58%, var(--surface)) !default;
$surface-10:   color-mix(in srgb, CanvasText 65%, var(--surface)) !default;
$surface-11:   color-mix(in srgb, CanvasText 72%, var(--surface)) !default;

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

$surface-token-values: (
  "surface": $surface,
  "surf-1": $surface-1,
  "surf-2": $surface-2,
  "surf-3": $surface-3,
  "surf-4": $surface-4,
  "surf-5": $surface-5,
  "surf-6": $surface-6,
  "surf-7": $surface-7,
  "surf-8": $surface-8,
  "surf-9": $surface-9,
  "surf-10": $surface-10,
  "surf-11": $surface-11,
) !default;

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

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

color/utilities/surface.scss

// ---------------------------------------------------------- 
// Surface utilities
// ----------------------------------------------------------
@use "../surface" as *;

// Utility values
$text-default:    CanvasText;
$text-accent:     light-dark(#fff, #000) !default;
$bg-prefix:       bg- !default;
$bd-prefix:       bd- !default;

// Mixin styles
@mixin surface-background-values($color, $background) {
  color: var(--bg-txt, #{$color});
  background-color: #{$background};
}

@mixin surface-border-values($color) {
  border-color: #{$color};
}

// Utility mixins
@mixin surface-backgrounds-css {
  .#{$bg-prefix}surf-1 {
    @include surface-background-values($text-default, $surface-1);
  }
  
  .#{$bg-prefix}surf-2 {
    @include surface-background-values($text-default, $surface-2);
  }
  
  .#{$bg-prefix}surf-3 {
    @include surface-background-values($text-default, $surface-3);
  }

  .#{$bg-prefix}surf-4 {
    @include surface-background-values($text-default, $surface-4);
  }

  .#{$bg-prefix}surf-5 {
    @include surface-background-values($text-default, $surface-5);
  }

  .#{$bg-prefix}surf-6 {
    @include surface-background-values($text-default, $surface-6);
  }

  .#{$bg-prefix}surf-7 {
    @include surface-background-values($text-accent, $surface-7);
  }

  .#{$bg-prefix}surf-8 {
    @include surface-background-values($text-accent, $surface-8);
  }

  .#{$bg-prefix}surf-9 {
    @include surface-background-values($text-accent, $surface-9);
  }

  .#{$bg-prefix}surf-10 {
    @include surface-background-values($text-accent, $surface-10);
  }

  .#{$bg-prefix}surf-11 {
    @include surface-background-values($text-accent, $surface-11);
  }
}

// Borders
@mixin surface-borders-css {
  .#{$bd-prefix}surf-1 {
    @include surface-border-values($surface-1);
  }
  
  .#{$bd-prefix}surf-1 {
    @include surface-border-values($surface-1);
  }
  
  .#{$bd-prefix}surf-2 {
    @include surface-border-values($surface-2);
  }
  
  .#{$bd-prefix}surf-3 {
    @include surface-border-values($surface-3);
  }

  .#{$bd-prefix}surf-4 {
    @include surface-border-values($surface-4);
  }

  .#{$bd-prefix}surf-5 {
    @include surface-border-values($surface-5);
  }

  .#{$bd-prefix}surf-6 {
    @include surface-border-values($surface-6);
  }

  .#{$bd-prefix}surf-7 {
    @include surface-border-values($surface-7);
  }

  .#{$bd-prefix}surf-8 {
    @include surface-border-values($surface-8);
  }

  .#{$bd-prefix}surf-9 {
    @include surface-border-values($surface-9);
  }

  .#{$bd-prefix}surf-10 {
    @include surface-border-values($surface-10);
  }

  .#{$bd-prefix}surf-11 {
    @include surface-border-values($surface-11);
  }
}

@mixin surface-utilities-css {
  @include surface-backgrounds-css;
  @include surface-borders-css;
}