Code Style and Conventions

CSS

Units

• Generally 'rem' is used
• Exceptions:
  • px for: border-width, border-radius, box-shadow, outline-width (these do not scale well, and don't need to)
  • px for media-queries
  • Relative units (%, vw, etc.) can be used where they make sense (e.g. layout)
  • For line-heights, unit-less values are used (e.g. 1, 1.2)

When defining rem values within KoliBri, always use the provided Sass function:

@import '@shared/mixins';
font-size: rem(16);

This ensures that the passed value always equals to the same number in pixels for default browser settings.

When a project uses a different root font-size than 16px, this can be configured using a CSS custom property and will be taken into account:

html {
  font-size: 65.5%; /* Equals 10px */
  --kolibri-root-font-size: 10;
}

Background reading and code samples

BEM

For CSS Selectors, we follow the BEM pattern.

When writing stylesheets, always follow the order: Block, Elements, Modifiers and utilize SCSS nesting:

.kol-mycomponent {
  &--primary {}

  &--card {}

  &__close-button {
    &--hidden-label {}
  }
}

When you need to combine modifiers, there are two approaches.
In the following example, we wan't a different styling for the Close-Button-Element when the component itself has the card-Modifier:

Approach 1 - Use CSS Custom Properties (✨ Preferred):

.kol-mycomponent {
  --button-color: black;

  &--card {
    --button-color: lightgray;
  }

  &__close-button {
    color: var(--button-color);
  }
}

Approach 2 - Combine selectors:

.kol-mycomponent {
  $root: &;
  
  &__close-button {
    @at-root #{$root}--card & {
      align-self: flex-end;
    }
  }
}

Avoid deep nesting and stick to the order (Block, Elements, Modifiers) where possible.
Negative example (⛔️ Avoid!):

.kol-mycomponent {
  &--card {
    .kol-mycomponent__close-button {
        align-self: flex-end;
      }
  }
}

Exceptions

Global utility classes such as visually-hidden may be used and don't need to follow the BEM convention.

Tip

Use the Sass Playground to fiddle with tricky SCSS-Selectors.