HTML/CSS coding guidelines

HTML

Naming conventions
  • Class names, IDs and data attributes should be written with a dash, e.g. .item-form or data-item-id.
  • Class names should be chosen based on their semantic values, not on their appearance or a particular location on the layout, e.g. .error instead of .red, or .main-menu. instead of .top-menu.
Tag usage
  • HTML tags should be used based on their semantic values, not on their visual appearance, e.g. strong may be used to highlight something important, but not just to make the text bold. Tags, that have no semantic value, such as font or br, should not be used at all.
  • The visual appearance of the elements should not be defined using HTML tags, such as font or br, but CSS.

CSS

Syntax
  • Hexadecimal color codes must be written in lower case.
Selectors
  • CSS selectors for structured groups of elements should start with the root element.
<div class="widget">
    <div class="header"></div>
    <div class="body"></div>
</div>
/* correct */
.widget { ... }
.widget .header { ... }
.widget .body a { ... }

/* wrong */
.widget { ... }
.header { ... }
.body a { ... }

/* also wrong */
.widget { ... }
.widget-header { ... }
.widget-body a { ... }
  • Selectors for common inline elements can be written without specifying their location.
.button { ... }
a:visited { ... }
  • Styles, that are specific for some page, should be defined starting from the unique page root element.
/* some special styles for a widget on the trigger monitoring page */
.w.list.trigger-mon .widget .body { ... }

/* different .button styles for forms */
.w.edit .button { ... }
  • Avoid using unnecessary HTML elements in selectors to be less bound to a specific DOM structure.
/* correct */
.w.list .item .status strong { ... }

/* wrong */
.w.list tr.item td.status strong { ... }
Style definition
  • Styles should always be defined in the corresponding CSS files, never in the style attribute.
  • Common styles should be put in default.css, theme-specific styles - in the corresponding theme's CSS file (the only exception is if we need to set some specific user-defined value, e.g. a path to a particular background image, that is stored in the database).
  • Styles should be defined starting from more common to more specific.
/* some common input and button styles */
input { ... }
.button { ... }

/* input and button styles inside of object configuration forms */
.w.edit input { ... }
.w.edit .button { ... }

/* specific styles for the item configuration form */
.w.edit.item-edit input { ... }
.w.edit.item-edit .button { ... }
Style ordering
  • Order side values by top, right, bottom, left.
  • Declare mixins first, then regular properties.
  • Pseudo selectors should come before other selectors.
.my-block {
    @include my-mixin;

    // Positioning
    position: absolute;
    top: 0;
    right: 0;
    bottom: 0;
    left: 0;
    z-index: 10;

    // Box Model
    box-sizing: border-box;
    display: block;
    width: 100px;
    height: 100px;
    padding-top: 10px;
    padding-bottom: 10px;
    margin: 10px;
    overflow: hidden;

    // Typography
    font-family: 'Times New Roman', serif;
    font-size: 1rem;
    font-style: italic;
    font-weight: bold;
    line-height: 1.5;
    color: #000;
    text-align: center;
    text-decoration: underline;
    text-shadow: 0 1px 0 #fff;
    text-transform: uppercase;

    // Accessibility & Interaction
    cursor: pointer;

    // Background & Borders
    background: #aaa;
    border: 10px solid #000;
    box-shadow: 0 0 10px #000;

    // Transitions & Animations
    transition: all 100ms ease;

    &::before { ... }

    &:hover { ... }

    &.my-modifier { ... }

    &.my-element { ... }
}
Class naming
  • Words must be separated by a "-" character. Example: "host-header-right".
  • Icon classes should start with "icon-". Example: "icon-maintenance".