Typography
Installation
yarn add @chewy/kib-foundations
Import
@use '~@chewy/kib-foundations/src/typography';
Functions
get
@function get($path) { ... }
@function get($path) { @return -get-type-style-property($path...); }
Description
Get a single type style property definition.
Parameters
parameter Name | parameter Description | parameter Type | parameter Default value |
---|---|---|---|
$path | The map path to the desired property definition. | List | — none |
Returns
List
or String
or Number
—Return the value of the type style property.
Requires
- [function]
-get-type-style-property
get-weight
@function get-weight($name) { ... }
@function get-weight($name) { @return get('weight-#{$name}'); }
Description
Get a type weight style property
Parameters
parameter Name | parameter Description | parameter Type | parameter Default value |
---|---|---|---|
$name | The name of the defined type style. | String | — none |
Returns
String
—Return the custom property and fallback of the weight style.
Requires
- [function]
get
Used by
- [mixin]
caution
- [mixin]
danger
- [mixin]
menu-group-link
- [mixin]
normalize-lists
- [mixin]
rating-display
- [mixin]
name-airy
- [mixin]
name
- [mixin]
trigger
get-type-style-with-fallback
@function get-type-style-with-fallback($path) { ... }
@function get-type-style-with-fallback($path) { $theme-map: common.get-theme-map(settings.$themes, settings.$preferred-theme); $type-style: map.get($theme-map, $path...); // Fallback to default theme if type style doesn't exist on the preferred theme to avoid an error @if not $type-style { @warn "Attempting to fallback to '#{common.$default-theme}' theme"; $theme-map: common.get-theme-map(settings.$themes, common.$default-theme); $type-style: map.get($theme-map, $path...); } @return $type-style; }
Description
Retrieve a defined type style group definition from the preferred theme map first, then if not found retry with the fallback default theme.
Parameters
parameter Name | parameter Description | parameter Type | parameter Default value |
---|---|---|---|
$path | Path of type style definition in theme map | List | — none |
Returns
Map
—Theme map containing a style definition.
Requires
- [function]
get-theme-map
- [function]
get
- [variable]
themes
- [variable]
preferred-theme
- [variable]
default-theme
Used by
- [function]
get-type-style
get-type-style
@function get-type-style($name) { ... }
@function get-type-style($name) { $type-style: null; $is-hero: string.index($name, 'hero'); $has-alternate: string.index($name, 'alternate'); @if $alternate or $is-hero { @if $alternate and $is-hero and not $has-alternate { $name: '#{$name}-alternate'; } $type-style: get-type-style-with-fallback('deprecated', $name); } @else { $type-style: get-type-style-with-fallback($name); } @if not $type-style { $alt-msg: if($alternate, 'alternate variant of the ', ''); @error "The #{$alt-msg}type style "#{$name}" does not exist."; } @return $type-style; }
Description
Get a defined type style group definition.
Parameters
parameter Name | parameter Description | parameter Type | parameter Default value |
---|---|---|---|
$name | The name of the defined type style. | String | — none |
Returns
Map
—Return a map containing a style definition.
Throws
The #{$alt-msg}type style
Requires
- [function]
get-type-style-with-fallback
Used by
- [mixin]
style-as
get-type-style-variant-weight
@function get-type-style-variant-weight($type-style, $variant) { ... }
@function get-type-style-variant-weight($type-style, $variant) { $theme-map: common.get-theme-map(settings.$themes, common.$default-theme); $category: null; $weight-token: null; @while not $weight-token { @each $c in settings.$type-style-categories { $found: string.index($type-style, $c); @if $found { $category: $c; $weight-token: '#{$category}-weight-#{$variant}'; } @else { $weight-token: -1; } } } @if $weight-token and $weight-token != -1 and not map.has-key($theme-map, $weight-token) { @error "#{$weight-token}: Variant '#{$variant}' does not exist for '#{$type-style}' type style."; } $property-name: common.get-property-name('typography', $category, 'weight', $variant); $value: map.get($theme-map, $weight-token); @return var(#{$property-name}, #{$value}); }
Description
Returns a font weight variant custom property and fallback for the new typography tokens set. This is used to override the default font-weight with the variant value instead.
Parameters
parameter Name | parameter Description | parameter Type | parameter Default value |
---|---|---|---|
$type-style | Type style name | String | — none |
$variant | Variant name (strong, stronger) | String | — none |
Returns
Map
—Variant font weight value
Throws
#{$weight-token}: Variant
Requires
- [function]
get-theme-map
- [function]
get-property-name
- [function]
get
- [variable]
themes
- [variable]
default-theme
- [variable]
type-style-categories
Used by
- [mixin]
style-as
get-properties
@function get-properties($theme: settings.$preferred-theme, $deprecated: false) { ... }
@function get-properties($theme: settings.$preferred-theme, $deprecated: false) { $theme-map: common.get-theme-map(settings.$themes, $theme); @if not $deprecated { $theme-map: map.deep-remove($theme-map, 'deprecated'); } $properties: common.flatten-map($theme-map); @return $properties; }
Description
Returns a theme's typography tokens as a flattened map
Parameters
parameter Name | parameter Description | parameter Type | parameter Default value |
---|---|---|---|
$theme | Name of the theme | String | settings.$preferred-theme |
$deprecated | Include deprecated typography styles. Not recommended. | Bool | false |
Returns
Map
—Final flattened map
Requires
- [function]
get-theme-map
- [function]
flatten-map
- [variable]
themes
-get-type-style-value
@function -get-type-style-value($theme: settings.$default-theme, $alias) { ... }
@function -get-type-style-value($theme: settings.$default-theme, $alias) { $theme-map: common.get-theme-map(settings.$themes, $theme); $has-key: map.has-key($theme-map, $path...); @if not $has-key { @error "Type style value (#{$path}) not found."; } @return map.get($theme-map, $path...); }
Description
Retrieves a typography style property value
Parameters
parameter Name | parameter Description | parameter Type | parameter Default value |
---|---|---|---|
$theme | Name of the theme | String | settings.$default-theme |
$alias | Alias of spacing unit | String | — none |
Returns
Number
—Spacing value from the theme
Throws
Type style value (#{$path}) not found.
Requires
- [function]
get-theme-map
- [function]
get
- [variable]
themes
Used by
- [function]
-get-type-style-property
-get-type-style-property
@function -get-type-style-property($path) { ... }
@function -get-type-style-property($path) { $theme-map: common.get-theme-map(settings.$themes, settings.$preferred-theme); @if not map.has-key($theme-map, $path...) { @error "The type style property (#{$path}) does not exist."; } $property: common.get-property-name('typography', $path...); $fallback: -get-type-style-value(settings.$preferred-theme, $path...); @return string.unquote('var(#{$property}, #{$fallback})'); }
Description
Get a single type style property definition.
Parameters
parameter Name | parameter Description | parameter Type | parameter Default value |
---|---|---|---|
$path | The map path to the desired property definition. | List | — none |
Returns
List
or String
or Number
—Return the value of the type styoe property.
Throws
The type style property (#{$path}) does not exist.
Requires
- [function]
get-theme-map
- [function]
get-property-name
- [function]
-get-type-style-value
- [variable]
themes
- [variable]
preferred-theme
Used by
- [function]
get
Mixins
custom-properties
@mixin custom-properties($theme: 'base', $deprecated: false, $overrides) { ... }
@mixin custom-properties($theme: 'base', $deprecated: false, $overrides) { @if $theme == 'base' { @include webTokens.custom-properties($deprecated); } @else if $theme == 'petmd' { @include petmdTokens.custom-properties($deprecated); } @else if $theme == 'gordita' { @include gorditaTokens.custom-properties($deprecated); } @else if $theme == 'enterprise' { @include enterpriseTokens.custom-properties($deprecated); } @else { @error "Theme '#{$theme}' not found."; } @if $overrides { @each $key, $value in $overrides { #{common.get-property-name('typography', $key)}: $value; } } }
Description
Generates CSS Custom Properties for a Chirp theme's typography tokens
Parameters
parameter Name | parameter Description | parameter Type | parameter Default value |
---|---|---|---|
$theme | The name of the theme to look up | String | 'base' |
$deprecated | Includes custom properties for deprecated type styles | Bool | false |
$overrides | Map that overrides any matching values within the theme | Map | — none |
Example
Apply all available properties to the :root
of the page
@use '~@chewy/kib-foundations/src/typography';
:root {
@include typography.custom-properties;
}
Apply properties to a selector
@use '~@chewy/kib-foundations/src/typography';
.chirp-typography {
@include typography.custom-properties;
}
Override a typography property
@use '~@chewy/kib-foundations/src/typography';
.chirp-typography-custom {
@include typography.custom-properties($overrides: ('text-typeface': Roboto));
}
Throws
Theme
Requires
- [function]
get-property-name
style-as
@mixin style-as($name, $variant, $alternate) { ... }
@mixin style-as($name, $variant, $alternate) { @if map.has-key(settings.$aliases, $type-style) { $type-style: map.get(settings.$aliases, $type-style); } // Returns alias equivalent if it exists @if map.has-key(settings.$aliases, $type-style) and not $alternate { $alias-style: map.get(settings.$aliases, $type-style); @if meta.type-of($alias-style) == 'list' and list.length($alias-style) == 2 { $type-style: list.nth($alias-style, 1); $variant: list.nth($alias-style, 2); } } $style: functions.get-type-style($type-style, $alternate); @each $name, $value in $style { $property-name: common.get-property-name( 'typography', if($alternate, 'deprecated', null), $type-style, $name ); $css-variable: var(#{$property-name}, #{$value}); @if $name == 'font-weight' { font-weight: if( $variant, functions.get-type-style-variant-weight($type-style, $variant), $css-variable ); } @else if $name == 'text-case' { text-transform: $css-variable; } @else { #{$name}: $css-variable; } } }
Description
Generate styles using custom properties from a defined type style.
Parameters
parameter Name | parameter Description | parameter Type | parameter Default value |
---|---|---|---|
$name | The name of the type style | String | — none |
$variant | The variant name of the type style | String | — none |
$alternate | Applies the deprecated alternate type style definition | Boolean | — none |
Example
Apply styles for a type style definition
@use '~@chewy/kib-foundations/src/typography';
.my-custom-class {
@include typography.style-as('display-1');
}
Apply styles for a variant type style
@use '~@chewy/kib-foundations/src/typography';
.my-custom-class {
@include typography.style-as('editorial-heading-2', 'strong');
}
Apply styles for a deprecated alternate type style definition
@use '~@chewy/kib-foundations/src/typography';
.my-custom-class {
@include typography.style-as('display-1', $alternate: true);
}
Requires
- [function]
get
- [function]
get-type-style
- [function]
get-property-name
- [function]
get-type-style-variant-weight
- [variable]
aliases