igniteui-theming 1.0.0-beta.5 → 1.0.0-beta.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "igniteui-theming",
-  "version": "1.0.0-beta.5",
+  "version": "1.0.0-beta.8",
   "description": "A set of Sass variables, mixins, and functions for generating palettes, typography, and elevations used by Ignite UI components.",
   "main": "index.js",
   "scripts": {

package/sass/color/_functions.scss

@@ -13,7 +13,7 @@ $_enhanced-accessibility: false;
 
 /// Configures the color module.
 /// @access public
-/// @param {Boolean} $enhanced-accessibility - Enables features like color blind palettes.
+/// @param {Boolean} $enhanced-accessibility [null] - Enables features like color blind palettes.
 @mixin configure($enhanced-accessibility: null) {
     @if $enhanced-accessibility {
         $_enhanced-accessibility: $enhanced-accessibility !global;
@@ -23,7 +23,6 @@ $_enhanced-accessibility: false;
 /// Generates a color palette.
 /// @access public
 /// @group Palettes
-/// @requires {function} _color-palette
 /// @param {Color} $primary - The primary color used to generate the primary color palette (required).
 /// @param {Color} $secondary - The secondary color used to generate the secondary color palette (required).
 /// @param {Color} $surface - The color used as a background in components, such as cards, sheets, and menus (required).
@@ -33,7 +32,8 @@ $_enhanced-accessibility: false;
 /// @param {Color} $warn [null] - The warning color used throughout the application (optional).
 /// @param {Color} $error [null] - The error color used throughout the application (optional).
 /// @param {String} $variant [null] - Used internally (optional).
-/// @returns {Map} - A map consisting of color shades for the passed base colors(primary, secondary, gray, etc).
+/// @requires {function} shades
+/// @returns {Map} - A map consisting of color shades for the passed base colors (primary, secondary, gray, etc).
 @function palette(
     $primary,
     $secondary,
@@ -47,26 +47,26 @@ $_enhanced-accessibility: false;
 ) {
     $color-shades: map.keys(types.$IColorShades);
     $gray-shades: map.keys(types.$IGrayShades);
-    $primary-palette: shades(primary, $primary, $color-shades);
-    $secondary-palette: shades(secondary, $secondary, $color-shades);
-    $surface-palette: shades(surface, $surface, $color-shades);
-    $grayscale-palette: shades(gray, $gray, $gray-shades, $surface);
-    $info-palette: if($info, shades(info, $info, $color-shades), ());
-    $success-palette: if($success, shades(success, $success, $color-shades), ());
-    $warn-palette: if($warn, shades(warn, $warn, $color-shades), ());
-    $error-palette: if($success, shades(error, $error, $color-shades), ());
+    $primary-palette: shades('primary', $primary, $color-shades);
+    $secondary-palette: shades('secondary', $secondary, $color-shades);
+    $surface-palette: shades('surface', $surface, $color-shades);
+    $grayscale-palette: shades('gray', $gray, $gray-shades, $surface);
+    $info-palette: if($info, shades('info', $info, $color-shades), ());
+    $success-palette: if($success, shades('success', $success, $color-shades), ());
+    $warn-palette: if($warn, shades('warn', $warn, $color-shades), ());
+    $error-palette: if($success, shades('error', $error, $color-shades), ());
 
     @return (
-        primary: $primary-palette,
-        secondary: $secondary-palette,
-        gray: $grayscale-palette,
-        surface: $surface-palette,
-        info: $info-palette,
-        success: $success-palette,
-        warn: $warn-palette,
-        error: $error-palette,
-        _meta: (
-            variant: $variant,
+        'primary': $primary-palette,
+        'secondary': $secondary-palette,
+        'gray': $grayscale-palette,
+        'surface': $surface-palette,
+        'info': $info-palette,
+        'success': $success-palette,
+        'warn': $warn-palette,
+        'error': $error-palette,
+        '_meta': (
+            'variant': $variant,
         )
     );
 }
@@ -78,10 +78,8 @@ $_enhanced-accessibility: false;
 /// @param {Color} $color - The base color used to generate the palette.
 /// @param {List} $shades - The list of shades.
 /// @param {Color} $surface [null] - The surface color. Usefull when generating shades of gray (optional).
-/// @requires {function} _color-shade
-/// @requires {function} _hsla-shade
-/// @requires {function} contrast
-/// @requires {function} to-opaque
+/// @requires {function} shade
+/// @requires {function} text-contrast
 /// @returns {Map} - A map consisting of hsla color shades and thier respective contrast colors.
 @function shades(
     $name,
@@ -113,6 +111,8 @@ $_enhanced-accessibility: false;
 /// @param {Color} $color - The color value to be used to generate a color shade.
 /// @param {String | Number} $shade - The color shade variant.
 /// @param {Color} $surface [null] - The surface color. Usefull when generating a shade of gray (optional).
+/// @require {function} luminance
+/// @require {function} to-fixed
 /// @returns {Map} - A map containing a list of HSL values and a raw color value.
 @function shade(
     $name,
@@ -124,7 +124,7 @@ $_enhanced-accessibility: false;
     $s: var(--ig-#{$name}-s);
     $l: var(--ig-#{$name}-l);
 
-    @if $name == gray {
+    @if #{$name} == 'gray' {
         $lum: luminance($surface);
         $color: if($color, $color, if($lum > .5, #000, #fff));
         $lmap: map.get(multipliers.$grayscale, 'l');
@@ -158,13 +158,13 @@ $_enhanced-accessibility: false;
 /// Retrieves a color from a color palette.
 /// @access public
 /// @group Palettes
-/// @param {Map} $palette [null]- The source palette map (optional).
-/// @param {String} $color [primary]- The target color from the color palette.
+/// @param {Map} $palette [null] - The source palette map (optional).
+/// @param {String} $color [primary] - The target color from the color palette.
 /// @param {Number | String} $variant [500] - The target color shade from the color palette.
 /// @param {Number} $opacity [null] - Optional opacity to apply to the color shade.
 /// @returns {Color | String} - The raw color shade or CSS variable reference from the palette.
-@function color($palette: null, $color: primary, $variant: 500, $opacity: null) {
-    $c: map.get($palette or types.$IPalette, $color);
+@function color($palette: null, $color: 'primary', $variant: 500, $opacity: null) {
+    $c: map.get($palette or types.$IPalette, #{$color});
     $a: var(--ig-#{$color}-a);
     $s: #{var(--ig-#{$color}-#{$variant})};
     $contrast: if(
@@ -191,11 +191,11 @@ $_enhanced-accessibility: false;
 
 /// Retrieves a contrast text color for a given color from a color palette.
 /// @access public
-/// @group Palettesreference
-/// @param {Map} $palette [null]- The source palette map (optional).
-/// @param {String} $color [primary]- The target color from the color palette.
+/// @group Palettes
+/// @param {Map} $palette [null] - The source palette map (optional).
+/// @param {String} $color [primary] - The target color from the color palette.
 /// @param {Number | String} $variant [500] - The target color shade from the color palette.
-/// @requires color
+/// @requires {function} color
 /// @returns {Color | String} - The raw contrast color shade or CSS variable from the palette.
 @function contrast-color($palette: null, $color: primary, $variant: 500) {
     @return color($palette, $color, #{$variant}-contrast);
@@ -208,6 +208,7 @@ $_enhanced-accessibility: false;
 /// @param {Color | List<Color>} $foreground [#fff] - A list of foreground colors
 /// that can be used with the provided background.
 /// @param {AAA | AA | A} $contrast [AAA] - The contrast level according to WCAG 2.0 standards.
+/// @require {function} contrast
 /// @returns {Color} - Returns either white, black, or the provided foreground
 /// color if it meets the required contrast level.
 /// @link https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-contrast.html
@@ -261,6 +262,7 @@ $_enhanced-accessibility: false;
 
 /// Mixes two colors to produce an opaque color.
 /// @access public
+/// @group Color
 /// @param {Color} $color-1 - The first color, usually transparent.
 /// @param {Color} $color-2 [#fff] - The second color, usually opaque.
 /// @return {Color} - The color representation of the rgba value.
@@ -282,6 +284,7 @@ $_enhanced-accessibility: false;
 
 /// Retruns a comma separated list of hue, saturation, and lightness values for a given color.
 /// @access public
+/// @group Color
 /// @param {Color} $color - The color to be converted to an HSL list of values.
 /// @example scss Turn #000 into an HSL list of values
 ///   $hsl-list: to-hsl(#000); // (0deg, 0%, 0%);
@@ -292,9 +295,12 @@ $_enhanced-accessibility: false;
 
 /// Calculates the contrast ratio between two colors.
 /// See https://www.w3.org/TR/WCAG20-TECHS/G17.html#G17-tests
-///
+/// @access public
+/// @group Color
 /// @param {Color} $background - The background color.
 /// @param {Color} $foreground - The foreground color.
+/// @require {function} luminance
+/// @require {function} to-fixed
 /// @returns {Number} - The contrast ratio between the background and foreground colors.
 @function contrast($background, $foreground) {
     $backLum: luminance($background) + .05;
@@ -305,8 +311,10 @@ $_enhanced-accessibility: false;
 
 /// Calculates the luminance for a given color.
 /// See https://www.w3.org/TR/WCAG20-TECHS/G17.html#G17-tests.
-///
+/// @access public
+/// @group Color
 /// @param {Color} $color - The color to calculate luminance for.
+/// @returns {Number | String} - The calculated luminance of a given color
 @function luminance($color) {
     @if meta.type-of($color) == 'color' {
         $r: math.div(color.red($color), 255);
@@ -321,6 +329,9 @@ $_enhanced-accessibility: false;
 
 /// Calculates the linear channel value for a given sRGB color.
 /// @access private
+/// @group Color
+/// @param {Number} $value - The sRGB color
+/// @returns {Number} - The calculated linear channel value
 @function _lcv($value) {
     /* stylelint-disable number-max-precision */
     @return if(
@@ -337,12 +348,3 @@ $_enhanced-accessibility: false;
 @function chart-brushes() {
     @return if($_enhanced-accessibility, charts.$brushes-color-blind, charts.$brushes-regular);
 }
-
-/// Returns a list of H, S, L values for a given color.
-/// @access public
-/// @param {Color} $color - The color to generate HSL values for.
-/// @group Palettes
-/// @returns { List } - The list of values.
-@function to-hsl($color) {
-    @return (color.hue($color), color.saturation($color), color.lightness($color));
-}

package/sass/color/_mixins.scss

@@ -8,12 +8,12 @@
 /// Generates CSS variables for a given palette.
 /// @access public
 /// @group Palettes
-/// @param {Map} $palette [null] - The palette used to generate CSS variables.
+/// @param {Map} $palette - The palette used to generate CSS variables.
 /// @param {Boolean} $contrast [true] - Specify if contrast colors should be included.
 /// @example scss Generate css variables for a palette
 ///    $palette: palette($primary: red, $secondary: blue, $gray: #000);
 ///    @include palette($palette);
-///
+/// @require {function} is-root
 @mixin palette($palette, $contrast: true) {
     $scope: if(is-root(), ':root', '&');
 
@@ -27,20 +27,20 @@
                 $_contrast: if($_other-shade, string.index($shade, 'contrast'), false);
 
                 @if $_base-shade and $_valid-color {
-                    --ig-#{meta.inspect($color)}-h: #{math.round(color.hue($value))};
-                    --ig-#{meta.inspect($color)}-s: #{math.round(color.saturation($value))};
-                    --ig-#{meta.inspect($color)}-l: #{math.round(color.lightness($value))};
-                    --ig-#{meta.inspect($color)}-a: #{color.alpha($value)};
+                    --ig-#{$color}-h: #{math.round(color.hue($value))};
+                    --ig-#{$color}-s: #{math.round(color.saturation($value))};
+                    --ig-#{$color}-l: #{math.round(color.lightness($value))};
+                    --ig-#{$color}-a: #{color.alpha($value)};
                 }
 
                 @if $_hsl {
                     $variant: string.slice($shade, 1, string.index($shade, '-hsl') - 1);
 
-                    --ig-#{meta.inspect($color)}-#{$variant}: #{$value};
+                    --ig-#{$color}-#{$variant}: #{$value};
                 }
 
                 @if $_contrast and $contrast {
-                    --ig-#{meta.inspect($color)}-#{$shade}: #{$value};
+                    --ig-#{$color}-#{$shade}: #{$value};
                 }
             }
         }

package/sass/color/_types.scss

@@ -1,5 +1,11 @@
 @use 'sass:map';
 
+////
+/// @group Palettes
+////
+
+/// A list consisting of all generated gray shades
+/// @type Map
 $IGrayShades: (
     50: '',
     100: '',
@@ -12,6 +18,9 @@ $IGrayShades: (
     800: '',
     900: '',
 );
+
+/// A list consisting of all generated shades for palette colors
+/// @type Map
 $IColorShades: map.merge(
     $IGrayShades,
     (
@@ -21,17 +30,26 @@ $IColorShades: map.merge(
         'A700': '',
     )
 );
+
+/// All palette colors mapped with corresponding color shades
+/// @type Map
 $IPaletteColors: (
-    primary: $IColorShades,
-    secondary: $IColorShades,
-    gray: $IGrayShades,
-    surface: $IColorShades,
-    info: $IColorShades,
-    success: $IColorShades,
-    warn: $IColorShades,
-    error: $IColorShades,
+    'primary': $IColorShades,
+    'secondary': $IColorShades,
+    'gray': $IGrayShades,
+    'surface': $IColorShades,
+    'info': $IColorShades,
+    'success': $IColorShades,
+    'warn': $IColorShades,
+    'error': $IColorShades,
 );
+
+/// A list consisting of palette metadata
+/// @type Map
 $IPaletteMeta: (
-    variant: '',
+    'variant': '',
 );
+
+/// A map with all palette colors and palette meta
+/// @type Map
 $IPalette: map.merge($IPaletteColors, (_meta: $IPaletteMeta));

package/sass/color/presets/dark/_material.scss

@@ -4,5 +4,9 @@ $palette: palette(
     $primary: #09f,
     $secondary: #e41c77,
     $surface: #222,
+    $info: #1377d5,
+    $success: #4eb862,
+    $warn: #fbb13c,
+    $error: #ff134a,
     $variant: 'material'
 );

package/sass/color/presets/light/_material.scss

@@ -4,5 +4,9 @@ $palette: palette(
     $primary: #09f,
     $secondary: #e41c77,
     $surface: white,
+    $info: #1377d5,
+    $success: #4eb862,
+    $warn: #fbb13c,
+    $error: #ff134a,
     $variant: 'material'
 );

package/sass/elevations/_functions.scss

@@ -3,7 +3,7 @@
 @use 'sass:list';
 
 ////
-/// @group elevations
+/// @group Elevations
 ////
 
 $factor: var(--ig-elevation-factor, 1);
@@ -82,6 +82,7 @@ $factor: var(--ig-elevation-factor, 1);
 /// Gets a CSS elevation variable by name.
 /// @access public
 /// @param {String} $name - The name of the shadow.
+/// @return {String} - The CSS elevation variable
 @function elevation($name) {
     @return var(--ig-elevation-#{$name});
 }

package/sass/elevations/_mixins.scss

@@ -1,7 +1,7 @@
 @use '../utils/meta' as *;
 
 ////
-/// @group elevations
+/// @group Elevations
 ////
 
 /// Generates CSS variables for a given elevations map.
@@ -9,13 +9,13 @@
 /// @param {Map} $elevations - The elevations map to use to generate CSS variables.
 ///
 /// @example scss Generate CSS variables for elevations.
-/// $elevations: (
-///     small: box-shadow(0 .125rem .25rem rgba(0 0 0 / 75%)),
-///     medium: box-shadow(0 .25rem .5rem rgba(0 0 0 / 85%)),
-///     large: box-shadow(0 .75rem 1rem rgba(0 0 0 / 95%)),
-/// );
-/// @include elevations($elevations);
-///
+///   $elevations: (
+///       small: box-shadow(0 .125rem .25rem rgba(0 0 0 / 75%)),
+///       medium: box-shadow(0 .25rem .5rem rgba(0 0 0 / 85%)),
+///       large: box-shadow(0 .75rem 1rem rgba(0 0 0 / 95%))
+///   );
+///   @include elevations($elevations);
+/// @require {function} is-root
 @mixin elevations($elevations) {
     $scope: if(is-root(), ':root', '&');
 

package/sass/elevations/presets/_material.scss

@@ -5,16 +5,16 @@
 /// @author <a href="https://github.com/simeonoff" target="_blank">Simeon Simeonoff</a>
 ////
 
-/// Level 1 - Umbra Shadows
-/// @type {Color} $_color-1 - The color used to generate umbra shadows.
+/// Level 1 - The color used to generate umbra shadows.
+/// @type Color
 $_color-1: rgba(0 0 0 / 26%);
 
-/// Level 2 - Penumbra Shadows
-/// @type {Color} $_color-2 - The color used to generate penumbra shadows.
+/// Level 2 - The color used to generate penumbra shadows.
+/// @type Color
 $_color-2: rgba(0 0 0 / 12%);
 
-/// Level 3 - Ambient Shadows
-/// @type {Color} $_color-3 - The color used to generate ambient shadows.
+/// Level 3 - The color used to generate ambient shadows.
+/// @type Color
 $_color-3: rgba(0 0 0 / 8%);
 
 /// Allows user configration of this module.
@@ -32,7 +32,8 @@ $_color-3: rgba(0 0 0 / 8%);
     }
 }
 
-/// @type {Map} $elevations - А map of 24 shadow elevations with the umbra, penumbra and ambient shadows.
+/// А map of 24 shadow elevations with the umbra, penumbra and ambient shadows.
+/// @type Map
 $elevations: (
     0: none,
     1: box-shadow((0 1px 3px 0 $_color-1, 0 1px 1px 0 $_color-2, 0 2px 1px -1px $_color-3)),

package/sass/themes/_functions.scss

@@ -9,6 +9,8 @@
 /// @access private
 /// @param {Map} $schema - A theme schema.
 /// @requires {function} resolve-value
+/// @requires {function} elevation
+/// @requires {function} chart-brushes
 /// @example scss Get the resolved theme for a schema
 ///   $custom-schema: (
 ///     foreground: (
@@ -82,8 +84,9 @@
 
 /// Retrieves the CSS custom property reference for the given key in the component theme.
 /// @access public
-/// @param {map} $theme - The source theme to be used to read values from.
-/// @param {string} $property - A key from the theme map to assign as value to the property.
+/// @param {Map} $theme - The source theme to be used to read values from.
+/// @param {String} $property - A key from the theme map to assign as value to the property.
+/// @param {String} $fallback [null] - A value to be used if the CSS property is not defined.
 /// @example scss Assign the color property in a set of rules to a value from the theme.
 ///   [part='icon'] {
 ///     color: var-get($theme, 'icon-color', inherit); // var(--icon-color, inherit)
@@ -104,6 +107,21 @@
 /// @param {Number} $radius - The preferred value.
 /// @param {Number} $min [rem(0)] - The minimum value.
 /// @param {Number} $max [$radius] - The maximum allowed value.
+/// @return {Number} - The clamped value
 @function border-radius($radius, $min: #{rem(0)}, $max: $radius) {
     @return clamp(#{$min}, #{calc(var(--ig-radius-factor) * #{$radius})}, #{$max});
 }
+
+/// Used to switch between values based on the size of the component.
+/// @access public
+/// @param {Number} $sm - The preferred value when the component's size is small.
+/// @param {Number} $md [$sm] - The preferred value when the component's size is medium.
+/// @param {Number} $lg [$md] - The preferred value when the component's size is large.
+/// @return {Function} - The evaluated value.
+@function sizable($sm, $md: $sm, $lg: $md) {
+    @return max(
+        calc(var(--is-large, 1) * #{$lg}),
+        calc(var(--is-medium, 1) * #{$md}),
+        calc(var(--is-small, 1) * #{$sm})
+    );
+}

package/sass/themes/_mixins.scss

@@ -10,12 +10,15 @@ $ignored-keys: ('name', 'palette', 'variant', 'selector');
 
 /// Parses a map of key value pairs from component themes to css variables.
 /// @access private
-/// @param {map} $theme - The component theme to be used to generate css variables.
+/// @param {Map} $theme - The component theme to be used to generate css variables.
+/// @param {String} $name - The CSS variables name
+/// @param {Map} $ignored [$ignored-keys] - A list of ignored keywords to be excluded when generating CSS variables
 /// @example scss Convert theme colors to CSS variables.
 ///   $theme: digest-schema((background: color(primary, 500), foreground: contrast-color(color, 500));
 ///   :root {
 ///     @include css-vars-from-theme($theme);
 ///   }
+/// @require {mixin} css-vars
 @mixin css-vars-from-theme($theme, $name, $ignored: $ignored-keys) {
     $themes: map.get($theme, 'themes');
 
@@ -69,6 +72,7 @@ $ignored-keys: ('name', 'palette', 'variant', 'selector');
 }
 
 /// Truncates text to a specific number of lines.
+/// @access public
 /// @param {number|string} $lines - The number of lines to show
 /// @param {Boolean} $inline - Sets whether an element displays inline-box or box
 /// @param {Boolean} $vertical - Sets whether an element lays out its contents horizontally or vertically
@@ -108,3 +112,15 @@ $ignored-keys: ('name', 'palette', 'variant', 'selector');
     overflow: hidden;
     appearance: none;
 }
+
+/// Adds the required CSS properties so that the scope can react to size changes.
+/// @access public
+@mixin sizable() {
+    --is-large: clamp(0, (var(--ig-size, 1) + 1) - var(--ig-size-large, 3), 1);
+    --is-medium:
+        min(
+            clamp(0, (var(--ig-size, 1) + 1) - var(--ig-size-medium, 2), 1),
+            clamp(0, var(--ig-size-large, 3) - var(--ig-size, 1), 1)
+        );
+    --is-small: clamp(0, var(--ig-size-medium) - var(--ig-size, 1), 1);
+}

package/sass/typography/_functions.scss

@@ -15,6 +15,7 @@ $browser-context: 16px;
 /// @access public
 /// @param {number|string} $pixels - The pixel value to be converted.
 /// @param {number|string} $context [$browser-context] - The base context to convert against.
+/// @return {number} - Returns the pixels value converted to em.
 @function em($pixels, $context: $browser-context) {
     @if math.is-unitless($pixels) {
         $pixels: $pixels * 1px;
@@ -27,10 +28,11 @@ $browser-context: 16px;
     @return math.div($pixels, $context) * 1em;
 }
 
-/// Pixels to root relative values (rem).
+/// Converts pixels to root relative values (rem).
 /// @access public
 /// @param {number|string} $pixels - The pixel value to be converted.
 /// @param {number|string} $context [$browser-context] - The base context to convert against.
+/// @return {number} - Returns the pixels value converted to rem.
 @function rem($pixels, $context: $browser-context) {
     @if math.is-unitless($pixels) {
         $pixels: $pixels * 1px;
@@ -43,10 +45,11 @@ $browser-context: 16px;
     @return math.div($pixels, $context) * 1rem;
 }
 
-/// Relative value(em/rem) to pixel.
+/// Converts relative value (em/rem) to pixel.
 /// @access public
 /// @param {number|string} $num - The relative value to be converted.
 /// @param {number|string} $context [$browser-context] - The base context to convert against.
+/// @return {number} - Returns the relative value converted to pixels.
 @function px($num, $context: $browser-context) {
     @if meta.type-of($num) == 'number' {
         @return math.div($num, $num * 0 + 1) * 16px;
@@ -107,7 +110,6 @@ $browser-context: 16px;
 /// @param {Map} $caption - A map containing type style properties as produces by the type-style function.
 /// @param {Map} $overline - A map containing type style properties as produces by the type-style function.
 /// @param {String} $_theme [null] - The theme related to this type scale. Internal use only.
-/// @requires type-style
 /// @requires $ITypeScale
 /// @returns {Map} - A map of all defined type scales.
 @function type-scale($_theme: null, $args...) {

package/sass/typography/_mixins.scss

@@ -10,13 +10,15 @@
 
 /// Includes all category related styles into the current style block.
 /// @param {String} $category - The type scale category.
+/// @param {String} $check [true] - Toggles category checks against ITypeScale.
+/// Set to false when using a custom type scale.
 /// @example scss Add the `h1` styles to custom CSS selector.
 ///   .fancy-h1 {
 ///      @include type-style('h1');
 ///      color: mediumvioletred;
 ///   }
-@mixin type-style($category) {
-    $valid: list.index(types.$ITypeScale, $category);
+@mixin type-style($category, $check: true) {
+    $valid: if($check, list.index(types.$ITypeScale, $category), true);
 
     @if $valid {
         @each $key, $value in types.$ITypeStyle {
@@ -30,8 +32,7 @@
 
 /// Transforms a type style map into css font variables.
 /// @param {String} $name - The custom CSS variable name.
-/// @param {Map} $type-style - A type style map reference as produces by type-style.
-/// @param {String} $prefix [null] - Optional prefix.
+/// @param {Map} $type-style - A type style map reference as produced by type-style.
 /// @example scss Assign the `h1` styles to custom CSS property using the CSS font shorthand syntax.
 ///   $h1-style: type-scale-category($type-scale, 'h1');
 ///   @include type-style-vars('h1', $h1-style);
@@ -42,7 +43,7 @@
 }
 
 /// Styles all native elements that match the IElementCategories map.
-/// @requires type-style
+/// @requires {mixin} type-style
 /// @requires $ITypeScale
 /// @requires $IElementCategories
 @mixin type-style-elements() {
@@ -61,7 +62,7 @@
 }
 
 /// Creates CSS classes with style rules for all categories in the ITypeScale map.
-/// @requires type-style
+/// @requires {mixin} type-style
 /// @requires $ITypeScale
 @mixin type-style-classes() {
     @each $category in types.$ITypeScale {
@@ -77,9 +78,10 @@
 /// @access public
 /// @param {String} $font-family - The font family to be used across all typographic elements.
 /// @param {Map} $type-scale - A type scale map as produced by the type-scale function.
-/// @requires type-style-vars
-/// @requires type-style-classes
-/// @requires type-style-elements
+/// @requires {function} is-root
+/// @requires {mixin} type-style-vars
+/// @requires {mixin} type-style-classes
+/// @requires {mixin} type-style-elements
 @mixin typography($font-family, $type-scale) {
     $scope: if(is-root(), ':root', '&');
 

package/sass/typography/_types.scss

@@ -1,3 +1,9 @@
+////
+/// @group Typography
+////
+
+/// A list consisting of 13 different category type styles
+/// @type List
 $ITypeScale: (
     h1,
     h2,
@@ -13,6 +19,9 @@ $ITypeScale: (
     caption,
     overline
 );
+
+/// A set of style rules for all categories
+/// @type Map
 $ITypeStyle: (
     font-family: var(--ig-font-family),
     font-size: null,
@@ -24,6 +33,9 @@ $ITypeStyle: (
     margin-top: 0,
     margin-bottom: 0
 );
+
+/// A list of all category type styles that can be maped to native elements
+/// @type Map
 $IElementCategories: (
     h1: 'h1',
     h2: 'h2',

package/sass/typography/presets/_bootstrap.scss

@@ -11,6 +11,7 @@ $_base-scale: (
     h1: type-style(
         $font-size: rem(40px),
         $font-weight: 500,
+        $letter-spacing: rem(-1.5px),
         $line-height: rem(48px),
         $text-transform: none,
         $margin-top: 0,
@@ -19,6 +20,7 @@ $_base-scale: (
     h2: type-style(
         $font-size: rem(32px),
         $font-weight: 500,
+        $letter-spacing: rem(-.5px),
         $line-height: rem(38.4px),
         $text-transform: none,
         $margin-top: 0,
@@ -27,6 +29,7 @@ $_base-scale: (
     h3: type-style(
         $font-size: rem(28px),
         $font-weight: 500,
+        $letter-spacing: 0,
         $line-height: rem(33.6px),
         $text-transform: none,
         $margin-top: 0,
@@ -35,6 +38,7 @@ $_base-scale: (
     h4: type-style(
         $font-size: rem(24px),
         $font-weight: 500,
+        $letter-spacing: rem(.25px),
         $line-height: rem(28.8px),
         $text-transform: none,
         $margin-top: 0,
@@ -43,6 +47,7 @@ $_base-scale: (
     h5: type-style(
         $font-size: rem(20px),
         $font-weight: 500,
+        $letter-spacing: 0,
         $line-height: rem(24px),
         $text-transform: none,
         $margin-top: 0,
@@ -51,6 +56,7 @@ $_base-scale: (
     h6: type-style(
         $font-size: rem(16px),
         $font-weight: 500,
+        $letter-spacing: rem(.15px),
         $line-height: rem(19.2px),
         $text-transform: none,
         $margin-top: 0,
@@ -59,6 +65,7 @@ $_base-scale: (
     body-1: type-style(
         $font-size: rem(16px),
         $font-weight: 400,
+        $letter-spacing: rem(.5px),
         $line-height: rem(24px),
         $text-transform: none,
         $margin-top: 0,
@@ -67,6 +74,7 @@ $_base-scale: (
     body-2: type-style(
         $font-size: rem(14.4px),
         $font-weight: 400,
+        $letter-spacing: rem(.25px),
         $line-height: rem(24px),
         $text-transform: none,
         $margin-top: 0,
@@ -75,6 +83,7 @@ $_base-scale: (
     subtitle-1: type-style(
         $font-size: rem(14px),
         $font-weight: 400,
+        $letter-spacing: rem(.15px),
         $line-height: rem(24px),
         $text-transform: none,
         $margin-top: 0,
@@ -83,6 +92,7 @@ $_base-scale: (
     subtitle-2: type-style(
         $font-size: rem(14.4px),
         $font-weight: 400,
+        $letter-spacing: rem(.1px),
         $line-height: rem(21.6px),
         $text-transform: none,
         $margin-top: 0,
@@ -91,6 +101,7 @@ $_base-scale: (
     button: type-style(
         $font-size: rem(16px),
         $font-weight: 500,
+        $letter-spacing: rem(.75px),
         $line-height: rem(24px),
         $text-transform: none,
         $margin-top: 0,

package/sass/typography/presets/_fluent.scss

@@ -8,6 +8,7 @@ $type-scale: (
     h1: type-style(
         $font-size: rem(68px),
         $font-weight: 700,
+        $letter-spacing: rem(-1.5px),
         $line-height: rem(76px),
         $text-transform: none,
         $margin-top: 0,
@@ -16,6 +17,7 @@ $type-scale: (
     h2: type-style(
         $font-size: rem(42px),
         $font-weight: 700,
+        $letter-spacing: rem(-.5px),
         $line-height: rem(52px),
         $text-transform: none,
         $margin-top: 0,
@@ -24,6 +26,7 @@ $type-scale: (
     h3: type-style(
         $font-size: rem(32px),
         $font-weight: 600,
+        $letter-spacing: 0,
         $line-height: rem(40px),
         $text-transform: none,
         $margin-top: 0,
@@ -32,6 +35,7 @@ $type-scale: (
     h4: type-style(
         $font-size: rem(28px),
         $font-weight: 400,
+        $letter-spacing: rem(.25px),
         $line-height: rem(36px),
         $text-transform: none,
         $margin-top: 0,
@@ -40,6 +44,7 @@ $type-scale: (
     h5: type-style(
         $font-size: rem(24px),
         $font-weight: 400,
+        $letter-spacing: 0,
         $line-height: rem(32px),
         $text-transform: none,
         $margin-top: 0,
@@ -48,6 +53,7 @@ $type-scale: (
     h6: type-style(
         $font-size: rem(20px),
         $font-weight: 400,
+        $letter-spacing: rem(.15px),
         $line-height: rem(28px),
         $text-transform: none,
         $margin-top: 0,
@@ -56,6 +62,7 @@ $type-scale: (
     body-1: type-style(
         $font-size: rem(16px),
         $font-weight: 400,
+        $letter-spacing: rem(.5px),
         $line-height: rem(22px),
         $text-transform: none,
         $margin-top: 0,
@@ -64,6 +71,7 @@ $type-scale: (
     body-2: type-style(
         $font-size: rem(14px),
         $font-weight: 400,
+        $letter-spacing: rem(.25px),
         $line-height: rem(20px),
         $text-transform: none,
         $margin-top: 0,
@@ -72,6 +80,7 @@ $type-scale: (
     subtitle-1: type-style(
         $font-size: rem(18px),
         $font-weight: 400,
+        $letter-spacing: rem(.15px),
         $line-height: rem(24px),
         $text-transform: none,
         $margin-top: 0,
@@ -80,6 +89,7 @@ $type-scale: (
     subtitle-2: type-style(
         $font-size: rem(14px),
         $font-weight: 600,
+        $letter-spacing: rem(.1px),
         $line-height: rem(20px),
         $text-transform: none,
         $margin-top: 0,
@@ -88,6 +98,7 @@ $type-scale: (
     button: type-style(
         $font-size: rem(14px),
         $font-weight: 400,
+        $letter-spacing: rem(.75px),
         $line-height: rem(14px),
         $text-transform: capitalize,
         $margin-top: 0,
@@ -104,7 +115,9 @@ $type-scale: (
     overline: type-style(
         $font-size: rem(10px),
         $font-weight: 400,
+        $letter-spacing: rem(1.5px),
         $line-height: rem(14px),
+        $text-transform: uppercase,
         $margin-top: 0,
         $margin-bottom: 0
     )

package/sass/typography/presets/_indigo.scss

@@ -8,8 +8,8 @@ $type-scale: (
     h1: type-style(
         $font-size: rem(96px),
         $font-weight: 200,
-        $line-height: rem(112px),
         $letter-spacing: rem(-1.5px),
+        $line-height: rem(112px),
         $text-transform: none,
         $margin-top: 0,
         $margin-bottom: 0
@@ -17,8 +17,8 @@ $type-scale: (
     h2: type-style(
         $font-size: rem(60px),
         $font-weight: 200,
-        $line-height: rem(72px),
         $letter-spacing: rem(-.5px),
+        $line-height: rem(72px),
         $text-transform: none,
         $margin-top: 0,
         $margin-bottom: 0
@@ -26,6 +26,7 @@ $type-scale: (
     h3: type-style(
         $font-size: rem(48px),
         $font-weight: 200,
+        $letter-spacing: 0,
         $line-height: rem(56px),
         $text-transform: none,
         $margin-top: 0,
@@ -34,6 +35,7 @@ $type-scale: (
     h4: type-style(
         $font-size: rem(36px),
         $font-weight: 200,
+        $letter-spacing: rem(.25px),
         $line-height: rem(42px),
         $text-transform: none,
         $margin-top: 0,
@@ -42,6 +44,7 @@ $type-scale: (
     h5: type-style(
         $font-size: rem(24px),
         $font-weight: 200,
+        $letter-spacing: 0,
         $line-height: rem(28px),
         $text-transform: none,
         $margin-top: 0,
@@ -50,6 +53,7 @@ $type-scale: (
     h6: type-style(
         $font-size: rem(20px),
         $font-weight: 600,
+        $letter-spacing: rem(.15px),
         $line-height: rem(26px),
         $text-transform: none,
         $margin-top: 0,
@@ -58,6 +62,7 @@ $type-scale: (
     body-1: type-style(
         $font-size: rem(16px),
         $font-weight: 400,
+        $letter-spacing: rem(.5px),
         $line-height: rem(20px),
         $text-transform: none,
         $margin-top: 0,
@@ -66,6 +71,7 @@ $type-scale: (
     body-2: type-style(
         $font-size: rem(14px),
         $font-weight: 400,
+        $letter-spacing: rem(.25px),
         $line-height: rem(20px),
         $text-transform: none,
         $margin-top: 0,
@@ -74,6 +80,7 @@ $type-scale: (
     subtitle-1: type-style(
         $font-size: rem(16px),
         $font-weight: 600,
+        $letter-spacing: rem(.15px),
         $line-height: rem(22px),
         $text-transform: none,
         $margin-top: 0,
@@ -82,6 +89,7 @@ $type-scale: (
     subtitle-2: type-style(
         $font-size: rem(14px),
         $font-weight: 700,
+        $letter-spacing: rem(.1px),
         $line-height: rem(20px),
         $text-transform: none,
         $margin-top: 0,
@@ -90,6 +98,7 @@ $type-scale: (
     button: type-style(
         $font-size: rem(12px),
         $font-weight: 700,
+        $letter-spacing: rem(.75px),
         $line-height: normal,
         $text-transform: uppercase,
         $margin-top: 0,
@@ -98,6 +107,7 @@ $type-scale: (
     caption: type-style(
         $font-size: rem(12px),
         $font-weight: 400,
+        $letter-spacing: rem(.4px),
         $line-height: rem(16px),
         $text-transform: normal,
         $margin-top: 0,
@@ -106,9 +116,9 @@ $type-scale: (
     overline: type-style(
         $font-size: rem(10px),
         $font-weight: 700,
+        $letter-spacing: rem(.2px),
         $line-height: rem(14px),
         $text-transform: uppercase,
-        $letter-spacing: rem(.2px),
         $margin-top: 0,
         $margin-bottom: 0
     )

package/sass/typography/presets/_material.scss

@@ -66,22 +66,6 @@ $type-scale: (
         $margin-top: 0,
         $margin-bottom: 0
     ),
-    subtitle-1: type-style(
-        $font-size: rem(16px),
-        $font-weight: 400,
-        $font-style: normal,
-        $letter-spacing: rem(.15px),
-        $line-height: rem(24px),
-        $text-transform: none
-    ),
-    subtitle-2: type-style(
-        $font-size: rem(14px),
-        $font-weight: 600,
-        $font-style: normal,
-        $letter-spacing: rem(.1px),
-        $line-height: rem(24px),
-        $text-transform: none
-    ),
     body-1: type-style(
         $font-size: rem(16px),
         $font-weight: 400,
@@ -100,6 +84,22 @@ $type-scale: (
         $line-height: rem(20px),
         $text-transform: none
     ),
+    subtitle-1: type-style(
+        $font-size: rem(16px),
+        $font-weight: 400,
+        $font-style: normal,
+        $letter-spacing: rem(.15px),
+        $line-height: rem(24px),
+        $text-transform: none
+    ),
+    subtitle-2: type-style(
+        $font-size: rem(14px),
+        $font-weight: 600,
+        $font-style: normal,
+        $letter-spacing: rem(.1px),
+        $line-height: rem(24px),
+        $text-transform: none
+    ),
     button: type-style(
         $font-size: rem(14px),
         $font-weight: 600,

package/sass/utils/_map.scss

@@ -24,7 +24,7 @@
 /// Extends a Map with the values of another Map, disregarding null values in the process.
 /// @access public
 /// @param {Map...} $maps - The maps to get extended.
-/// @requires {function} map-clean
+/// @requires {function} clean
 /// @returns {Map} - Returns the merged maps.
 @function extend($maps...) {
     $result: ();

package/sass/utils/_math.scss

@@ -1,5 +1,10 @@
 @use 'sass:math';
 
+/// Rounds a number to a certain precision
+/// @access public
+/// @param {Number} $number - The number to be rounded
+/// @param {Number} $precision [2] - Specifies the number of the digits after the decimal separator
+/// @returns {Number} - The rounded number
 @function to-fixed($number, $precision: 2) {
     $pow: math.pow(10, $precision);
 

package/sass/utils/_meta.scss

@@ -8,7 +8,7 @@
 ///       /* style rules here */
 ///     }
 ///   }
-///
+/// @return {Boolean} - Returns a boolean depending on the scope where it's called
 @function is-root() {
     @each $selector in & {
         @return if($selector == null, true, false);

package/test/_typography.spec.scss

@@ -8,6 +8,7 @@
 @use 'sass:string';
 @use '../node_modules/sass-true/' as *;
 @use '../sass/typography/' as *;
+@use '../sass/typography/presets' as presets;
 
 $h1: (font-size: 96px);
 $h2: (font-size: 70px);
@@ -157,6 +158,22 @@ $scale: type-scale(
             }
         }
 
+        @include it('should include all styles from a custom type category') {
+            @include assert() {
+                $custom-category: 'calendar-labels';
+
+                @include output() {
+                    @include type-style($custom-category, $check: false);
+                }
+
+                @include expect() {
+                    @each $key, $value in map.get(presets.$bootstrap-type-scale, $custom-category) {
+                        #{$key}: var(--ig-#{$custom-category}-#{$key});
+                    }
+                }
+            }
+        }
+
         @include it('should include type styles with CSS var refs as values for a specific category') {
             $category: 'h1';
 

package/test/e2e/theme.scss

@@ -1,4 +1,7 @@
 @use '../../index' as *;
+@use '../../sass/color/presets' as *;
+@use '../../sass/typography/presets' as *;
+@use '../../sass/elevations/presets' as *;
 @include palette($light-material-palette);
 @include typography($material-typeface, $material-type-scale);
 @include elevations($material-elevations);