sky-css-lint

Sky CSS Style Guide

Our approach to CSS

Contents

Writing CSS

• Template
• Architecture
• Selectors
• Properties
• Formatting
• Extending and Modifying
• Resources

Linter

• Installation
• Versioning
• Champions

---

Writing CSS

Template

Before diving into the details of CSS coding style, you can find a Sky-conformant .scss template over at git.io/template.

Instantly get started with:

curl -L git.io/template -o _<your-file-name>.scss

Architecture

TODO: General Principles - DRY, OOCSS

Project stylesheets should be structured following closely to the principles of ITCSS, imported in the following order for greater control over re-usability and specificity:

1. Settings - Global configuration and variables.
2. Tools - Mixins and functions.
3. Generic - High-level styles such as resets and normalize.css.
4. Elements - Base HTML styling.
5. Objects - Common non-cosmetic structural design patterns.
6. Components - Specific cosmetic elements of UI.
7. Trumps Utilities - Helpers and overrides.

TODO: Toolkit example

Selectors

It's important we keep code transparent and self-documented when it comes to naming our selectors.

:x: Don't

• Don't use html tags in selectors.
• Don't use IDs (#) in selectors.
• Don't uncessarily nest selectors.
  • Try to keep selectors flat, at the same level of specificity.
  • Avoid going more than 2 levels deep.

:white_check_mark: Do

• Do use classes.

Specificity

By following the steps above (specifically by using classes and limited nesting) conflicts with specificity shouldn't be a problem.

:warning: Never use !important

If you're struggling to ovverride styles, battling specificty, the safest option is to chain the selector to itself. In SCSS we can achieve this by:

/**
 * Doubling up a selector's specificity in SCSS.
 *
 * 1. Outputs as `.c-example.c-example`
 *
 */

.c-example {
  color: #4a4a4a;

  &#{&} { /* [1] */
    text-decoration: none;
  }
}

BEM

TODO

States

• is-
• has-

State prefixes signify that the piece of UI in question is currently styled a certain way because of a state or condition (SMACSS). It tells us that the DOM currently has a temporary, optional, or short-lived style applied to it due to a certain state being invoked.

Namespacing

Following a prefix convention provides better insight into a class' purpose for other developers to work with.

• o- signifies that this class is an Object, and that it may be used in any number of unrelated contexts to the one you can currently see it in. :warning: Making modifications to these types of class could potentially have knock-on effects in a lot of other unrelated places.
• c- signifies that this class is a Component. This is a concrete, implementation-specific piece of UI. All of the changes you make to its styles should be detectable in the context you're currently looking at. Modifying on top of these styles should be safe and have no side effects.
• u- signifies that this class is a Utility class. It has a very specific role (often providing only one declaration) and should not be bound onto or changed. It can be reused and is not tied to any specific piece of UI. You will probably recognise this namespace from libraries and methodologies like SUIT.
• t- signifies that a class is responsible for adding a Theme to a view. It lets us know that UI Components' current cosmetic appearance may be due to the presence of a theme.
• js- signifies that this piece of the DOM has some behaviour acting upon it, and that JavaScript binds onto it to provide that behaviour. If you're not a developer working with JavaScript, leave these well alone.
• qa- signifies that a QA or Test Engineering team is running an automated UI test which needs to find or bind onto these parts of the DOM. Like the JavaScript namespace, this reserves hooks in the DOM for non-CSS purposes.

Properties

Ordering

Properties should be ordered in the following manner (a style similar to Dropbox) to promote readability:

1. Structure

• display, position, margin, padding, width, height, box-sizing, overflow etc.

1. Typography

• font-*, line-height, text-*, letter-spacing etc.

1. Cosmetic

• color, background-*, border-*, animation, transition etc.

1. Native interaction

• appearance, cursor, user-select, pointer-events etc.

1. @-rules

• @include use your previously-defined mixins here.

1. Pseudo-elements

• ::before, ::after etc.

1. Pseudo-classes

• :hover, :focus, :active etc.

1. Nested elements

Definining separately:

1. State classes
2. Modifier classes

Example

.c-example {
  TODO
}

.c-example.is-active {
  TODO
}

.c-example--large {
  TODO
}

Formatting

TODO

Extending and Modifying

:warning: Never use @extend.

TODO

Resources

Reference

• CSS Almanac (CSS-Tricks)
• cssreference.io
• MDN

Guides

• Code Guide
• CSS Guidelines
• idiomatic-css
• OOCSS

Organisation Style Guides

• Airbnb
• Dropbox
• Primer (GitHub)

---

Linter

Installation

Our CSS linter runs on Stylelint, you can install the conguration by running:

$ npm install github:sky-uk/css --save

After installing, we recommend creating a symbolic link in the route of your project to reference the Style Guide's configuration:

$ ln -s node_modules/sky-css-lint/.stylelintrc .stylelintrc

Versioning

The CSS Style Guide follows Semantic Versioning to help manage the impact of releasing new library versions.

Champions

The CSS Style Guide is maintained by the Toolkit Champions.