Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
95 lines (60 loc) · 3.16 KB

CONTRIBUTING.md

File metadata and controls

95 lines (60 loc) · 3.16 KB

Contributing to Design System Styles

These contribution guidelines extend the general contribution guidelines, where you can find instructions on how to set up the repository for contributing.

Design principles

Sass

General styling rules are suggested through linting with stylelint. At the moment, these rules are not enforced or applied/fixed automatically. This might change in the future.

Stylesheets define their own dependencies and use namespaces for variables, functions and mixins. Using global scss variables is discouraged.

// DO
@use 'variables/buttons'; // Creates "buttons" namespace by convention

.btn {
  background: buttons.$background;
}

// DON'T
@import 'variables/buttons'; // Global import, leads to duplicate output

.btn {
  background: $background; // No namespace
}

This ensures independent component styles that can be reused. The mechanics of the @use keyword also ensures that no file is loaded twice when generating a CSS bundle, even if it is used more than once.

Components

Component file names are lower- and kebab-cased (floating-label.scss) and don't start with an underscore (_floatingLabel.scss) as they are not partial scss files - they can be compiled standalone and produce valid, usable CSS.

Dependencies/licensing

Licenses of third party packages that are bundled with the output need to be included in the output and delivered with the output code.

Margins

Block level content elements (headings, paragraphs, images, lists, ...; html tags without any classes or context) should use the following margin system: define block margins but reset the margin start for the first child and the margin end for the last child. The rules for first and last child should have low specificity.

p { margin-block: 1rem; :where(:first-child) { margin-block-start: 0; } :where(:last-child) {
margin-block-end: 0; } }

Bundling the styles

Run the following command to lint all scss files, create a dist folder and build the output CSS files using gulp. This command also copies the entire Scss source files into the dist folder, making them available for developers.

# Production build
npm run build

# Rebuild on change
npm run start

Integration tests

Automated integration tests are not yet available for the Design System Styles.

Linting

This project is using Stylelint with a configuration based on the Sass Guidelines, properties are sorted according to the SMACSS sort order.

# Console output only
npm run lint

# Fix all auto-fixable issues
npm run lint:fix

Formatting

Prettier is used to format .scss files with this configuration. If your editor allows for it, we recommend to enable format on save for .scss files.

npm run format

Other commands

Common tasks are present as npm scripts:

# Delete the dist folder
npm run clean

Icons

Please refer to the icon generation guide to learn how to generate a new icon variables file.