Chirp Sass Documentation

Elevation

Installation

  yarn add @chewy/kib-foundations

Import

  @use '~@chewy/kib-foundations/src/elevation';

Mixins

@mixin elevation($emphasis: 'medium') { ... }@mixin elevation($emphasis: 'medium') { 
  @warn "elevation.elevation() is deprecated. Use elevation.apply('emphasis-primary') or similar named emphasis levels.";

  // Map legacy emphasis names to new names
  $mapping: map.get(settings.$levels, $emphasis);

  @if $mapping {
    $new-emphasis: map.get($mapping, 'shadow');
    @include apply($new-emphasis);
  }
 }

Description

Legacy elevation shadow mixin

Parameters

Parameters
parameter Name	parameter Description	parameter Type	parameter Default value
`$emphasis`	elevation emphasis level	`String`	`'medium'`

Requires

[mixin] apply
[function] get
[variable] levels

@mixin apply($emphasis) { ... }@mixin apply($emphasis) { 
  box-shadow: get-value($emphasis);
 }

Description

Apply elevation shadow with theming support. Reads shadow layers from elevation tokens and generates box-shadow with var() references.

Parameters

Parameters
parameter Name	parameter Description	parameter Type	parameter Default value
`$emphasis`	Shadow emphasis level 'emphasis-primary', 'emphasis-secondary', 'overlay-small', 'overlay-large'	`String`	— none

Requires

[function] get-value

Functions

@function get-value($emphasis) { ... }@function get-value($emphasis) { 
  $emphasis-map: map.get(settings.$elevation, $emphasis);

  @if not $emphasis-map {
    @error "Elevation emphasis '#{$emphasis}' not found.";
  }

  $shadows: ();
  $layer: 1;

  // Iterate through numbered layers (1, 2, 3, ...) until no more exist
  @while map.has-key($emphasis-map, '#{$layer}') {
    $layer-map: map.get($emphasis-map, '#{$layer}');

    $offset-x: -get-elevation-var($emphasis, $layer, 'offset-x', $layer-map);
    $offset-y: -get-elevation-var($emphasis, $layer, 'offset-y', $layer-map);
    $blur: -get-elevation-var($emphasis, $layer, 'blur', $layer-map);
    $spread: -get-elevation-var($emphasis, $layer, 'spread', $layer-map);
    $color: -get-elevation-var($emphasis, $layer, 'color', $layer-map);

    $shadow: #{$offset-x} #{$offset-y} #{$blur} #{$spread} #{$color};
    $shadows: list.append($shadows, $shadow, comma);
    $layer: $layer + 1;
  }

  @return $shadows;
 }

Description

Flatten shadow properties into a box-shadow string. Reads from the elevation token map, iterating over numbered layers ('1', '2', etc.).

Parameters

Parameters
parameter Name	parameter Description	parameter Type	parameter Default value
`$emphasis`	Shadow emphasis level New format: 'emphasis-primary', 'emphasis-secondary', 'overlay-small', 'overlay-large'	`String`	— none

Returns

String —

Complete box-shadow CSS value

Throws

Elevation emphasis

Requires

[function] get
[function] -get-elevation-var
[variable] elevation
[variable] color

Used by

[mixin] apply

@function -get-elevation-var($emphasis, $layer, $prop, $layer-map) { ... }@function -get-elevation-var($emphasis, $layer, $prop, $layer-map) { 
  $property: common.get-property-name('elevation', $emphasis, '#{$layer}', $prop);
  $fallback: map.get($layer-map, $prop);

  @return string.unquote('var(#{$property}, #{$fallback})');
 }

Description

Create a CSS var() reference for an elevation property with fallback.

Parameters

Parameters
parameter Name	parameter Description	parameter Type	parameter Default value
`$emphasis`	Emphasis level name	`String`	— none
`$layer`	Layer number	`Number`	— none
`$prop`	Property name (offset-x, offset-y, blur, spread, color)	`String`	— none
`$layer-map`	Map of the layer's properties	`Map`	— none

Returns

String —

CSS var() with fallback

Requires

[function] get-property-name
[function] get

Used by

[function] get-value

Variables

$elevation: (...);$elevation: map.get(tokens.$chirp-theme, 'elevation');

Description

Elevation tokens from chirp-design-tokens Used by elevation.apply() mixin for new elevation system

Type

Map

$levels: (...);$levels: (
  minimal: (
    opacity: 0.08,
    blur-radius: $_blur-tiny,
    color: color.get('shadow', 'low-emphasis'),
    shadow: 'emphasis-secondary'
  ),
  medium: (
    opacity: 0.08,
    blur-radius: $_blur-small,
    color: color.get('shadow', 'medium-emphasis'),
    shadow: 'emphasis-primary'
  ),
  high: (
    opacity: 0.16,
    blur-radius: $_blur-default,
    color: color.get('shadow', 'high-emphasis'),
    shadow: 'overlay-small'
  )
);

Description

Legacy elevation emphasis levels

Type

Map

Used by

[mixin] elevation