Mixins

variables

accessibility

$accessibility: 'AA' !default;

Description

Defines the default accessibility for all mixins. Can be AA, AAA, or false.

Example

@use 'sass-themes' with ($accessibility: 'AAA');

Used by

[mixin] create
[mixin] accessibility
[mixin] accessibility

base-styles

$base-styles: 'extend' !default;

Description

Defines how base styles (setting text, background, and border colors) are included by default. Can be extend, include, or false. By default, styles are extended so that they can be overridden by the same specificity rules.

Example

@use 'sass-themes' with ($base-styles: false);

functions

[private] _classify

@function _classify($str) { ... }

Description

Turns a string into a class name. Leaves strings formatted as selectors unmodified.

Parameters

parameter Name	parameter Description	parameter Type	parameter Default value
`$str`	— none	`String`	— none

Returns

String

Used by

[mixin] create

mixins

[private] _create

@mixin _create($text, $bg, $brand: null, $styles: $base-styles) { ... }

Description

Defines the CSS properties for a theme class. Uses the define mixin from the scss-properties library.

Parameters

parameter Name	parameter Description	parameter Type	parameter Default value
`$text`	— none	`Color`	— none
`$bg`	— none	`Color`	— none
`$brand`	— none	`Color`	`null`
`$styles`	Controls how base styles (setting text, background, and border colors) should be added.	`'extend'` or `'include'` or `False`	`$base-styles`

Output

Output is simplified for readability. Actual output shown in comments.

body, .light {
  --light-theme:      1;                                          // 1 if text color is darker than background, else 0
  --dark-theme:       0;                                          // opposite --light-theme
  --theme-tx:         #111;                                       // hsla(var(--theme-tx-h), var(--theme-tx-s), var(--theme-tx-l), var(--theme-tx-a));
  --theme-bg:         white;                                      // hsla(var(--theme-bg-h), var(--theme-bg-s), var(--theme-bg-l), var(--theme-bg-a));
  --theme-br:         royalblue                                   // hsla(var(--theme-br-h), var(--theme-br-s), var(--theme-br-l), var(--theme-br-a));
  --button-text:      if($brand and not $light-theme, $text, $bg) // hsla(var(--button-text-h), var(--button-text-s), var(--button-text-l), var(--button-text-a));
  --button-bg:        $brand or $text                             // hsla(var(--button-bg-h), var(--button-bg-s), var(--button-bg-l), var(--button-bg-a));
  --theme-tx--light:  #{scss-properties.mix(                      // rgba(calc((var(--theme-tx-r) * (0.58 + (0.18 * var(--theme-dark)))) + (var(--theme-bg-r) * (1 - (0.58 + (0.18 * var(--theme-dark)))))),
                        --theme-tx,                               //      calc((var(--theme-tx-g) * (0.58 + (0.18 * var(--theme-dark)))) + (var(--theme-bg-g) * (1 - (0.58 + (0.18 * var(--theme-dark)))))),
                        --theme-bg,                               //      calc((var(--theme-tx-b) * (0.58 + (0.18 * var(--theme-dark)))) + (var(--theme-bg-b) * (1 - (0.58 + (0.18 * var(--theme-dark)))))),
                        '(0.58 + (0.18 * var(--theme-dark)))'     //      calc((var(--theme-tx-a) * (0.58 + (0.18 * var(--theme-dark)))) + (var(--theme-bg-a) * (1 - (0.58 + (0.18 * var(--theme-dark)))))));
                      )};

  color:              var(--theme-tx);
  background-color:   var(--theme-bg);
  border-color:       var(--theme-tx);
}

Used by

[mixin] create

create

@mixin create($tx, $bg, $br: null, $accessibility: $accessibility, $styles: 'extend', $keywords: null) { ... }

Description

Wrapper for _create, which normalizes arguments and keyword aliases before creating a theme. Must define at least a text and a background color.

Parameters

parameter Name	parameter Description	parameter Type	parameter Default value
`$tx`	Aliases: `$text`, `$color`, `$text-color`, `$--theme-tx`	`Color`	— none
`$bg`	Aliases: `$background`, `$background-color`, `$--theme-bg`	`Color`	— none
`$br`	Aliases: `$brand`, `$brand-color`, `$--theme-br`	`Color`	`null`
`$accessibility`	The accessibility standard to check this themes colors against.	`'aaa'` or `'aa'` or `False`	`$accessibility`
`$styles`	Controls how base styles (setting text, background, and border colors) should be added.	`'extend'` or `'include'` or `False`	`'extend'`
`$keywords`	A map that sets multiple the parameter values if passed as the only argument.	`Map`	`null`

Example

@use 'sass-themes';

body, .light {
  // using keyword arguments
  @include sass-themes.create(
    $tx: #111,
    $bg: white,
    $br: royalblue
  )
}

.dark {
  // using a map of keyword arguments
  @include sass-themes.create((
    --theme-tx: white;
    --theme-bg: #111;
    --theme-br: royalblue;
  ));
}

@use 'sass-themes';

@include sass-themes.create((
  // using a map of class names and keyword arguments
  'light': (
      --theme-tx: #111,
      --theme-bg: white,
      --theme-br: royalblue ),
  'dark': (
      --theme-tx: white,
      --theme-bg: #111,
      --theme-br: royalblue )));

Throws

theme must specify at least text and background colors: #{&}

Requires

[function] _classify
[mixin] _create
[mixin] accessibility
[variable] accessibility

accessibility

@mixin accessibility($text, $bg, $brand: null, $accessibility: $accessibility) { ... }

Description

Checks the color contrast ratios against the WCAG standards. Throws a warning when the provided colors do not meet the standard.

Parameters

parameter Name	parameter Description	parameter Type	parameter Default value
`$text`	— none	`Color`	— none
`$bg`	— none	`Color`	— none
`$brand`	— none	`Color`	`null`
`$accessibility`	The accessibility standard to check this themes colors against.	`'aaa'` or `'aa'` or `False`	`$accessibility`

Requires

[variable] accessibility
[variable] accessibility

Used by

[mixin] create

base

@mixin base() { ... }

Description

The styles applied to all theme classes after their properties have been defined.

Parameters

None.

Styles: Base

variables

link-selector

$link-selector: '.theme-link' !default;

Description

Name of the class that applies the default theme styles for links.

Used by

[css] :link, #{$link-selector}:link
[css] :visited, #{$link-selector}:visited
[css] a:hover, #{$link-selector}:hover

anchor-override

$anchor-override: '.subtle-link' !default;

Description

Name of the class that unsets the default theme styles for links.

Used by

[css] #{list.join($anchor-override, (), 'comma', false)}

css

blockquote

blockquote { ... }

Description

Default styles for blockquotes.

pre, code

pre,
code { ... }

Description

Default styles for code blocks.

input[type='text'], textarea

input[type='text'],
textarea { ... }

Description

Default styles for form fields.

:link, #{$link-selector}:link

:link,
#{$link-selector}:link { ... }

Description

Default styles for link elements.

:visited, #{$link-selector}:visited

:visited,
#{$link-selector}:visited { ... }

Description

Default styles for visited links.

a:hover, #{$link-selector}:hover

a:hover,
#{$link-selector}:hover { ... }

Description

Default styles for darkened links.

#{list.join($anchor-override, (), 'comma', false)}

#{list.join($anchor-override, (), 'comma', false)} { ... }

Description

Override default link styles.

Styles: Backgrounds

variables

overlay

$overlay: 0.5 !default;

Description

Opacity of the .overlay class

Used by

[css] .overlay

heavy-overlay

$heavy-overlay: 0.75 !default;

Description

Opacity of the .heavy-overlay class

Used by

[css] .heavy-overlay

css

.theme-bg

.theme-bg { ... }

Description

Applies the --theme-bg to an element's background color.

.no-bg

.no-bg { ... }

Description

Removes an element's background color.

.overlay

.overlay { ... }

Description

Applies a semi-transparent --theme-bg to an element's background color.

.heavy-overlay

.heavy-overlay { ... }

Description

Same as .overlay, but with a separate control.

Styles: Borders

variables

border-light

$border-light: 10% !default;

Description

Percent of text color mixed with background in the .border-light class.

border-x-light

$border-x-light: 5% !default;

Description

Percent of text color mixed with background in the .border-x-light class.

css

&-light

&-light { ... }

Description

Applies a subtle color to border styles, relative to --theme-tx and --theme-bg. @name .border-light @require $border-light

&-x-light

&-x-light { ... }

Description

Applies an even subtler color to border styles, relative to --theme-tx and --theme-bg. @name .border-x-light @require $border-x-light

Styles: Buttons

variables

btn-hover-mix

$btn-hover-mix: 80% !default;

Description

Controls how much the .button and .button-o elements react on hover.

Used by

[css] .button

css

.button

.button { ... }

Description

Button element with an opaque, branded background.

&.subtle-button

&.subtle-button { ... }

Description

More subtle styling for the .button class @name .button.subtle-button @require {css} .button

&-o

&-o { ... }

Description

Button element with default background and branded outlines. @name .button-o

&.subtle-button:not(:hover)

&.subtle-button:not(:hover) { ... }

Description

More subtle styling for the .button-o class @name .button-o.subtle-button @require {css} .button-o

Styles: SVG

css

.fill-color-theme

.fill-color-theme { ... }

Description

SVG fill classes.

.stroke-color-theme

.stroke-color-theme { ... }

Description

SVG stroke classes.

Styles: Text

css

.text-light

.text-light { ... }

Description

Light text, relative to background color.

.text-brand

.text-brand { ... }

Description

Applies the brand color to text.

Utilities

functions

if-light

@function if-light($true, $false) { ... }

Description

Returns one of two values depending on whether the current theme is light or dark. The values can either be custom CSS properties produced by the create mixin, or any CSS value that can be multiplied in a calc() function.

Parameters

parameter Name	parameter Description	parameter Type	parameter Default value
`$true`	— none	`String` or `Number`	— none
`$false`	— none	`String` or `Number`	— none

Returns

Value —

a calc function that resolves to $true on light themes and $false on dark themes.

Example

.theme-class {
  color: sass-themes.if-light(--theme-tx, --theme-br);
}

.theme-class {
  height: sass-themes.if-light(100px, 80em);
}

if-dark

@function if-dark($true, $false) { ... }

Description

Same as if-light but reversed.

Parameters

parameter Name	parameter Description	parameter Type	parameter Default value
`$true`	— none	`String` or `Number`	— none
`$false`	— none	`String` or `Number`	— none

Returns

Value —

a calc function that resolves to $true on dark themes and $false on light themes.

See

[function] if-light

Mixins

variables

Description

Example

Used by

Description

Example

functions

[private] _classify

Description

Parameters

Returns

Used by

mixins

[private] _create

Description

Parameters

Output

Used by

Description

Parameters

Example

Throws

Requires

Description

Parameters

Requires

Used by

Description

Parameters

Styles: Base

variables

Description

Used by

Links

Description

Used by

Links

css

Description

Links

Description

Links

Description

Links

Description

Links

Description

Links

Description

Links

Description

Links

Styles: Backgrounds

variables

Description

Used by

Description

Used by

css

Description

Description

Description

Links

Description

Links

Styles: Borders

variables

Description

Description

css

Description

Description

Styles: Buttons

variables

Description

Used by

Links

css

Description