Skip to main content

Writing CSS

Once your stylesheets have been set up how you want them, you can start writing CSS with the Norton Design System.

Theming​

The Norton Design System's CSS is fully themeable through the use of Sass variables. The variables that capture the foundational style elements constitute the main interface for theming an application. Refer to the variables table to learn more about these customizable variables.

The following practices will help you get the most out of the Norton Design System's CSS.

Use CSS custom properties, not Sass variables​

CSS custom properties are live variables that can be modified via JavaScript and will always reference the current value of the token. Sass variables, on the other hand, are hard-coded into the stylesheet when the CSS is compiled and cannot be changed after that point.

@use '@wwnds/core';

// 👍 Good: use the CSS custom property
.foo {
	font-family: var(--nds-font-family-serif);
}

// 👎 Bad: use the Sass variable
.foo {
	font-family: core.$font-family-serif;
}

Use role tokens, not system tokens​

Using role tokens will facilitate theming in your application since role tokens can be customized, whereas system tokens cannot. Refer to the design token types inheritance outline for more clarification of this convention.

@use '@wwnds/core';

// ✨ Best: modify a known role token at this scope and then use it
// (not always possible)
.foo {
	--nds-background-color: var(--nds-base-color-20);

	background-color: var(--nds-background-color);
}

// 👍 Good: use the role token
.foo {
	background-color: var(--nds-base-color-20);
}

// 👎 Bad: use the system token
.foo {
	background-color: var(--nds-navy-20);
}

Override token values instead of property values whenever possible​

Some tokens, like text-color and background-color are set globally and are designed to use the CSS cascade to style all elements. We encourage you to embrace the cascade—a fundamental feature of CSS—modifying token values at specific scopes to accomplish your goals instead of modifying properties directly.

@use '@wwnds/core';

// 👍 Good: override the token value and then use it
.foo {
	--nds-text-color: var(--nds-base-color-10);
	--nds-background-color: var(--nds-primary-color-80);

	color: var(--nds-text-color);
	background-color: var(--nds-background-color);
}

// Okay: override the property value
.foo {
	color: var(--nds-base-color-10);
	background-color: var(--nds-primary-color-80);
}

Compose your own CSS custom properties out of existing tokens​

We deliberately provide only a small set of opinionated design tokens but recognize that you may have application-specific styles that would make sense as tokens.

@use '@wwnds/core';

// 👍 Good: declare and use your own reusable custom properties out of existing tokens
:root {
	--brand-gradient: linear-gradient(
		var(--nds-primary-color),
		var(--nds-primary-color-90),
	);
}

Use Sass modules​

When using the Sass directly, avoid @import, favoring @forward and @use.

// ✨ Best: forward a configured version of the core library
@forward '@wwnds/core' with (
	// configured Sass variables
	$radius-base: var(--nds-radius-xl),
);

// 👍 Good: use the core library directly
@use '@wwnds/core';

// 👎 Bad: use the deprecated import syntax
@import '@wwnds/core/full';