1.4. CSS and Styles

The CSS Coding conventions are inspired by Stoyan Stefanov’s CSS Coding Conventions.

See Idiomatic CSS for more details.

Many of them are automatically checked using scame which is now included in the CSS Coding Convention Checker. Please report any problems that you have with running paver lint or if some errors are not identified by paver lint.

1.4.1. CSS Syntax Elements

When describing the CSS rules, we will use the following terminology.

CSS Selector Graphic

1.4.2. General

  • Use C++ comments style (/* comment here */) and not C style (//) as they are not supported by CSS2 and there are problems in some browsers. Also, on LESS C style comments (//) are ignored in the final result.

  • Avoid using short CSS notation. They are harder to read and the diff generated by changing short notations is less explicit.

  • Avoid using IDs when defining styles as they discourage style reuse… and then you take the risk of repeating yourself.

  • Put general styles in ‘’styles.css’’ and don’t put page specific styles.

  • Page specific styles can be included using a different file.

  • Use lowercase characters for HEX RGB color codes. (eg. Good #f9a0c5 - Bad #F9A0C5)

  • Don’t use color names or RGBA, just HEX code.

  • Use 2 space indentation. We use 2 and not 4 as with Tailwind you end up with a lot of nesting. With all the levels of nesting in Tailwind, the end result looks similar to 4 space indentation.

  • End every property-value with a semi-colon.

  • Separate each rule by a blank line.

  • Put unrelated rules in different files.

1.4.3. CSS Class naming

  • The most important thing to have in mind is the content nature of the HTML document, not its presentation. Selector names should describe the content semantic and not how it looks.

  • Don’t use abbreviation. Use ‘header’ instead of ‘hdr’ or ‘head’.

  • Avoid presentation-specific words in the name, like blue, text-gray, or light-box.

  • Add namespaces using a dash (-) as a separator.

  • Distinct words in the class name are separated by a dash.

  • Names are lowercase.

  • Use js-CLASS-NAME notation for classes which are used to support the JS application.

    These classes must not have any CSS style attached to them.

    When changing them in the markup, review the JS application code.

  • Use test-CLASS-NAME notation for classes which are used only to help the testing process.

    No CSS style should be defined on them.

    No JS application functionality should be associated with them, other than the testing code.

    The testing code should use only CSS selectors defined based on these test CSS classes.

    No other class or tag name should be used. BEM Notation

BEM is an abbreviation of the key elements of the methodology — Block, Element and Modifier.

When naming CSS classes, try to use this convention.

Elements are delimited with two (2) underscores _ _.

Modifiers are delimited by two (2) hyphens - -.

  • Block

    Standalone entity that is meaningful on its own. The sole root of the component.

    Examples: header, container, menu, btn, input.

  • Element

    A part of a block that has no standalone meaning and is semantically tied to its block.

    Examples: menu__item, list__item, header__title.

  • Modifier

    A flag on a block or element. Use them to change appearance or behavior.

    Examples: disabled, highlighted, checked, fixed, size big, primary.

    Block modifier: input--big, btn--primary

    Element modifier: header__title--highlighted

1.4.4. Rules definition

  • The property will be followed by colon and then a space.

  • Put each selector on a single line and separate them using commas. This makes it easier to see each selector when using multiple selectors and also to manage the diff.

  • The opening bracket should be on the same line as the last selector.

  • The closing bracket should be on its own line and indented like the selector.

1.4.5. Layout and Typography separation

  • Don’t put typography properties in the same class as layout properties

  • The idea it that when you change or remove a typographic rule, the layout will not be affected.

  • Use this with moderation, sometimes it is ok to set a margin or padding for h1 or p tags… but don’t abuse this.


.product-name {
  font-style: underline;
  color: #f00;

.highlighted-box {
  float: center;
  width: 30px;
  background-color: #07f;


.product-name {
  color: red;
  float: center;
  width: 30px;
  background-color: blue;

1.4.6. Tailwind and PostCSS

Tailwind CSS is a utility-first, highly customizable, low-level CSS framework that contains the building blocks for building custom designs.

Follow the Tailwind documentation as the primary rule for writing CSS. When defining our own classes follow BEM notation without using abbreviations.

It’s ok to use the Tailwind abberviated class, just make sure our custom classes are not abbreviated.

We also use PostCSS to improve the way we manage the CSS:

  • Don’t have empty lines between Tailwind CSS classes as it will fail on Windows.

  • Use imports to break CSS into multiple files for development.

  • Used as general minifier and having a single production CSS file.


@tailwind base;
@tailwind components;
@tailwind utilities;

@layer components {
  .button {

  .button--primary {

  .button--primary:hover {