@aurodesignsystem/webcorestylesheets

WC Style Sheets

WC Style Sheets(WCSS) is a responsive, mobile-first collection of styles and tools designed to make it quick and simple for developers to create web experiences using the Auro Design Language.

What's included

This repository is a library of core level styles, functions, and mixins that can be used for consistent front-end UI development. This will include full descriptions of CSS selectors, mixins and any other supporting functions or tools.

Documentation

Please see the documentation site for all information related to WC Style Sheets.

Install

$ npm i @aurodesignsystem/webcorestylesheets

Using the files in Sass

There are no core files to import, rather WCSS is an à la carte solution allowing for users to import what they want and when they want it. In most cases you can simply import the Sass file as illustrated below:

@import "~@aurodesignsystem/webcorestylesheets/src/ ... "

Tokens Dependency

WCSS uses Sass and has a dependency on the SCSSVariables.scss file from Design Tokens package. This reference needs to be imported before any reference of a WCSS partial.

@import "~@aurodesignsystem/design-tokens/dist/tokens/SCSSVariables";
@import "~@aurodesignsystem/webcorestylesheets/src/ ... ";

Install the essentials

While WCSS is an à la carte solution, there are things that should be considered when adding WCSS to your project. For example, if the project has little or no legacy CSS, it is suggested to set the following foundation:

// baseline design tokens as Sass variables
@import "~@aurodesignsystem/design-tokens/src/tokens/SCSSVariables";

// globally add the mixins so that any future reference will be addressed
@import '~@aurodesignsystem/design-tokens/src/tokens/breakpoints';

// it's typically best practice to load the @font-face rules prior to any reference of the custom web fonts
@import '~@aurodesignsystem/design-tokens/src/tokens/fonts';

// set a baseline browser normalize
@import '~@aurodesignsystem/design-tokens/src/tokens/normalize';

// essentials setup baseline primitive selectors for any UI development
@import '~@aurodesignsystem/design-tokens/src/tokens/essentials';

For an example of setting up a master file that imports all of WCSS's resources, see the styleTest.scss in the project.

Web font dependency

WC style sheets has full support for Auro's web fonts, ASCircular. When importing ~@aurodesignsystem/design-tokens/dist/tokens/fonts this will import the (3) Auro web fonts that are loaded from our CDN for light, medium, and book weights.

Any references to ASCircularWeb-Book, ASCircularWeb-Medium, or ASCircularWeb-Light would be considered redundant and you should remove those legacy references.

Any references to ASCircularWeb-Bold or any other ASCircularWeb- style font family is not supported and these references are considered fully deprecated.

Pre-processed bundled resources

At a limited scale, some files have been pre-processed to CSS so that it can be delivered via CDN and used in environments where this rendered resource is required.

API Note: First supporting version v2.9.0

resource	CDN URL
essentials.scss fonts.scss	https://cdn.jsdelivr.net/npm/@aurodesignsystem/webcorestylesheets@latest/dist/bundled/essentials.css

Development

To develop against WCSS run both npm run watch and npm run serve in separate terminals.

The watch command will run a Sass linter, process a test file from Sass to CSS and run a post CSS linter. This will ensure the quality of all new Sass added to the repo.

If additional selectors or scenarios are needed, please update the ./scripts/testBuild.scss file to test your code.

Running the serve command will open the Sassdoc view. Please review all changes as Sassdoc produces all documentation.

WCSS fully supports idiomatic CSS, be sure to review the auro docs site for more information.

Changelog

5.0.0 (2023-09-25)

Features

• remove all deprecated references #169 (711d729)
• update to use CSS variables with fallback #134 (9546be4)

Performance Improvements

• deps: update repo to support Node 18 #155 (c208bad)
• tokens: update to design tokens 4.x #134 (8f17359)
• update all references from auro- to ds- #169 (57831ef)
• update insetUtility to maintain current support (a136b9d)
• update package config #171 (4ca4e7d)

BREAKING CHANGES

• This commit updates the .npmignore package config to reduce the scope of the packaged files and directories

This commit also removes the necessity of copying all the src files to a dist dir and instead allows the src dir to be added to the package. Consumers will have to update dir references from ./dist to ./src in most import cases.

Processed files are still located in the ./dist dir.

Changes to be committed: modified: .github/workflows/testPublish.yml modified: .npmignore modified: README.md modified: package.json

• This commit removes the legacy insetUtility mixin and replaces it with a static output of the generated legacy values from the previous version of WCSS and design tokens.

Users will not get a failure when importing the file reference src/utilityMixins/_insetUtility.scss but instead of the mixin generating a subset of selectors, all the static selectors will be added to the project's CSS output.

This legacy feature has also been designated as DEPRECATED and should be deleted with the next MAJOR release.

• This commit will require all consumers to update their app to use @aurodesignsystem/design-tokens v4.x

All references in documentation and code has been updated from auro- to ds- per the new design token specification.

Changes to be committed: modified: FAQ.md modified: README.md modified: demo/3col.html modified: packageScripts/postinstall.js modified: src/* modified: tests/*

• tokens: This commit updates the repo's dependency on the newly released Auro Design Tokens 4.x.

Changes to be committed: modified: package-lock.json modified: package.json