Accessibility
functions
focus-halo
@function focus-halo() { ... }
Description
Create a focus halo from an inner and outer ring color.
Parameters
None.
Used by
- [mixin]
focus-halo
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
- [mixin]
a11y-helpers
sr-only
@mixin sr-only() { ... }
Description
Screen reader only - ensure that the element is only visible to screen readers.
Parameters
None.
Used by
- [mixin]
a11y-helpers
Links
focus-halo
@mixin focus-halo($current-shadows...) { ... }
Description
A box shadow focus indicator that is offset from the focused element.
Parameters
parameter Name | parameter Description | parameter Type | parameter Default value |
---|---|---|---|
$current-shadows... | Zero or more additional shadows to be applied in addition to the focus indicator. | Box-shadow[] | — none |
Requires
- [function]
focus-halo
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 Name | parameter Description | parameter Type | parameter 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
- [mixin]
miscellaneous-tokens
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
- [mixin]
miscellaneous-tokens
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 Name | parameter Description | parameter Type | parameter 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. | Number | null |
$inverse | Invert the grade map. | Boolean | false |
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] -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
- [mixin]
color
- [mixin]
root
- [mixin]
design-tokens
color
@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
- [mixin]
color-tokens
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
- [mixin]
root
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
- [mixin]
helpers
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
link-styling-context
$link-styling-context: 'main' !default;
Description
Enable link styling for the specified selector context. Setting this to null
will result in link styling being applied to all links. The default (main
) means the link styling is applied to the main :link
selector.
Type
String</code> or <code>List</code> or <code>Null
Links
link-visited-context
$link-visited-context: null !default;
Description
Enable the :visited
pseudo class styling.
Type
String</code> or <code>List</code> or <code>Null
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
- [mixin]
media-hd
hd-dppx
$hd-dppx: 1.25 !default;
Description
The minimum dots per pixel unit (dppx) for a high-resolution screen
Used by
- [mixin]
media-hd
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 Name | parameter Description | parameter Type | parameter 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 Name | parameter Description | parameter Type | parameter 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
- [mixin]
elevation
elevation
@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
- [mixin]
elevation-tokens
Helpers
mixins
a11y-helpers
@mixin a11y-helpers() { ... }
Description
Accessibility helper classes.
Parameters
None.
Requires
- [mixin]
reduce-motion
- [mixin]
sr-only
Main API
mixins
root
@mixin root() { ... }
Description
All foundational design tokens set as CSS custom properties on the :root
.
Parameters
None.
Requires
- [variable]
enable-dark-scheme
- [mixin]
color-tokens
- [mixin]
motion-tokens
- [mixin]
spacing-tokens
- [mixin]
typography-tokens
- [mixin]
miscellaneous-tokens
Used by
tokens
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
- [mixin]
root
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
- [mixin]
color-tokens
- [mixin]
motion-tokens
- [mixin]
spacing-tokens
- [mixin]
typography-tokens
- [mixin]
miscellaneous-tokens
components
@mixin components() { ... }
Description
Declarations for every component.
Parameters
None.
Used by
- [mixin]
complete
helpers
@mixin helpers() { ... }
Description
Helper declarations that set a composed style uncoupled from any component.
Parameters
None.
Requires
- [variable]
enable-helpers
Used by
- [mixin]
complete
utilities
@mixin utilities() { ... }
Description
Utility declarations that set one property per class.
Parameters
None.
Requires
Used by
- [mixin]
complete
complete
@mixin complete() { ... }
Description
The complete design system set in a single global stylesheet.
Parameters
None.
Requires
- [mixin]
root
- [mixin]
components
- [mixin]
helpers
- [mixin]
utilities
reset
@mixin reset() { ... }
Description
The global HTML reset. Forked from the Bootstrap reboot to use the Norton Design System foundations.
Parameters
None.
Requires
- [function]
rem
- [function]
spacer
- [function]
rem
- [function]
spacer
- [function]
spacer
- [function]
spacer
- [function]
spacer
- [function]
spacer
Links
Miscellaneous
variables
radius-base
$radius-base: var(--nds-radius-sm) !default;
Description
The base border radius.
Used by
- [mixin]
miscellaneous-tokens
mixins
miscellaneous-tokens
@mixin miscellaneous-tokens() { ... }
Description
Miscellaneous tokens as CSS custom properties.
Parameters
None.
Requires
- [variable]
focus-halo
- [variable]
focus-ring
- [variable]
radius-base
Used by
- [mixin]
root
- [mixin]
design-tokens
- [mixin]
miscellaneous
miscellaneous
@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
- [mixin]
miscellaneous-tokens
Motion
functions
transition
@function transition($properties, $duration, $easing) { ... }
Description
Apply one transition to many properties.
Parameters
parameter Name | parameter Description | parameter Type | parameter 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
- [mixin]
motion-tokens
Links
duration-simple
$duration-simple: 100ms;
Description
A duration used for simple animations such as selection controls.
Used by
- [mixin]
motion-tokens
Links
duration-simple-enter
$duration-simple-enter: 150ms;
Description
A duration used for simple entrances such as fade-ins.
Used by
- [mixin]
motion-tokens
Links
duration-simple-exit
$duration-simple-exit: 75ms;
Description
A duration used for simple exits such as fade-outs.
Used by
- [mixin]
motion-tokens
Links
duration-complex
$duration-complex: 200ms;
Description
A duration used for complex animations such as shape changes.
Used by
- [mixin]
motion-tokens
Links
duration-detailed
$duration-detailed: 500ms;
Description
A duration used for detailed animations such as icon transformations.
Used by
- [mixin]
motion-tokens
Links
duration-open
$duration-open: 250ms;
Description
A duration used for elements that open from a closed state, such as a sidebar.
Used by
- [mixin]
motion-tokens
Links
duration-close
$duration-close: 200ms;
Description
A duration used for elements that close from an opened state, such as a sidebar.
Used by
- [mixin]
motion-tokens
Links
duration-expand
$duration-expand: 300ms;
Description
A duration used when an element expands (grows).
Used by
- [mixin]
motion-tokens
Links
duration-collapse
$duration-collapse: 250ms;
Description
A duration used when an element collapses (shrinks).
Used by
- [mixin]
motion-tokens
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
- [mixin]
motion-tokens
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
- [mixin]
motion-tokens
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
- [mixin]
motion-tokens
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
- [mixin]
motion-tokens
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
- [mixin]
motion-tokens
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
- [mixin]
motion-tokens
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
- [mixin]
motion-tokens
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
- [mixin]
motion-tokens
Links
easing-sharp
$easing-sharp: cubic-bezier(0.4, 0, 0.6, 1);
Description
Timing function to quickly accelerate and decelerate
Used by
- [mixin]
motion-tokens
Links
mixins
motion-tokens
@mixin motion-tokens() { ... }
Description
Motion tokens as CSS custom properties.
Parameters
None.
Requires
- [variable]
duration-simple
- [variable]
duration-simple-enter
- [variable]
duration-simple-exit
- [variable]
duration-complex
- [variable]
duration-detailed
- [variable]
duration-open
- [variable]
duration-close
- [variable]
duration-expand
- [variable]
duration-collapse
- [variable]
duration-small
- [variable]
duration-medium-expand
- [variable]
duration-medium-collapse
- [variable]
duration-large-expand
- [variable]
duration-large-collapse
- [variable]
easing-standard
- [variable]
easing-deceleration
- [variable]
easing-acceleration
- [variable]
easing-sharp
- [variable]
duration-scalar
Used by
- [mixin]
root
- [mixin]
design-tokens
- [mixin]
motion
Links
motion
@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
- [mixin]
motion-tokens
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 Name | parameter Description | parameter Type | parameter Default value |
---|---|---|---|
$padding-length | The desired padding length. | String or Number | — none |
$border-width | The desired border width. | String or Number | 0 |
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
- [mixin]
root
- [mixin]
design-tokens
- [mixin]
spacing
spacing
@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
- [mixin]
spacing-tokens
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 Name | parameter Description | parameter Type | parameter 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 Name | parameter Description | parameter Type | parameter Default value |
---|---|---|---|
$family | The font size, which should be a | Font-family | font-family-base |
$height | The line height, which should be a | Line-height | line-height-base |
$size | The font size, which should be a | Font-size | font-size-base |
$size | The font weight, which should be a | Font-size | null |
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
- [mixin]
typeset
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
- [mixin]
typeset
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
- [mixin]
typeset
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
- [mixin]
typeset
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
- [mixin]
typeset
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
- [mixin]
typeset
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
- [mixin]
ui-base
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
- [mixin]
ui-base
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
- [mixin]
ui-base
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
- [mixin]
ui-base
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 Name | parameter Description | parameter Type | parameter 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
- [mixin]
typeset-heading
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
- [mixin]
typeset-heading
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
- [mixin]
typeset-heading
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
- [mixin]
typeset-heading
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
- [mixin]
typeset-heading
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
- [mixin]
typeset-heading
typography-tokens
@mixin typography-tokens() { ... }
Description
Typography tokens as CSS custom properties.
Parameters
None.
Used by
- [mixin]
root
- [mixin]
design-tokens
- [mixin]
typography
typography
@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
- [mixin]
typography-tokens
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
- [variable]
background-color
- [variable]
background-color
- [variable]
background-color
- [variable]
background-color
Utilities
functions
flatten
@function flatten($map, $name: null, $key-separator: -) { ... }
Description
Flatten a nested map.
Parameters
parameter Name | parameter Description | parameter Type | parameter Default value |
---|---|---|---|
$map | The map that should be flattened. The | Map | — none |
$name | The name of the map. Resulting keys will use this as a prefix. | String | null |
$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
- [mixin]
set
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 Name | parameter Description | parameter Type | parameter 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 Name | parameter Description | parameter Type | parameter 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 Name | parameter Description | parameter Type | parameter 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 | 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
- [function]
flatten
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.