@ulu/frontend 0.0.22 → 0.1.0-beta.0

package/scss/_button.scss

@@ -14,45 +14,84 @@
 @use "utils";
 
 // Used for function fallback
-$-element-get: meta.get-function("get", false, "element");
 $-fallbacks: (
-  "box-shadow" : $-element-get
+  "box-shadow": meta.get-function("get", false, "element")
 );
 
 /// Module Settings
 /// @type Map
+/// @prop {String} active-selector ["&.is-active"] The selector that determines if a button is active
+/// @prop {CssValue} box-shadow [true] Specify box shadow for default button. Default true will fallback to element "box-shadow"
+/// @prop {Number} line-height [1.1] Line height for button
+/// @prop {Dimension} letter-spacing [0.02em]
+/// @prop {Dimension} margin [(0.45em 0.5em 0.45em 0)] Margin for buttons, usually left margin is omitted so buttons can flow inline and make space between them and the next element inline
+/// @prop {Dimension} min-width [9rem] The smallest width for all buttons
+/// @prop {Dimension} padding [(0.75em 1.5em)] Button inner padding value, pass space separated list
+/// @prop {CssValue} white-space [nowrap] Adjust button line wrapping, by default line's are not wrapped
+/// @prop {String} border-color ["control-border"] The border color for the button, usually if there is no border we set this to match the background color so if a button with no borders is adjacent a style that has borders the heights will match.
+/// @prop {String} border-color-hover ["control-border-hover"] Color of border when button is hovered
+/// @prop {String} border-color-active ["control-border-active"] Color of border when a button has active class
+/// @prop {Dimension} border-radius [2rem] Border Radius for button
+/// @prop {Dimension} border-width [1px] Width of button border
+/// @prop {String} background-color ["control-background"] Background color of button
+/// @prop {String} background-color-hover ["control-background-hover"] Background color of button when hovered
+/// @prop {String} background-color-active ["control-background-active"] Background color of button when active
+/// @prop {String} color ["control"] Text color of button
+/// @prop {String} color-hover ["control-hover"] Text color of button when hovered
+/// @prop {String} color-active ["control-active"] Text color of button when active
+/// @prop {CssValue} font-family [inherit] Font family for button
+/// @prop {CssValue} font-weight [bold] Font weight for button
+/// @prop {String} font-size ["base"] Font size for button, can be omitted if it should inherit, sizes can also work with utility type size classes
+/// @prop {Dimension} icon-size [2.5rem] The size of a button when used with an icon
+/// @prop {Dimension} icon-font-size [1.38rem] The font size for the icon when a button is an icon button
+/// @prop {Dimension} icon-border-radius [50%] The border radius of a icon button (defaults to 50% circle)
+/// @prop {CssValue} text-shadow [none] Text shadow for button
+/// @prop {CssValue} text-transform [none] Text transform for button
+/// @prop {CssValue} text-decoration [none] Text decoration of button
+/// @prop {Boolean} transition-enabled [true] Whether or not to enable transitions on button properties like background-color, color, border color as they change state
+/// @prop {Time} transition-duration [200ms] The duration of the button's transition if enabled
+/// @prop {List} transition-properties [(border-color, background-color, color, box-shadow)] The properties to transition if `transition-enabled` 
 
 $config: (
-  "padding":                 (0.75em 1.5em),
-  "background-color":        color.tint(black, 30%),
-  "background-color-hover": black,
-  "font-family":             inherit,
-  "white-space" :            nowrap,
-  "font-weight":             bold,
+  "active-selector":         "&.is-active",
+  "box-shadow":              true,
   "line-height":             1.1,
   "letter-spacing":          0.02em,
-  "text-transform":          none,
-  "text-shadow":             none,
-  "font-size":               "base",
-  "color":                   white,
-  "color-hover":            white,
-  "color-active":            white,
-  "box-shadow":              true,
-  "border-radius":           2rem,
-  "border-width":            0,
-  "border-color":            transparent,
-  "border-color-hover":     transparent,
   "margin":                  (0.45em 0.5em 0.45em 0),
   "min-width":               9rem,
+  "padding":                 (0.75em 1.5em),
+  "white-space":             nowrap,
+  "border-color":            "control-border",
+  "border-color-active":     "control-border-active",
+  "border-color-hover":      "control-border-hover",
+  "border-radius":           2rem,
+  "border-width":            1px,
+  "background-color":        "control-background",
+  "background-color-hover":  "control-background-hover",
+  "background-color-active": "control-background-active",
+  "color":                   "control",
+  "color-hover":             "control-hover",
+  "color-active":            "control-active",
+  "font-family":             inherit,
+  "font-weight":             bold,
+  "font-size":               "base",
   "icon-size":               2.5rem,
   "icon-font-size":          1.38rem,
   "icon-border-radius":      50%,
-  "text-decoration" :        none
+  "text-shadow":             none,
+  "text-transform":          none,
+  "text-decoration":         none,
+  "transition-enabled":      true,
+  "transition-duration":     200ms,
+  "transition-properties":   (border-color, background-color, color, box-shadow),
 ) !default;
-
+  
 /// Button sizes
+/// - A map that holds to the sizes for buttons in the theme
+/// - Use set-sizes() to adjust the sizes for the theme
+/// - Don't edit sizes variable directly
 /// @type Map
-
+  
 $sizes: (
   "small" : (
     "padding":        (0.35em 1.5em),
@@ -68,6 +107,8 @@ $sizes: (
 ) !default;
 
 /// Button styles
+/// - A map of styles for each button in the theme. Us set-styles() to overwrite or merge into these styles
+/// - Don't edit styles variable directly
 /// @type Map
 
 $styles: (
@@ -85,7 +126,7 @@ $styles: (
   "outline" : (
     "background-color" : transparent,
     "color" : "type",
-    "border-color" : "rule",
+    "border-color" : "rule-light",
     "box-shadow" : none,
     "hover" : (
       "background-color" : "white",
@@ -95,8 +136,8 @@ $styles: (
 
 /// Change modules $config
 /// @param {Map} $changes Map of changes
-/// @example scss - General example, replace module-name with module's name
-///   @include module-name.set(( "property" : value ));
+/// @example scss - General example
+///   @include ulu.button-set(( "property" : value ));
 
 @mixin set($changes) {
   $config: map.merge($config, $changes) !global;
@@ -104,15 +145,16 @@ $styles: (
 
 /// Get a config option
 /// @param {Map} $name Name of property
-/// @example scss - General example, replace module-name with module's name
-///   @include module-name.get("property");
+/// @example scss - General example
+///   @include ulu.button-get("property");
 
 @function get($name) {
   $value: utils.require-map-get($config, $name, "button [config]");
   @return utils.function-fallback($name, $value, $-fallbacks);
 }
 
-/// Set button styles
+/// Set button styles 
+/// - See $styles for example of structure of map
 /// @param {Map} $changes Map of changes
 /// @param {String} $merge-mode Merge mode see utils.map-merge() [null|"deep"|"overwrite"]
 
@@ -121,6 +163,7 @@ $styles: (
 }
 
 /// Set Button Sizes
+/// - See $sizes for example of structure of map
 /// @param {Map} $changes Map of changes
 /// @param {String} $merge-mode Merge mode see utils.map-merge() [null|"deep"|"overwrite"]
 
@@ -128,7 +171,7 @@ $styles: (
   $sizes: utils.map-merge($sizes, $changes, $merge-mode) !global;
 }
 
-/// Print styles to reset browser button style
+/// Reset CSS for button (to change browser defaults for button styling)
 
 @mixin reset() {
   text-transform: none;
@@ -143,7 +186,7 @@ $styles: (
   cursor: pointer;
 }
 
-/// Print default button styles
+/// Output the default button styles
 /// @param {Boolean} $with-reset [false] Include button.reset()
 
 @mixin default($with-reset: false) {
@@ -175,12 +218,17 @@ $styles: (
   white-space: get("white-space");
   max-width: 100%; // Questionable, not sure if it's needed
   flex-shrink: 0; 
-  // Should override link visted coloring
+  // Should override link visited coloring
+  
+  @if get("transition-enabled") {
+    transition-duration: get("transition-duration");
+    transition-property: get("transition-properties");
+  }
   &,
   &:visited {
     color: color.get(get("color"));
-    border: get("border-width") solid get("border-color");
-    background-color: get("background-color");
+    border: get("border-width") solid color.get(get("border-color"));
+    background-color: color.get(get("background-color"));
     text-decoration: get("text-decoration");
   }
   &:last-child {
@@ -188,14 +236,35 @@ $styles: (
   }
   &:hover,
   &:focus {
-    color: get("color-hover");
-    background-color: get("background-color-hover");
-    border-color: get("border-color-hover");
+    color: color.get(get("color-hover"));
+    background-color: color.get(get("background-color-hover"));
+    border-color: color.get(get("border-color-hover"));
     text-decoration: get("text-decoration");
   }
+  @include when-active() {
+    color: color.get(get("color-active"));
+    background-color: color.get(get("background-color-active"));
+    border-color: color.get(get("border-color-active"));
+  }
 }
 
-/// Print button size styles for a specifc size
+/// Mixin to wrap in active selectors
+/// - Use to match the button's active selector
+/// @example scss
+///   // Site specific styling for active button
+///   .button {
+///     @include when-active() {
+///       background: linear-gradient(0.25turn, #3f87a6, #ebf8e1, #f69d3c);
+///     }
+///   }
+
+@mixin when-active() {
+  #{ get("active-selector") } {
+    @content;
+  }
+}
+
+/// Print button size styles for a specific size
 /// @param {String} $name Name of size from $sizes
 /// @see $sizes
 /// @see set-sizes
@@ -218,16 +287,24 @@ $styles: (
 /// @see set-styles
 /// @return {*} The property you were trying to get
 
-@function get-style-value($name, $prop, $for-hover: false) {
-  $is-color-prop: string.index($prop, "color");
+@function get-style-value($name, $prop, $state: null) {
   $style: utils.require-map-get($styles, $name, 'button [color value]');
-  $hover: map.get($style, "hover");
-  $hover: if($hover, $hover, ());
-  $from: if($for-hover, $hover, $style);
+  $state-style: ();
+  // If a specific state [hover, active] grab that map
+  @if ($state) {
+    $state-style: map.get($style, $state);
+    $state-style: if($state-style, $state-style, ());
+  }
+  // From is the map to grab styles from
+  $from: if($state, $state-style, $style);
   $value: map.get($from, $prop);
-  $value: if($value, $value, map.get($style, $prop)); // Fallback to parent (if hover)
 
-  @if (meta.type-of($value) == "string" and $is-color-prop and $value != "inherit" and $value != "transparent") {
+  // Fallback to parent (if hover)
+  @if ($state == "hover") {
+    $value: if($value, $value, map.get($style, $prop)); 
+  }
+
+  @if (meta.type-of($value) == "string" and string.index($prop, "color")) {
     @return color.get($value);
   } @else {
     @return $value;
@@ -242,13 +319,16 @@ $styles: (
 /// @see set-styles
 
 @mixin style-styles($name) {
-  background-color: get-style-value($name, "background-color", false);
-  color: get-style-value($name, "color", false);
-  border-color: get-style-value($name, "border-color", false);
-  border-width: get-style-value($name, "border-width", false);
-  box-shadow: get-style-value($name, "box-shadow", false);
-  text-decoration: get-style-value($name, "text-decoration", false);
-  font-weight: get-style-value($name, "font-weight", false);
+  background-color: get-style-value($name, "background-color");
+  color: get-style-value($name, "color");
+  border-color: get-style-value($name, "border-color");
+  border-width: get-style-value($name, "border-width");
+  box-shadow: get-style-value($name, "box-shadow");
+  text-decoration: get-style-value($name, "text-decoration");
+  font-weight: get-style-value($name, "font-weight");
+  @if get-style-value($name, "transition-duration") {
+    transition-duration: get-style-value($name, "transition-duration");
+  }
 }
 
 /// Print a button style's base styles (hover styles only)
@@ -259,18 +339,26 @@ $styles: (
 /// @see set-styles
 
 @mixin style-styles-hover($name) {
-  background-color: get-style-value($name, "background-color", true);
-  color: get-style-value($name, "color", true);
-  border-color: get-style-value($name, "border-color", true);
-  box-shadow: get-style-value($name, "box-shadow", true);
-  text-decoration: get-style-value($name, "text-decoration", true);
+  background-color: get-style-value($name, "background-color", "hover");
+  color: get-style-value($name, "color", "hover");
+  border-color: get-style-value($name, "border-color", "hover");
+  box-shadow: get-style-value($name, "box-shadow", "hover");
+  text-decoration: get-style-value($name, "text-decoration", "hover");
+}
+
+@mixin style-styles-active($name) {
+  @include when-active() {
+    background-color: get-style-value($name, "background-color", "active");
+    color: get-style-value($name, "color", "active");
+    border-color: get-style-value($name, "border-color", "active");
+  }
 }
 
 /// Print a button style
 /// - Includes base/visited styling, and hover/focus state styles
 /// - To print only one of those states, use style-styles or style-styles-hover
 /// - By default this mixin prints the buttons base styles along with :visited state. 
-///   This is to avoid link visted states effecting the button styles (if used in editor areas 
+///   This is to avoid link visited states effecting the button styles (if used in editor areas 
 ///   or other areas that apply automatic links styling for example. (param below to override behavior)
 /// @param {String} $name Name of style from $styles
 /// @param {String} $no-visited [false] Do not include :visited selector for button base styles
@@ -290,4 +378,7 @@ $styles: (
   &:focus {
     @include style-styles-hover($name);
   }
+  @include when-active() {
+    @include style-styles-active($name);
+  }
 }

package/scss/_color.scss

@@ -5,32 +5,47 @@
 @use "sass:map";
 @use "sass:meta";
 @use "sass:string";
+@use "sass:color";
+
 @use "utils";
 @use "selector";
 
 /// The color palette map, can be extended or modified with set() and accessed with get()
-/// Note do not use names that start with "--" as those are reserved for custom-properties (pass through) also "inherit" is reserved.
+/// - Note do not use names that start with "var(" which are reserved for custom properties. Also do not use "inherit" or "transparent" as those are reserved.
+/// - The default palette color names are used throughout the system
 /// @type map  
 
 $palette: (
-  "black":        black,
-  "white":        white,
-  "type":         black,
-  "background":   white,
-  "focus":        blue,
-  "error":        red,
-  "warning":      orange,
-  "accent":       orange,
-  "selected" :    green,
-  "box-shadow":   rgba(0, 0, 0, 0.349),
-  "box-shadow:hover" : rgba(0, 0, 0, 0.5),
-  "rule":         gray,
-  "rule-light":   lightgray,
-  "link":         blue,
-  "link:hover":   darkblue,
-  "link:active":  darkblue,
-  "link:visited": purple,
-  "bullet":       inherit
+  "black"                   : black,
+  "white"                   : white,
+  "type"                    : black,
+  "type-secondary"          : rgb(82, 82, 82),
+  "type-tertiary"           : rgb(157, 157, 157),
+  "headline"                : inherit,
+  "background"              : white,
+  "focus"                   : blue,
+  "error"                   : red,
+  "warning"                 : orange,
+  "accent"                  : orange,
+  "selected"                : green,
+  "box-shadow"              : rgba(0, 0, 0, 0.349),
+  "box-shadow-hover"        : rgba(0, 0, 0, 0.5),
+  "rule"                    : gray,
+  "rule-light"              : lightgray,
+  "link"                    : blue,
+  "link-hover"              : darkblue,
+  "link-active"             : darkblue,
+  "link-visited"            : purple,
+  "bullet"                  : inherit,
+  "control"                 : white,
+  "control-hover"           : white,
+  "control-active"           : white,
+  "control-border"          : purple,
+  "control-border-hover"       : blue,
+  "control-border-active"       : orange,
+  "control-background"      : purple,
+  "control-background-hover": blue,
+  "control-background-active": orange,
 ) !default;
 
 /// Pairs of background-color and color definitions
@@ -53,6 +68,7 @@ $contexts: (
 );
 
 /// Palette entries that are output as classes when using all-color-class-styles
+/// - Use set-color-classes mixin to alter this map
 $color-classes: (
   "black" : true,
   "white" : true,
@@ -62,7 +78,7 @@ $color-classes: (
 /// Used to override or extend the color palette
 /// @param {Map} $changes A map to merge into the color palette
 /// @example scss Setting the error and type color
-///   @include color.set((
+///   @include ulu.color-set((
 ///     "type" : #444,
 ///     "error" : orange,
 ///   ));
@@ -73,13 +89,13 @@ $color-classes: (
 
 /// Get a color from the palette by name
 /// @param {String} $name Name of color to get
-/// @return {Color} Note if non-string value is passed it is sent back through, along with custom properties and keyword inherit
+/// @return {Color} Note if non-string value is passed it is sent back through, along with custom properties ("var(..." and keywords inherit and transparent. This is by design so that you can always pass a user's colors through this (without having to check if it's a color value or a string [color palette])
 
 @function get($name) {
   // Allow non lookup if the value is already a color (helps with code flow)
   @if (meta.type-of($name) == "string") {
-    // Allow custom-properties and keyword inherit to pass through
-    @if ($name == "inherit" or string.index($name, "var(") == 1) {
+    // Allow custom-properties and keyword inherit/transparent to pass through
+    @if ($name == "inherit" or $name == "transparent" or string.index($name, "var(") == 1) {
       @return $name;
     // Else look up the color from the palette
     } @else {
@@ -91,13 +107,15 @@ $color-classes: (
   @return $name;
 }
 
-/// Set ouput classes for all-color-class-styles
+/// Set output classes for all-color-class-styles
 /// @param {Map} $changes Map of changes (you can disable defaults this way)
 
 @mixin set-color-classes($changes) {
   $color-classes: map.merge($color-classes, $changes) !global;
 }
 
+/// Check if a color is set in the palette
+
 @function exists($name) {
   $color: map.get($palette, $name);
   @return if($color != null, true, false);
@@ -108,7 +126,7 @@ $color-classes: (
 /// @param {Map} $deep Use deep merge
 /// @param {Map} $overwrite Overwrite the completly (cannot be used with deep)
 /// @example scss Overwriting contexts
-///   @include color.set-contexts((
+///   @include ulu.color-set-contexts((
 ///     "dark" : (
 ///       "background-color" : red,
 ///       "color" : white,
@@ -135,7 +153,7 @@ $color-classes: (
 @function get-context-value($name, $prop) {
   $context: get-context($name);
   $value: map.get($context, $prop);
-  // Get from pallete by name
+  // Get from palette by name
   @if (meta.type-of($value) == "string") {
     $value: get($value);
   }
@@ -161,7 +179,7 @@ $color-classes: (
 /// @link https://css-tricks.com/snippets/sass/tint-shade-functions/ Modified from source (CSS Tricks, Kitty Giraudel)
 
 @function tint($color, $percentage) {
-  @return mix(get("white"), get($color), $percentage);
+  @return color.mix(get("white"), get($color), $percentage);
 }
 
 /// Darken a color with the default black by a percentage
@@ -172,7 +190,7 @@ $color-classes: (
 /// @link https://css-tricks.com/snippets/sass/tint-shade-functions/ Modified from source (CSS Tricks, Kitty Giraudel)
 
 @function shade($color, $percentage) {
-  @return mix(get("black"), get($color), $percentage);
+  @return color.mix(get("black"), get($color), $percentage);
 }
 
 /// Prints all context styles 

package/scss/_cssvar.scss

@@ -6,12 +6,14 @@
 @use "sass:meta";
 @use "sass:map";
 @use "sass:string";
+@use "sass:list";
+
 @use "utils";
 @use "breakpoint";
 
 /// Module Settings
 /// @type Map
-/// @prop {String} prefix [""] Default prefix, will be added to all custom properties when using mixin or functions, unless overriden, set to empty quotes to disable
+/// @prop {String} prefix [""] Default prefix, will be added to all custom properties when using mixin or functions, unless overridden, set to empty quotes to disable
 
 $config: (
   "prefix" : ""
@@ -19,7 +21,7 @@ $config: (
 
 /// Change modules $config
 /// @example scss Setting the prefix to 'ulu'
-///   @include cssvar.set(( "prefix" : "ulu" ));
+///   @include ulu.cssvar-set(( "prefix" : "ulu" ));
 /// @param {Map} $changes Map of changes
 
 @mixin set($changes) {
@@ -28,7 +30,7 @@ $config: (
 
 /// Get a config option
 /// @example scss Getting the config value for prefix
-///   $prefix: cssvar.get("prefix");
+///   $prefix: ulu.cssvar-get("prefix");
 /// @param {String} $name Name of property
 /// @return {*} Map property value
 
@@ -38,7 +40,7 @@ $config: (
 
 /// Get a custom property name (with optional prefix)
 /// @example scss Getting a custom property name
-///   #{ cssvar.name("base-color") } { ... }
+///   #{ ulu.cssvar-name("base-color") } { ... }
 /// @param {String} $name Name of custom property 
 /// @param {String} $prefix [$config.prefix] Override default prefix
 /// @return {String} The formatted property name (unquoted string)
@@ -51,23 +53,28 @@ $config: (
   }
 }
 
-/// Function to use a custom property within a declartion value 
+/// Function to use a custom property within a declaration value 
 /// @example scss Print an custom property as a value
 ///   .test {
-///     color: cssvar.use("base-color");
+///     color: ulu.cssvar-use("base-color");
 ///   }
 /// @param {String} $name Name of custom property 
+/// @param {String} $default-value [null] Provide a default value for var()
 /// @param {String} $prefix [$config.prefix] Override default prefix
-/// @return {String} Formatted custom propety for use in property value (ie. var(...))
+/// @return {String} Formatted custom property for use in property value (ie. var(...))
 
-@function use($name, $prefix: get("prefix")) {
-  @return var(name($name, $prefix));
+@function use($name, $default-value: null, $prefix: get("prefix")) {
+  @if ($default-value) {
+    @return var(name($name, $prefix), $default-value);
+  } @else {
+    @return var(name($name, $prefix));
+  }
 }
 
 /// Outputs a single custom property declaration
 /// @example scss Declare a custom property
 ///   :root {
-///     @include cssvar.declare("base-color", red);
+///     @include ulu.cssvar-declare("base-color", red);
 ///   }
 /// @param {String} $name Name of property
 /// @param {*} $value The properties value to declare
@@ -80,7 +87,7 @@ $config: (
 /// Outputs a map as custom properties
 /// @example scss Declare each property in a map as a custom property
 ///   :root {
-///     @include cssvar.declare($colors);
+///     @include ulu.cssvar-declare($colors);
 ///   }
 /// @param {Map} $props Properties to declare
 /// @param {String} $prefix [$config.prefix] Override default prefix
@@ -94,7 +101,7 @@ $config: (
 /// Declare a custom property for current breakpoint
 /// @example scss Declare each property in a map as a custom property
 ///   :root {
-///     @include cssvar.declare-breakpoint();
+///     @include ulu.cssvar-declare-breakpoint();
 ///   }
 /// @param {Map} $breakpoints [breakpoint.get-sizes()] Breakpoints to declare
 /// @param {String} $name ["breakpoint"] Name to use for custom property
@@ -113,4 +120,88 @@ $config: (
       @include declare($name, $size, $prefix);
     }
   }
+}
+
+/// Declare a custom property for each breakpoint size
+/// @example scss Declare each property in a map as a custom property
+///   :root {
+///     @include ulu.cssvar-declare-breakpoint-sizes();
+///   }
+/// @param {Map} $breakpoints [breakpoint.get-sizes()] Breakpoints to declare
+/// @param {String} $name ["breakpoint-size-"] Name to use for custom property (prefixes size name)
+/// @param {String} $prefix [$config.prefix] Override default prefix
+
+@mixin declare-breakpoint-sizes(
+  $breakpoints: breakpoint.get-sizes(), 
+  $name: "breakpoint",
+  $prefix: get("prefix"),
+) {
+  @each $size, $value in $breakpoints {
+    $min: breakpoint.get-size-value($size);
+    $max: breakpoint.get-size-value($size, true);
+    @include declare("#{ $name }-#{ $size }-min", $min, $prefix);
+    @include declare("#{ $name }-#{ $size }-max", $max, $prefix);
+  }
+}
+
+/// Outputs css vars for a specific type from a theme map
+/// @param {Map} $theme The map containing the values. Example (
+/// @param {String} $key The key used to retrieve values from the map.
+/// @param {String} $prefix The optional prefix for CSS variables.
+/// @example scss - Example of theme map and usage
+///   // Defining a map to hold my color theme values
+///   $color-themes: (
+///     "color-button" : (
+///       "light" : blue,
+///       "dark" : red
+///     ), ...
+///   );
+/// 
+///   // Declaring default theme
+///   :root {
+///     @include ulu.cssvar-declare-theme-values($color-themes, "light");
+///   }
+///   
+///   // Creating class to use on body/other elements to switch to dark theme
+///   .theme-dark {
+///     @include ulu.cssvar-declare-theme-values($color-themes, "dark");
+///   }
+
+@mixin declare-theme-values($theme, $key, $prefix: get("prefix")) {
+  @each $name, $definition in $theme {
+    $value: map.get($definition, $key);
+    @if ($value) {
+      @include declare($name, $value, $prefix);
+    }
+  }
+}
+
+/// Joins a list of cssvar names
+/// - Use to "+", "-" and then use in calc
+/// @param {List} $names list of names (string), like if using use
+/// @param {String} $separator Separator to use when joining custom property var statements
+/// @return {String} For example if separator was "+" would result in "var(--some-prop) + var(--another-prop)"
+
+@function join($names, $separator) {
+  $values: ();
+  @each $name in $names {
+    $values: append($values, use($name));
+  }
+  @return utils.list-join($values, $separator);
+}
+
+/// For any names passed will join them with "+" and wrap in calc
+/// @param {String} $name Name string (pass multiple comma separated)
+/// @return {String} A string like "calc(var(--some-prop) + var(--another-prop))"
+
+@function add($names...) {
+  @return calc(join($names, "+"));
+}
+
+/// For any names passed will join them with "-" and wrap in calc
+/// @param {String} $name Name string (pass multiple comma separated)
+/// @return {String} A string like "calc(var(--some-prop) - var(--another-prop))"
+
+@function subtract($names...) {
+  @return calc(join($names, "-"));
 }