Code Conventions

The design system favors clarity over succinctness. This means the design system may be verbose, but it should deliver clarity, predictability, and legibility in exchange.

Coding style can be really personal and everyone has their own opinions and preferences. But when we work as a team on a shared codebase it’s invaluable to agree to some basic rules. The CSS in RTS Design System should be written consistently no matter who wrote it.

Selector use

We favor classes over IDs or type selectors. Using ID selectors can lead to specificity wars requiring ever more powerful selectors to override previous styling and type selectors are very broad that can cause some inherit problems to other elements.

Avoid qualifying classes with type selectors. It slows down performance and makes classes less portable. E.g. .classname is better than div.classname.

Nesting

We use SCSS as a pre-processor. Nested rules are converted into descendent selectors in the generated style sheet. The deeper the nesting, the more complex and specific the final selector will be. Don’t nest rules unless necessary for context and specificity, and don’t nest rules just to group them together.

All the declarations for the parent element should come before the nested rules. Include a blank line before each nested rule to separate it from the rule or declaration above it.

Don’t do this

.component {
  display: inline-block;

  &-container {
    background-color: $color-white;

    &__header {
      padding: $space-unit;
    }
  }  
}

Unnecessary specificity and makes classes hard to find.

Do this

.component {
  display: inline-block;
}

  .component-container {
    background-color: $color-white;
  }

    .component-container__header {
      padding: $space-unit;
    }

Clean and simple.

Units

We use rems as the base unit. Try to use the spacing classes when possible, otherwise use the rem() function to add a specific number of pixels. E.g. rem(15) for 15px. Use percentages for fluid-width elements. Use unitless line-height in conjunction with font-size; it acts as a multiplier of font size. E.g. line-height: 1.5.

Naming conventions

Naming conventions are an important aspect of any design system. This allows us to keep our classes flat, avoid conflicts, provide clarity, and improve legibility.

It consists of two required parts.

  • Class prefix
  • BEM Syntax

Class Prefixes

We follow an ITCSS architecture, each class name has a prefix which gives information about what the class is doing.

Prefix Description
.o- (Object) Cosmetic-free design patterns that are very dangerous to change because they are often used in unrelated contexts. E.g. the OOCSS Media Object.
.c- (Component) Implementation-specific pieces of UI. CSS is safe to change because it is isolated to the specific component.
.u- (Utility) Highly specific, highly reusable, usually single purpose, and have high specificity.
.is- (State) These classes are typically added and removed through JavaScript or on the server to show specific states.

Following the namespace and prefix is a name conforming to BEM syntax.

Put all together, a CSS class can be broken down to these key parts: [PREFIX]-[BLOCK]__[ELEMENT]--[MODIFIER].

  • Block is a standalone entity that is meaningful on its own. For example: .c-card, .c-btn
  • Element is a part of a block that has no standalone meaning and is semantically tied to its block, such as .c-card__title
  • Modifier is a flag on a block or element and is used to change appearance or behavior. For example: .c-btn--primary, .c-table--compact, .o-stack--xs.

File structure

Following the ITCSS architecture together with code components our file structure looks like this:

assets/
|____scss
| |____01-settings (Global settings like font, colors definitions, etc.)
| | |_____settings.[NAME].scss
| |____02-tools (Globally used mixins and functions.)
| | |_____tools.[NAME].scss
| |____03-generic (Reset and normalize styles)
| | |_____generic.[NAME].scss
| |____04-objects (Undecorated design patterns, E.g. media object known from OOCSS)
| | |_____objects.[NAME].scss
| |____06-utilities (Helper classes with ability to override anything)
| | |_____utilities.[NAME].scss
| |____docs (Rules to style the design system website)
| | |_____fractal.[NAME].scss
| |____global.scss (All styles)
| |____docs.scss (Styles for the Design System site)
components/
|____code-components/
| |____component-name/
| | |____component-name.hbs (Component template)
| | |_____component-name.scss (Component styles)
| | |____component-name.config.yml (Component config and context)
|____pages/
| |____page-name/
| | |____page-name.hbs (Page template)
| | |____page-name.config.yml (Page config and context)
docs/
|____documentation/ (General Documentation)
| |____*/
|____components/ (Usage documentation and code examples)
| |____*/
|____pages/ (Group of pages by section)
Design System