Code Style Guide - MattMcAdams/stratus GitHub Wiki

This style guide is primarily enforced through stylelint. If you notice any discrepancies between this document and the stylelint configuration, please let me know by opening an issue. Thanks!

1.0 Introduction

1.1 Preprocessor

All CSS code in this project should be written using a Sass preprocessor (with the Dart implementation) with SCSS syntax.

1.2 Tabs and spaces

For indentation and formatting of the code, we use spaces and NOT tabs. Please set up your code editor with these settings:

  • No tabs
  • Tab size = 2
  • indent size = 2

Spaces are the only way to guarantee code renders the same in any person’s environment.

2.0 Formatting

Before we discuss how we write our rulesets, let’s first familiarise ourselves with the relevant terminology:

[selector] {
  [<--declaration--->]
  [property]: [value];
}

Here are some formatting guidelines:

  • A space before the opening brace {
  • The opening brace { on the same line as the last selector
  • The first declaration on a new line after the opening brace {
  • Properties and values always on the same line
  • A space after the property–value delimiting colon :
  • Each declaration on its own new line (line breaks between declarations)
  • Each function or mixin parameter on its own new line (line breaks between parameters)
  • Each selector on its own new line (line breaks between selectors)
  • The closing brace } on its own new line
  • Each declaration indented by two (2) spaces
  • Use shorthand hex values where possible #ccc
  • Hex values must be written lower case #0366d6
  • Decimal numbers must have a leading zero 0.5
  • Pseudo elements must use the double colon notation ::
.foo,
.bar {
  display: block;
  background-color: #fff;
  width: 0.2rem
}

Avoid specifying units for zero values:

margin: 0; /* Good */
margin: 0px; /* No good */

3.0 Naming conventions

3.1 Configuration

  • Any option for configuration must be made using a config variable at the top of the file.
  • These variables should reference a variable in the global configuration file.
  • These variables should all have the config- prefix.
  • Every configuration variable must have the !default flag.
$config-sp-unit: config.$space-unit-size !default;

3.2 Functions & Mixins

There are exceptions, but generally functions and mixins should be prefixed with the module they belong to.

3.3 Variables

  • Parameters in a function or mixin should be unprefixed, short, and self explanatory.
  • Variables inside functions should be prefixed with an underscore _ to indicate they are private to that function or mixin.

4.0 Organization

4.1 Imports

At the top of the file, all imported modules should be added with @use with the following order:

  1. Built in Sass modules
  2. Project modules
  3. Configuration file
@use 'sass:math';
@use '../core/validation' as v;
@use '../core/error';
@use '../core' as stratus;
@use '../config';

4.2 Configuration

Directly below imports should be any configuration variables used in the file

4.3 Private functions & mixins

Any functions or mixins used by the project that are not meant to be used by the end user should be placed here.

NOTEDespite these functions being private, do NOT prefix them with an underscore. This will make them private to the rest of the project. To hide these functions from the end user, edit _index.scss in the root directory and hide the member in the @forward statement

@forward 'src/foo' hide bar;

4.4 Public functions & mixins

Below private members are the rest of the module's code. Each function or mixin should be preceded by it's documentation block.