Accessibility

functions

focus-halo

@function focus-halo() { ... }

Description

Create a focus halo from an inner and outer ring color.

Parameters

None.

Used by

mixins

reduce-motion

@mixin reduce-motion() { ... }

Description

Disable animations and transitions when either children of .reduced-motion or the user has specified that they prefer reduced motion on their OS.

Parameters

None.

Used by

sr-only

@mixin sr-only() { ... }

Description

Screen reader only - ensure that the element is only visible to screen readers.

Parameters

None.

Used by

Links

focus-halo

@mixin focus-halo($current-shadows...) { ... }

Description

A box shadow focus indicator that is offset from the focused element.

Parameters

parameter Nameparameter Descriptionparameter Typeparameter Default value
$current-shadows...

Zero or more additional shadows to be applied in addition to the focus indicator.

Box-shadow[] none

Requires

focus-ring

@mixin focus-ring($current-shadows...) { ... }

Description

A box shadow focus indicator that is directly attached to the focused element. Should only be used when the focused element conveys focus through some additional mechanism, such as the <input>'s caret.

Parameters

parameter Nameparameter Descriptionparameter Typeparameter Default value
$current-shadows...

Zero or more additional shadows to be applied in addition to the focus indicator.

Box-shadow[] none

variables

focus-halo

$focus-halo: a11y.focus-halo() !default;

Description

The default focus shadow has a 2px outer ring and an inner ring that matches the body's background color by default, giving the illusion of transparency.

Used by

focus-ring

$focus-ring: a11y.focus-ring() !default;

Description

A collapsed focus shadow that is meant to be used when the focused element conveys focus through some other mechanism, such as an <input>'s caret.

Used by

Color

functions

family

@function family($name, $ref-family, $grade-root: null, $inverse: false) { ... }

Description

Create a new color family map that references an existing family map.

Parameters

parameter Nameparameter Descriptionparameter Typeparameter Default value
$name

The name of the family that you'd like to create.

String none
$ref-family

The name of the family that you'd like to reference.

String none
$grade-root

If provided, this will be the midpoint of the "lighter/darker" shade swatch.

Numbernull
$inverse

Invert the grade map.

Booleanfalse

Example

Minimal usage

@debug family('foo', 'teal');
// (
//   10: var(--nds-teal-10),
//   20: var(--nds-teal-20),
//   ...30 - 80...
//   90: var(--nds-teal-90),
//   100: var(--nds-teal-100),
// )

With $grade-root

@debug family('foo', 'teal', 30);
// (
//   10: var(--nds-teal-10),
//   20: var(--nds-teal-20),
//   ...all other grades...
//   'lighter': var(--nds-foo-10),
//   'light': var(--nds-foo-20),
//   '#root': var(--nds-foo-30),
//   'dark': var(--nds-foo-40),
//   'darker': var(--nds-foo-50),
// )

variables

primary-family

$primary-family: 'teal' !default;

Description

The primary color family is used in UI elements that use a default color.

primary-grade

$primary-grade: 60 !default;

Description

The grade that defines the "midpoint" of the primary family. For instance, setting this to 60 will cause the primary token to reference primary-60.

base-family

$base-family: 'navy' !default;

Description

The base color family is used for background color gradients and text colors.

base-grade

$base-grade: null !default;

Description

The grade that defines the "midpoint" of the base family. For instance, setting this to 60 will cause the base token to reference base-60.

disabled-family

$disabled-family: 'base-color' !default;

Description

The color family that will be used for disabled controls.

disabled-grade

$disabled-grade: 30 !default;

Description

The grade that defines the "midpoint" of the disabled family. For instance, setting this to 60 will cause the disabled token to reference disabled-60.

error-family

$error-family: 'red' !default;

Description

The color family that will be used to convey errors/failing.

error-grade

$error-grade: 60 !default;

Description

The grade that defines the "midpoint" of the error family. For instance, setting this to 60 will cause the error token to reference error-60.

success-family

$success-family: 'green' !default;

Description

The color family that will be used to convey success/passing.

success-grade

$success-grade: 60 !default;

Description

The grade that defines the "midpoint" of the success family. For instance, setting this to 60 will cause the success token to reference success-60.

warning-family

$warning-family: 'yellow' !default;

Description

The color family that will be used to convey warning/caution.

warning-grade

$warning-grade: 60 !default;

Description

The grade that defines the "midpoint" of the warning family. For instance, setting this to 60 will cause the warning token to reference warning-60.

colors

$colors: () !default;

Description

A list of the color families that should be used.

colors-omitted

$colors-omitted: () !default;

Description

A list of the color families that should not be used.

[private] -blue-default

$-blue-default: (
	10: #f0f7ff,
	20: #d9ebff,
	30: #badbff,
	40: #8fc2f7,
	50: #4696eb,
	60: #2576cc,
	70: #1d5da1,
	80: #17477a,
	90: #12365c,
	100: #0e253d,
);

Description

The default blue family. Override by declaring a $blue map.

[private] -cyan-default

$-cyan-default: (
	10: #e9f7fb,
	20: #d3eef5,
	30: #afe0ed,
	40: #7cc9de,
	50: #2c9fbf,
	60: #1f7e99,
	70: #1c6275,
	80: #1b4c59,
	90: #163740,
	100: #10252b,
);

Description

The default cyan family. Override by declaring a $cyan map.

[private] -gray-default

$-gray-default: (
	10: #f5f5f5,
	20: #e8e8e8,
	30: #d6d6d6,
	40: #bdbdbd,
	50: #919191,
	60: #737373,
	70: #595959,
	80: #424242,
	90: #333,
	100: #232323,
);

Description

The default gray family. Override by declaring a $gray map.

[private] -green-default

$-green-default: (
	10: #e6fae6,
	20: #d0f2d0,
	30: #aae3aa,
	40: #7ccf7c,
	50: #49a349,
	60: #228522,
	70: #216621,
	80: #1c4f1c,
	90: #163b16,
	100: #112911,
);

Description

The default green family. Override by declaring a $green map.

[private] -navy-default

$-navy-default: (
	10: #f2f5f8,
	20: #e2e8ee,
	30: #ced7e0,
	40: #b1bdc9,
	50: #8493a3,
	60: #63768a,
	70: #475b70,
	80: #32475e,
	90: #243547,
	100: #192633,
);

Description

The default navy family. Override by declaring a $navy map.

[private] -purple-default

$-purple-default: (
	10: #f6f5ff,
	20: #eae6ff,
	30: #d9d1ff,
	40: #bfb3ff,
	50: #9684f0,
	60: #7663d6,
	70: #5d4dab,
	80: #483c82,
	90: #342d59,
	100: #26213d,
);

Description

The default purple family. Override by declaring a $purple map.

[private] -red-default

$-red-default: (
	10: #fff2f2,
	20: #ffe0e0,
	30: #ffc8c7,
	40: #ffa2a1,
	50: #ed6664,
	60: #c93f3c,
	70: #9e3331,
	80: #7a2a28,
	90: #591e1d,
	100: #3d1515,
);

Description

The default red family. Override by declaring a $red map.

[private] -teal-default

$-teal-default: (
	10: #e9f7f7,
	20: #d1eded,
	30: #abe0e0,
	40: #76cbcc,
	50: #29a1a3,
	60: #1a8082,
	70: #196263,
	80: #174c4d,
	90: #133838,
	100: #0f2929,
);

Description

The default teal family. Override by declaring a $teal map.

[private] -yellow-default

$-yellow-default: (
	10: #fff5d9,
	20: #fae7af,
	30: #f0d278,
	40: #deb647,
	50: #b88828,
	60: #96690e,
	70: #7a4f11,
	80: #633b12,
	90: #4a2a0f,
	100: #331d0d,
);

Description

The default yellow family. Override by declaring a $yellow map.

background-color

$background-color: var(--nds-white) !default;

Description

The main background color.

Used by

background-color-inverse

$background-color-inverse: var(--nds-base-color-90) !default;

Description

The inverse background color.

text-color

$text-color: var(--nds-base-color-90) !default;

Description

The main text color.

text-color-inverse

$text-color-inverse: var(--nds-white) !default;

Description

The inverse text color.

subdued-color

$subdued-color: var(--nds-base-color-60) !default;

Description

A subdued or "muted" text color, used for less emphasized text.

selection-background-color

$selection-background-color: 'null' !default;

Description

The background color.

selection-text-color

$selection-text-color: var(--nds-text-color-inverse) !default;

Description

The text color.

focus-color

$focus-color: var(--nds-blue-50) !default;

Description

The color used for the :focus state.

focus-color-background

$focus-color-background: var(--nds-blue-20) !default;

Description

The background color used for the :focus state in focusable lists, such as listboxes and menus.

focus-halo-inner-color

$focus-halo-inner-color: var(--nds-background-color) !default;

Description

The color of the inner ring for the focus halo. Used to visually offset the default focus halo from the focused element.

focus-halo-outer-color

$focus-halo-outer-color: var(--nds-focus-color) !default;

Description

The color of the outer ring for the focus halo.

mixins

color-tokens

@mixin color-tokens() { ... }

Description

Color tokens as CSS custom properties.

Parameters

None.

Used by

color

Deprecated!

@include color-tokens inside your own :root declaration or use the root mixin to set all design system tokens.

@mixin color() { ... }

Description

Color tokens set as CSS custom properties on the :root element and color schemes set anywhere with the data-color-scheme attribute.

Parameters

None.

Requires

Config

variables

browser-font-size

$browser-font-size: 16 !default;

Description

The expected browser font size, which determines the value of 1rem. This is 16 in all browsers by default and shouldn't be changed under most scenarios.

Type

Number

Links

enable-duplicate-declarations

$enable-duplicate-declarations: false !default;

Description

Indicates whether duplicate declarations should be allowed. If true, including a style mixin will result in duplicate CSS. If false, including a style mixin multiple times will only create a declaration the first time.

Type

Boolean

Links

enable-dark-scheme

$enable-dark-scheme: false !default;

Description

Enable the dark scheme. This will only make it possible for the dark scheme to be applied by either the user's OS setting or by manually applying a class to the :root element.

Type

Boolean

Used by

Links

enable-helpers

$enable-helpers: true !default;

Description

Enable helper declarations. Only has an effect when using the full stylesheet. Helper declarations can always be used imperatively via @include.

Type

Boolean

Used by

Links

[private] -default-utilities

$-default-utilities: (
	'color': false,
	'spacing': false,
);

Description

The default map of utilities for reference. All utilities are disabled by default.

Links

utilities

$utilities: () !default;

Description

A map of utility declarations that should be included in the full stylesheet. Only has an effect when using the full stylesheet. See $-default-utilities for a list of the possible utilities. Utility declarations can always be used imperatively via @include.

Type

Map

Used by

Links

focus-visible-polyfill

$focus-visible-polyfill: false !default;

Description

Indicates whether the :focus-visible polyfill is being used. When true, focus selectors will use the focus-visible polyfill classes.

Type

Boolean

Links

Device

variables

hd-dpi

$hd-dpi: 200 !default;

Description

The minimum dots per inch (dpi) of a high-resolution screen

Used by

hd-dppx

$hd-dppx: 1.25 !default;

Description

The minimum dots per pixel unit (dppx) for a high-resolution screen

Used by

min-xs

$min-xs: 0 !default;

Description

The minimum width for an extra small screen: a handset.

min-sm

$min-sm: 600px !default;

Description

The minimum width for a small screen: a large handset or small tablet.

min-md

$min-md: 960px !default;

Description

The minimum width for a medium screen: a large tablet or small laptop.

min-lg

$min-lg: 1280px !default;

Description

The minimum width for a large screen: a desktop.

min-xl

$min-xl: 1920px !default;

Description

The minimum width for an extra large screen: a high-definition device.

mixins

media-hd

@mixin media-hd($dpi: $hd-dpi, $dppx: $hd-dppx) { ... }

Description

A media query helper for high definition screens.

Parameters

parameter Nameparameter Descriptionparameter Typeparameter Default value
$dpi

The dpi of a high definition (HD) screen.

Number$hd-dpi
$dppx

The dppx of a high definition (HD) screen.

Number$hd-dppx

Requires

Links

media-up

@mixin media-up($size, $breakpoints: $devices) { ... }

Description

A media query helper for device sizes. @content will apply to the given size and up.

Parameters

parameter Nameparameter Descriptionparameter Typeparameter Default value
$size

The device size: xs, sm, md, lg, or xl.

String none
$breakpoints

The map of breakpoints to use.

Map$devices

Elevation

mixins

elevation-tokens

@mixin elevation-tokens() { ... }

Description

Elevation tokens as CSS custom properties.

Parameters

None.

Used by

elevation

Deprecated!

@include elevation-tokens inside your own :root declaration or use the root mixin to set all design system tokens.

@mixin elevation() { ... }

Description

Elevation tokens set as CSS custom properties on the :root element.

Parameters

None.

Requires

Helpers

mixins

a11y-helpers

@mixin a11y-helpers() { ... }

Description

Accessibility helper classes.

Parameters

None.

Requires

Main API

mixins

root

@mixin root() { ... }

Description

All foundational design tokens set as CSS custom properties on the :root.

Parameters

None.

Requires

Used by

tokens

Deprecated!

Use the root mixin to set your :root declaration, or set tokens on your own selector with the design-tokens mixin.

@mixin tokens() { ... }

Description

All foundational design tokens set as CSS custom properties on the :root.

Parameters

None.

Requires

design-tokens

@mixin design-tokens() { ... }

Description

All foundational design tokens as CSS custom properties. Use when you need access to all CSS custom properties outside of the :root context.

Parameters

None.

Example

Usage in shadow DOM styling

@use '@wwnds/core' as nds;
:host {
  @include nds.design-tokens;
}

Requires

components

@mixin components() { ... }

Description

Declarations for every component.

Parameters

None.

Used by

helpers

@mixin helpers() { ... }

Description

Helper declarations that set a composed style uncoupled from any component.

Parameters

None.

Requires

Used by

utilities

@mixin utilities() { ... }

Description

Utility declarations that set one property per class.

Parameters

None.

Requires

Used by

complete

@mixin complete() { ... }

Description

The complete design system set in a single global stylesheet.

Parameters

None.

Requires

reset

@mixin reset() { ... }

Description

The global HTML reset. Forked from the Bootstrap reboot to use the Norton Design System foundations.

Parameters

None.

Requires

Links

Miscellaneous

variables

radius-base

$radius-base: var(--nds-radius-sm) !default;

Description

The base border radius.

Used by

mixins

miscellaneous-tokens

@mixin miscellaneous-tokens() { ... }

Description

Miscellaneous tokens as CSS custom properties.

Parameters

None.

Requires

Used by

miscellaneous

Deprecated!

@include miscellaneous-tokens inside your own :root declaration or use the root mixin to set all design system tokens.

@mixin miscellaneous() { ... }

Description

Focus & radius tokens set as CSS custom properties on the :root element. Note: these may be moved to their own mixins at sometime in the future.

Parameters

None.

Requires

Motion

functions

transition

@function transition($properties, $duration, $easing) { ... }

Description

Apply one transition to many properties.

Parameters

parameter Nameparameter Descriptionparameter Typeparameter Default value
$properties

A single or list of CSS properties.

String or Listof none
$duration

A duration value.

String none
$easing

An easing value.

String none

Links

variables

duration-scalar

$duration-scalar: 1 !default;

Description

A multiplier used for increasing/decreasing all motion speed when motion is allowed (prefers-reduced-motion: no-preference).

Used by

Links

duration-simple

$duration-simple: 100ms;

Description

A duration used for simple animations such as selection controls.

Used by

Links

duration-simple-enter

$duration-simple-enter: 150ms;

Description

A duration used for simple entrances such as fade-ins.

Used by

Links

duration-simple-exit

$duration-simple-exit: 75ms;

Description

A duration used for simple exits such as fade-outs.

Used by

Links

duration-complex

$duration-complex: 200ms;

Description

A duration used for complex animations such as shape changes.

Used by

Links

duration-detailed

$duration-detailed: 500ms;

Description

A duration used for detailed animations such as icon transformations.

Used by

Links

duration-open

$duration-open: 250ms;

Description

A duration used for elements that open from a closed state, such as a sidebar.

Used by

Links

duration-close

$duration-close: 200ms;

Description

A duration used for elements that close from an opened state, such as a sidebar.

Used by

Links

duration-expand

$duration-expand: 300ms;

Description

A duration used when an element expands (grows).

Used by

Links

duration-collapse

$duration-collapse: 250ms;

Description

A duration used when an element collapses (shrinks).

Used by

Links

duration-small

$duration-small: var(--nds-duration-simple);

Description

A duration used for elements with a small transition areas, such as icons and selection controls.

Used by

Links

duration-medium-expand

$duration-medium-expand: var(--nds-duration-open);

Description

A duration used for expanding elements with larger transition areas, such as bottom sheets and expanding chips.

Used by

Links

duration-medium-collapse

$duration-medium-collapse: var(--nds-duration-close);

Description

A duration used for collapsing elements with larger transition areas, such as bottom sheets and expanding chips.

Used by

Links

duration-large-expand

$duration-large-expand: var(--nds-duration-expand);

Description

A duration used for expanding elements that traverse a large portion of the screen.

Used by

Links

duration-large-collapse

$duration-large-collapse: var(--nds-duration-collapse);

Description

A duration used for collapsing elements that traverse a large portion of the screen.

Used by

Links

easing-standard

$easing-standard: cubic-bezier(0.4, 0, 0.2, 1);

Description

Standard easing puts subtle attention at the end of an animation, by giving more time to deceleration than acceleration. It is the most common form of easing.

Elements that begin and end at rest use standard easing. They speed up quickly and slow down gradually, in order to emphasize the end of the transition.

Used by

Links

easing-deceleration

$easing-deceleration: cubic-bezier(0, 0, 0.2, 1);

Description

Incoming elements are animated using deceleration easing, which starts a transition at peak velocity (the fastest point of an element’s movement) and ends at rest.

Used by

Links

easing-acceleration

$easing-acceleration: cubic-bezier(0.4, 0, 1, 1);

Description

Elements exiting a screen use acceleration easing, where they start at rest and end at peak velocity.

Used by

Links

easing-sharp

$easing-sharp: cubic-bezier(0.4, 0, 0.6, 1);

Description

Timing function to quickly accelerate and decelerate

Used by

Links

mixins

motion-tokens

@mixin motion-tokens() { ... }

Description

Motion tokens as CSS custom properties.

Parameters

None.

Requires

Used by

Links

motion

Deprecated!

@include motion-tokens inside your own :root declaration or use the root mixin to set all design system tokens.

@mixin motion() { ... }

Description

Motion tokens set as CSS custom properties on the :root element.

Parameters

None.

Requires

Links

Spacing

functions

px-rem

@function px-rem() { ... }

Description

Convert a px value to a rem spacer.

Parameters

None.

rem-px

@function rem-px() { ... }

Description

Convert a rem value to a px spacer.

Parameters

None.

px

@function px() { ... }

Description

Use a px value as a px spacer.

Parameters

None.

rem

@function rem() { ... }

Description

Use a rem value as a rem spacer.

Parameters

None.

Used by

padding

@function padding($padding-length, $border-width: 0) { ... }

Description

Padding helper Ensures that padding fits the design system box model.

Parameters

parameter Nameparameter Descriptionparameter Typeparameter Default value
$padding-length

The desired padding length.

String or Number none
$border-width

The desired border width.

String or Number0

Links

spacer

@function spacer() { ... }

Description

Get a spacer from a role or a value.

Parameters

None.

Used by

mixins

spacing-tokens

@mixin spacing-tokens() { ... }

Description

Spacing tokens as CSS custom properties.

Parameters

None.

Used by

spacing

Deprecated!

@include motion-tokens inside your own :root declaration or use the root mixin to set all design system tokens.

@mixin spacing() { ... }

Description

Spacing tokens set as CSS custom properties on the :root element.

Parameters

None.

Requires

Typography

functions

sans

@function sans() { ... }

Description

Set a sans-serif font with the system stack fallback.

Parameters

None.

serif

@function serif() { ... }

Description

Set a serif font with the system stack fallback.

Parameters

None.

mono

@function mono() { ... }

Description

Set a monospace font with the system stack fallback.

Parameters

None.

size

@function size($px) { ... }

Description

Get a font size using rem spacers.

Parameters

parameter Nameparameter Descriptionparameter Typeparameter Default value
$px

The font size in pixels.

Number none

Returns

String

The font size spacer and rem conversion string.

mixins

font-smoothing

@mixin font-smoothing() { ... }

Description

Apply font smoothing.

Parameters

None.

Links

typeset

@mixin typeset($family: font-family-base, $height: line-height-base, $size: font-size-base, $size: null) { ... }

Description

Create a composed set of typography design tokens. Explicitly specifying a value of null values will result in the property not being set.

Parameters

parameter Nameparameter Descriptionparameter Typeparameter Default value
$family

The font size, which should be a font-size-* token.

Font-familyfont-family-base
$height

The line height, which should be a line-height-* token.

Line-heightline-height-base
$size

The font size, which should be a font-size-* token.

Font-sizefont-size-base
$size

The font weight, which should be a font-weight-* token.

Font-sizenull

Used by

body-base

@mixin body-base() { ... }

Description

The "base" body typeset uses all -base tokens.

Parameters

None.

Example

.my-selector {
  @include nds.body-base;
}

// CSS output
.my-selector {
  font-family: var(--nds-font-family-base);
  font-size: var(--nds-font-size-base);
  line-height: var(--nds-line-height-base);
}

Requires

body-xs

@mixin body-xs() { ... }

Description

A typeset suitable for extra small body text.

Parameters

None.

Example

.my-selector {
  @include body-xs;
}

// CSS output with default config
.my-selector {
  font-family: var(--nds-font-family-base);
  font-size: var(--nds-font-size-xs);
  line-height: var(--nds-line-height-base);
}

Requires

body-sm

@mixin body-sm() { ... }

Description

A typeset suitable for small body text.

Parameters

None.

Example

.my-selector {
  @include body-sm;
}

// CSS output with default config
.my-selector {
  font-family: var(--nds-font-family-base);
  font-size: var(--nds-font-size-sm);
  line-height: var(--nds-line-height-base);
}

Requires

body-md

@mixin body-md() { ... }

Description

A typeset suitable for medium body text.

Parameters

None.

Example

.my-selector {
  @include body-md;
}

// CSS output with default config
.my-selector {
  font-family: var(--nds-font-family-base);
  font-size: var(--nds-font-size-md);
  line-height: var(--nds-line-height-base);
}

Requires

body-lg

@mixin body-lg() { ... }

Description

A typeset suitable for large body text.

Parameters

None.

Example

.my-selector {
  @include body-lg;
}

// CSS output with default config
.my-selector {
  font-family: var(--nds-font-family-base);
  font-size: var(--nds-font-size-lg);
  line-height: var(--nds-line-height-base);
}

Requires

ui-base

@mixin ui-base() { ... }

Description

The "base" UI typeset uses the ui line height and -base tokens for everything else.

Parameters

None.

Example

.my-selector {
  @include ui-base;
}

// CSS output with default config
.my-selector {
  font-family: var(--nds-font-family-base);
  font-size: var(--nds-font-size-base);
  line-height: var(--nds-line-height-3);
}

Requires

Used by

ui-xs

@mixin ui-xs() { ... }

Description

A typeset suitable for extra small UI text.

Parameters

None.

Example

.my-selector {
  @include ui-xs;
}

// CSS output with default config
.my-selector {
  font-family: var(--nds-font-family-base);
  font-size: var(--nds-font-size-xs);
  line-height: var(--nds-line-height-3);
}

Requires

ui-sm

@mixin ui-sm() { ... }

Description

A typeset suitable for small UI text.

Parameters

None.

Example

.my-selector {
  @include ui-sm;
}

// CSS output with default config
.my-selector {
  font-family: var(--nds-font-family-base);
  font-size: var(--nds-font-size-sm);
  line-height: var(--nds-line-height-3);
}

Requires

ui-md

@mixin ui-md() { ... }

Description

A typeset suitable for medium UI text.

Parameters

None.

Example

.my-selector {
  @include ui-md;
}

// CSS output with default config
.my-selector {
  font-family: var(--nds-font-family-base);
  font-size: var(--nds-font-size-md);
  line-height: var(--nds-line-height-3);
}

Requires

ui-lg

@mixin ui-lg() { ... }

Description

A typeset suitable for large UI text.

Parameters

None.

Example

.my-selector {
  @include ui-lg;
}

// CSS output with default config
.my-selector {
  font-family: var(--nds-font-family-base);
  font-size: var(--nds-font-size-lg);
  line-height: var(--nds-line-height-3);
}

Requires

typeset-heading

@mixin typeset-heading($size, $height) { ... }

Description

A typeset intended for text that is meant to convey hierarchy (i.e., a heading).

Parameters

parameter Nameparameter Descriptionparameter Typeparameter Default value
$size

The font size. Required.

Font-size none
$height

The line height. Required.

Number none

Example

.my-selector {
  @include typeset-heading($size: 3rem, $height: 1.25);
}

// CSS output with default config
.my-selector {
  margin-top: 0;
  margin-bottom: var(--nds-spacing-4);
  font-family: var(--nds-font-family-headings);
  font-size: 3rem;
  font-style: var(--nds-font-style-headings);
  font-weight: var(--nds-font-weight-headings);
  line-height: 1.25;
}

Requires

Used by

heading-1

@mixin heading-1() { ... }

Description

A typeset suitable for text that is meant to convey the top level of content hierarchy, such as an h1.

Parameters

None.

Requires

heading-2

@mixin heading-2() { ... }

Description

A typeset suitable for text that is meant to convey the second level of content hierarchy, such as an h2.

Parameters

None.

Requires

heading-3

@mixin heading-3() { ... }

Description

A typeset suitable for text that is meant to convey the third level of content hierarchy, such as an h3.

Parameters

None.

Requires

heading-4

@mixin heading-4() { ... }

Description

A typeset suitable for text that is meant to convey the fourth level of content hierarchy, such as an h4.

Parameters

None.

Requires

heading-5

@mixin heading-5() { ... }

Description

A typeset suitable for text that is meant to convey the fifth level of content hierarchy, such as an h5.

Parameters

None.

Requires

heading-6

@mixin heading-6() { ... }

Description

A typeset suitable for text that is meant to convey the sixth (and lowest) level of content hierarchy, such as an h6.

Parameters

None.

Requires

typography-tokens

@mixin typography-tokens() { ... }

Description

Typography tokens as CSS custom properties.

Parameters

None.

Used by

typography

Deprecated!

@include typography-tokens inside your own :root declaration or use the root mixin to set all design system tokens.

@mixin typography() { ... }

Description

Typography tokens set as CSS custom properties on the :root element.

Parameters

None.

Requires

variables

font-family-sans

$font-family-sans: () !default;

Description

The main sans serif font family. Overrides will have $font-family-system-sans appended as a fallback.

font-family-serif

$font-family-serif: () !default;

Description

The main serif font family. Overrides will have $font-family-system-serif appended as a fallback.

font-family-mono

$font-family-mono: () !default;

Description

The main monospace font family. Overrides will have $font-family-system-mono appended as a fallback.

font-family-base

$font-family-base: var(--nds-font-family-sans) !default;

Description

The main font family that will be used throughout your application.

font-family-headings

$font-family-headings: var(--nds-font-family-base) !default;

Description

The font family that will be used for all headings.

General

mixins

arrow

@mixin arrow() { ... }

Description

A triangle arrow that connects with a Popper.js element

Parameters

None.

Requires

Utilities

functions

flatten

@function flatten($map, $name: null, $key-separator: -) { ... }

Description

Flatten a nested map.

Parameters

parameter Nameparameter Descriptionparameter Typeparameter Default value
$map

The map that should be flattened. The #root key will be treated use the name as its key.

Map none
$name

The name of the map. Resulting keys will use this as a prefix.

Stringnull
$key-separator

The separator that will be used to join map names.

String-

Returns

Map

The flattened map. Key names will reflect the nesting structure.

Example

@debug flatten((a: (b: (c: 'd'))));
// ("a-b-c": "d")
@debug flatten((a: (b: (c: 'd'))), 'foo');
// ("foo-a-b-c": "d")

and a #root key

@debug flatten(('a': ('b': 'c', '#root': 'd')), 'foo');
// ("foo-a-b": "c", "foo-a": "d")

Throws

  • When flattening #root keys, ensure that the #root is either nested or a valid $name argument is included.

Used by

deep-merge

@function deep-merge($maps...) { ... }

Description

Recursively merge a list of maps. Similar to map.merge but takes many maps and merges any sub-maps recursively.

Parameters

parameter Nameparameter Descriptionparameter Typeparameter Default value
$maps...

A list of maps that will be merged.

Map[] none

Returns

Map

A deeply merged map.

Throws

  • All arguments must be maps.

get-key

@function get-key($map, $value) { ... }

Description

Get the key that corresponds to a value in a map.

Parameters

parameter Nameparameter Descriptionparameter Typeparameter Default value
$map

The map that will be used for lookup.

Map none
$value

The value of the corresponding key.

String none

Returns

String

The map's key name corresponding to the provided value.

Example

$my-map: ('red': #f00, 'yellow': #ba7);
@debug get-key($my-map, #ba7);
// yellow

mixins

set

@mixin set($prop-maps...) { ... }

Description

Set a list of properties as CSS custom properties.

Parameters

parameter Nameparameter Descriptionparameter Typeparameter Default value
$prop-maps...

Either an arglist of key: value pairs or a list of maps with key: value pairs. Note that if the key does not begin with --, it will be added.

Arglist or Map[] none

Example

variables

.button {
  // set properties local to .button with Sass variables as parameters
  @include set($button-border-radius: 2px);
  // use the property
  border-radius: var(--button-border-radius);
}
// CSS output
.button {
  --button-border-radius: 2px;
  border-radius: var(--nds-button-border-radius, 2px);
}

custom properties map

.button {
  // set properties local to .button with a map of CSS custom properties
  @include set((
    --button-border-radius: 2px,
  ));
  // use the property
  border-radius: var(--button-border-radius);
}
// CSS output
.button {
  --button-border-radius: 2px;
  border-radius: var(--button-border-radius, 2px);
}

Throws

  • All arguments must be maps

Requires

color-utilities

@mixin color-utilities() { ... }

Description

Utility declarations for color families.

Parameters

None.

spacing-utilities

@mixin spacing-utilities() { ... }

Description

Utility declarations for spacing tokens.

Parameters

None.