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]
menu-group-link
- [mixin]
normalize-lists
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 -transform-type-style($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
- [function]
-transform-type-style
Used by
- [mixin]
style-as
- [function]
get-type-style-property
- [mixin]
style-as-type
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'); } $transformed: -recursive-transform($theme-map); $flattened: common.flatten-map($transformed); $properties: (); // Filter out any properties that have other properties as values. // This is because the style-as will being those other properties anyway, so // the "middle-man" properties aren't used anywhere and thus don't need to be set. @each $name, $value in $flattened { @if meta.type-of($value) != 'string' or not string.index($value, 'var(') { $properties: map.set($properties, $name, $value); } } @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]
-recursive-transform
- [function]
flatten-map
- [variable]
themes
Used by
- [mixin]
custom-properties
- [mixin]
custom-properties
-transform-type-style
@function -transform-type-style($type-style) { ... }
@function -transform-type-style($type-style) { $map: $type-style; @each $key, $value in $map { $transformed: $value; @if meta.type-of($value) == number and math.unit($value) == 'px' { @if $key == 'font-size' { $transformed: unit.rem($value); } @else if $key == 'line-height' { $line-height: $value; $font-size: map.get($map, 'font-size'); $transformed: math.div($line-height, $font-size); } } @if $key == 'paragraph-spacing' { $transformed: spacing.get('s4'); } $map: map.set($map, $key, $transformed); } @return $map; }
Description
Runs some transforms on properties in a type style group definition.
Parameters
parameter Name | parameter Description | parameter Type | parameter Default value |
---|---|---|---|
$type-style | The name of the defined type style. | Map | — none |
Returns
Map
—Return a map containing a style definition.
Used by
- [function]
get-type-style
- [function]
-recursive-transform
-recursive-transform
@function -recursive-transform($map) { ... }
@function -recursive-transform($map) { @each $key, $value in $map { @if meta.type-of($value) == 'map' { // It's a type style group, so transform it @if map.has-key($value, 'font-size') { $value: -transform-type-style($value); $map: map.set($map, $key, $value); } @else { // We need to go deeper $map: map.set($map, $key, -recursive-transform($value)); } } } @return $map; }
Description
Recursively transforms all map properties with the transform-type-style
function.
Parameters
parameter Name | parameter Description | parameter Type | parameter Default value |
---|---|---|---|
$map | The map to recursively transform | Map | — none |
Returns
Map
—The transformed map
Requires
- [function]
-transform-type-style
Used by
- [function]
get-properties
-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) { $typography-properties: functions.get-properties($theme, $deprecated); @if $overrides { $typography-properties: map.deep-merge($typography-properties, $overrides); } @each $key, $value in $typography-properties { #{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));
}
Requires
- [function]
get-properties
- [function]
get-property-name
style-as
@mixin style-as($name, $alternate) { ... }
@mixin style-as($name, $alternate) { $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: ''; @if meta.type-of($value) == 'string' and string.index($value, 'var(') { $css-variable: $value; } @else { $css-variable: var(#{$property-name}, #{$value}); } @if $name == 'text-case' and $name { text-transform: $css-variable; } @else if $name == 'text-decoration' { text-decoration: if($value == 'strikethrough', line-through, $value); } @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 |
$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 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-type-style
- [function]
get-property-name