Core API
The @wwnds/core package exposes six top-level mixins for setting CSS declarations, as well as a set of customizable variables for theming.
tokens- All foundational design tokens set as CSS custom properties on the:root.reset- The global HTML reset. Forked from the Bootstrap reboot to use the Norton Design System foundations.components- Declarations for every component.helpers- Helper declarations that set a composed style uncoupled from any component.utilities- Utility declarations that set one property per class.complete- The complete design system set in a single global stylesheet.
Theming variables
These variables should be configured in a forwarded stylesheet to ensure the most flexibility.
| Token | Default value | Usage |
|---|---|---|
$primary-family | "teal" | The family used in components that have a default color |
$primary-grade | 60 | The grade that defines the midpoint of the primary color |
$base-family | "navy" | Background, border, or shadow gradients |
$base-grade | null (unset) | The grade that defines the midpoint of the base color |
$disabled-family | "base-color" | Not currently usable, non-interactive |
$disabled-grade | 30 | The grade that defines the midpoint of the disabled color |
$error-family | "red" | Error, danger, or incorrect |
$error-grade | 60 | The grade that defines the midpoint of the error color |
$success-family | "green" | Success, passing, or correct |
$success-grade | 60 | The grade that defines the midpoint of the success color |
$warning-family | "yellow" | Warning or caution |
$warning-grade | 60 | The grade that defines the midpoint of the warning color |
$background-color | white | The main background color |
$text-color | base-color-90 | The main text color |
$text-color-inverse | background-color | A contrasting text color |
$subdued-color | base-color-60 | De-emphasized, muted, or subdued content |
$selection-background-color | null (unset) | The background color of user-selected text |
$selection-text-color | null (unset) | The text color of user-selected text |
$focus-color | blue-50 | The color used when an element has been focused (:focus) |
$focus-halo-inner-color | background-color | The inner color of the focus halo |
$focus-halo-outer-color | focus-color | The outer color of the focus halo |
$radius-base | var(--nds-radius-sm) | The main border radius used for component shapes |
$hd-dpi | 200 | The minimum dots per inch (dpi) of a high-resolution screen |
$hd-dppx | 125 | The minimum dots per pixel unit (dppx) for a high-resolution screen |
$min-xs | 0 | The minimum width for an extra small screen: a handset |
$min-sm | 600px | The minimum width for a small screen: a large handset or small tablet |
$min-md | 960px | The minimum width for a medium screen: a large tablet or small laptop |
$min-lg | 1280px | The minimum width for a large screen: a desktop |
$min-xl | 1920px | The minimum width for an extra large screen: a high-definition device |
$duration-scalar | 1 | A multiplier used for increasing/decreasing all motion speed |
$font-family-sans | var(--nds-font-family-system-sans) | The main sans serif font family |
$font-family-serif | var(--nds-font-family-system-serif) | The main serif font family |
$font-family-mono | var(--nds-font-family-system-mono) | The main monospace font family |
$font-family-base | var(--nds-font-family-sans) | The main font family that will be used throughout your application |
$font-family-headings | var(--nds-font-family-base) | The font family that will be used for all headings |
$font-size-root | 1em | The font size that is used to define 1rem |
$font-size-xs | var(--nds-font-size-12) | An extra small font size |
$font-size-sm | var(--nds-font-size-14) | A small font size |
$font-size-md | var(--nds-font-size-16) | A medium font size |
$font-size-lg | var(--nds-font-size-18) | A large font size |
$font-size-h1 | var(--nds-font-size-32) | The font size used for the highest heading level |
$font-size-h2 | var(--nds-font-size-24) | The font size used for second-level headings |
$font-size-h3 | var(--nds-font-size-20) | The font size used for third-level headings |
$font-size-h4 | var(--nds-font-size-18) | The font size used for fourth-level headings |
$font-size-h5 | var(--nds-font-size-16) | The font size used for fifth-level headings |
$font-size-h6 | var(--nds-font-size-14) | The font size used for sixth-level headings |
$font-size-base | var(--nds-font-size-md) | The font size used on the body and to set most text |
$font-weight-base | var(--nds-font-weight-regular) | The font weight used for body copy |
$font-weight-headings | var(--nds-font-weight-bold) | The font weight used for headings |
Tokens
The tokens mixin sets the foundations that contain design tokens as global CSS custom properties on the :root element.
You will almost always want to set this as a global stylesheet, as most component styles use the CSS custom properties in their styling.
@use '@wwnds/core';
@include core.tokens;
Reset
The reset mixin is meant to be used to create a global stylesheet that ensures that all HTML elements are rendered consistently across browsers.
@use '@wwnds/core';
@include core.reset;
Components
The component API provides three levels of usage with different levels of customization to suit your needs.
All components
All component declarations can be set at once in one mixin.
@use '@wwnds/core';
@include core.components;
// resulting CSS will contain declarations for all components
Individual components
Each individual component exposes a style mixin that is namespaced with the component's name on the top-level API (e.g., button-style).
@use '@wwnds/core';
@include core.button-style;
// resulting CSS will contain only button declarations
Fully modular mixins
Each component composes its styles via mixins. Generally, these are applied to the component's anatomy with BEM selectors but you can use them with your own selectors.
@use '@wwnds/core';
.custom-button {
@include core.button-base;
@include core.button-solid;
// override or add your own styles
// border: 2px solid var(--nds-button-color-80);
}
.custom-button__icon {
@include core.button-icon;
}
// resulting CSS will contain only the above two declarations
Helpers
Helpers are composed declarations that help with common styling needs that are not connected to any component. Unlike utilities, helpers always set multiple properties per declaration or compose styles together to meet a specific need.
Helpers are disabled by default and must be turned on by setting $enable-helpers to true.
@use '@wwnds/core' with (
$enable-helpers: true,
);
@include core.helpers;
Utilities
Utilities are declarations that set a single property and are turned off by default.
To enable them, they must be turned on with the $enable-utilities map.
Note that the utility API is deliberately minimal and is not suited for production usage. If you would like to use a more utility-focused approach, we like Tailwind CSS.
@use '@wwnds/core' with (
$enable-utilities: ('color', 'spacing'),
);
@include core.utilities;
Complete
The complete mixin provides a single way to opt into every declaration.
Note that this can also be accessed directly by using @wwnds/core/full.
@use '@wwnds/core';
@include core.complete;