@wwnds/core

A Sass implementation of the design system's foundations and styling for all components.

Usage

All usage guidance is provided in the developer guide.

Developing

The core library makes considerable use of Sass modules to structure its stylesheets and enable theming through the @forward...with syntax.

Conventions

We follow a handful of conventions to make our stylesheets more manageable and readable. All contributors should strive to follow these conventions.

1. Declarations must be wrapped in a mixin. This ensures that declarations never leak on @forward or @use.
2. Design token defaults should be expressed as abstract Sass variables. These aren't compiled and won't result in any CSS output.
   • For example: $duration-simple: 100ms;
3. Sass variable tokens should be used to set the token as a CSS custom property prefixed with --nds-.
   • For example: --nds-duration-simple: #{$duration-simple};.
4. System tokens (static properties associated with a foundation):
   • should be declared on the :root element. System tokens are foundational, and should be used globally.
   • should not be customizable. In other words, they should not include the !default flag.
5. Role tokens (themeable properties associated with a foundation):
   • must be customizable with the !default flag. This makes it possible to override the value on @forward or @use.
   • should be named for their property or their role. If a token sets a single property, name it for its property. If it's used in a more abstract way, name it for what it is trying to accomplish (its role).
     • Property example: $background-color if it's used to set the background-color property.
     • Role example: $padding-y if it's used for both padding-top and padding-bottom.
6. Component tokens (properties associated with a component):
   • should be set in a standalone tokens.scss file adjacent to the component's styles.
   • should be customizable with the !default flag.
   • should default to existing role tokens whenever possible.
     • Good 👍: $background-color: var(--nds-background-color) !default; (role token)
     • Okay 👍: $border-color: var(--nds-base-color-40) !default; (system token when no role token exists)
     • Bad 👎: $background-color: var(--nds-white) !default; (system token when a role token exists)
     • Worse 👎: $background-color: #fff !default; (raw value)
   • should be named for their property or their role. If a token sets a single property, name it for its property. If it's used in a more abstract way, name it for what it is trying to accomplish (its role).
     • Property example: $background-color if it's used to set the background-color property.
     • Role example: $padding-y if it's used for both padding-top and padding-bottom.
   • should not be prefixed. Component tokens are prefixed with the component's name when forwarded by the main entry point so including the prefix would result in a doubly-prefixed name (e.g., $tooltip-tooltip-border-radius).