Docs for CSS structure

Principles

  • BEM (http://getbem.com/introduction/)
  • SMACSS (https://smacss.com/)
  • ITCSS (https://www.xfive.co/blog/itcss-scalable-maintainable-css-architecture/)
  • OOCSS (http://oocss.org/)
  • Atomic Design (http://atomicdesign.bradfrost.com/chapter-2/)

Folder Structure

We are using the structure of ITCSS. A number should be given to each folder.

00-settings
01-tools
02-generic
03-elements
04-objects
05-components
06-utilities

Importing files

  • Do not use the _ before the filename
  • Separate each block with an own import statement
  • Separate each file with comma
  • Do not use the .scss ending
@import "00-settings/settings.colors",
        "00-settings/settings.layout";

@import "01-tools/tools.border",
        "01-tools/tools.get-color";

File Structure

A file can have different sections. The first section is the config area where you can define componened-based settings. Then you give the component the style.

Please use childs and states in the block. Under the block you can describe the variations.

// Config
$button-border-color: blue;

// Component
/// @group Buttons
.c-button {
  cursor: pointer;
  display: inline-block;
  padding: get-spacing-squished(m);
  vertical-align: top;
  -webkit-appearance: none;
  -moz-appearance: none;
  @include border(transparent);
  background: get-color-brand(primary);
  color: get-color(unique, white);
  line-height: 1;
  text-align: center;

  &:hover {

  }

  &__child {
    color: red;
  }

  // States
  &.is-active {
    color: blue
  }
}

/// Modifiers
.c-button--ghost {}
.c-button--boss {}

BEM

Block, Element, Modifier. Always use this naming convention when you name your classes.

// Block
.c-accordion {

  // Trigger
  &__trigger {}

  // Modifier
  &--boss {}
}

Prefix for Separation

// Object
.o-grid {}

// Component
.c-accordion {}

// Utility
.u-hide {}

Using T-Shirt Sizes

If you have hierarchical values, then use the different steps as t-shirt sizes.

$font-size: (
  xs: .6rem,
  s: .8rem,
  m: 1rem,
  l: 1.4rem,
  xl: 1.8rem
) !default;

JS Hooks

Sometimes we need a class for only JS Hooks. It is important that JavaScript does not give the elements a style. For all JS Hooks Classes we use the `js' Prefix.

<div class="c-accordion js-accordion"></div>

State Handling

We separate States from the block. You can remove or add these classes with JS for State handling. Mostly these classes have a prefix like is-.

.c-button {

  &.is-active {

  }
}

Categorizing CSS Rules

We use this concept from SMACSS and categorise our CSS Rules in different sections. Please structure the properties in each block alphabetically.

  • Box
  • Border
  • Background
  • Font
  • Other
.c-button {
  // Box
  padding: 24px;
  position: relative;
  top: 0;

  // Border
  border: 1px solid #000;

  // Background
  background: red;

  // Font
  color: #fff;
  line-height: 1;

  // Other
  transform: scale(1);
}

Separate Colours

Palette Colours

Every colour which you want to use in the project should be added into this palette.

$color-palette: (
  unique: (
    white: #fff,
    black: #000
  ),
  orange: (
    base: #FFCE18
  ),
  gray: (
    light: #C1C2C5,
    base: #98999F,
  )
) !default;

Brand Colours

These Colours are only for the brand specific colours.

$color-brand: (
  primary: get-color(blue),
  primaryGradation: get-color(blue, light),
  secondary: get-color(orange),
  secondaryGradation: get-color(orange, light)
) !default;

Layout Colours

Mostly used for areas like boxes with a background, promoboxes or whisperboxes.

$color-layout: (
  ghost: get-color(unique, white),
  spot: get-color(blue)
) !default;

Semantic Colours

These colours define the semantic of a component, element or whatever. Something like hints, success or error states.

$color-semantic: (
  success: #98C674,
  successGradation: #F0FAEA,
  error: #E07676,
  errorGradation: #FAEAEA
) !default;

Avoid !important and IDs

Please do not use !important or IDs for styling. We prefer classes. An ID should only be used for JS. The exception for !important is in utilities. There it would be possible to use it.

.u-hide {
  display: none !important;
}

Line-Breaks, Whitespaces (One Tab = Two Whitespaces)

.c-button {
  margin: 12px;
  padding: 24px;
}

Use the Function to Get the Colour

// Bad: use hex value of the color in the component
.c-button {
  background: #000;
}

// Perfect: use the function
.c-button {
  background: get-color-brand(primary);
}

Handling Spacing

https://medium.com/eightshapes-llc/space-in-design-systems-188bcbae0d62

Separation in these categories: * Inset * Inline * Stack * Squish * Stretch

Handling Indices

Please do not use an index directly as a property. You must add it to the map and use the get-index() function.

// Bad: z-index in the component
.c-header {
  z-index: 20;
}

// Perfect: using a map for a good overview
$indecies: (
  navbar: 10,
  header: 20
) !default;

.c-header {
  z-index: get-index(header);
}

Alphabetical Order

.c-button {
  left: 0;
  margin: 0;
  padding: 0;
  position: relative;

  color: green;
  font-size: 21px;
  line-height: 1;
}

Don't Use Very Generic or Specific Class Names

// Bad: So specific
.c-button--red {}

// Bad: It can contain everything
.c-button--alternative {}

// Perfect: Super Light Button
.c-button--ghost {}

Do Not Use ShortNames

// Bad: a short name
$fw-light: 300;

// Perfect: someone will know what do you mean
$font-weight-light: 300;

SCSS Only With a Map

If you write a SCSS Map, then you must create a function to get a value from it the easy way.

// Map
$indices: (
  navbar: 10,
  header: 20
) !default;

// Function
@function get-index($key) {
  @if map-has-key($indices, $key) {
    @return map-get($indices, $key);
  }

  @warn "The key #{$key} is not in the map ’$indices’";
  @return null;
}

Atomic Design

We only use this principle for categorising all kinds of components in the front-end: It does not reflect our CSS structure.

atoms/
molecules/
organisms/
templates/
objects/

Storybook

Design Tokens

https://medium.com/@didoo/how-to-manage-your-design-tokens-with-style-dictionary-98c795b938aa

Readable Articles

  • https://medium.com/codyhouse/line-height-crop-a-simple-css-formula-to-remove-top-space-from-your-text-9c3de06d7c6f