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>
Copy
✔ Copied
/* correct */
       .widget { ... }
       .widget .header { ... }
       .widget .body a { ... }
       
       /* wrong */
       .widget { ... }
       .header { ... }
       .body a { ... }
       
       /* also wrong */
       .widget { ... }
       .widget-header { ... }
       .widget-body a { ... }
Copy
✔ Copied
  • Selectors for common inline elements can be written without specifying their location.
.button { ... }
       a:visited { ... }
Copy
✔ Copied
  • 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 { ... }
Copy
✔ Copied
  • 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 { ... }
Copy
✔ Copied
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 { ... }
Copy
✔ Copied
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 { ... }
       }
Copy
✔ Copied
Class naming
  • Words must be separated by a "-" character. Example: "host-header-right".
  • Icon classes should start with "icon-". Example: "icon-maintenance".
To toggle search highlight, press Ctrl+Alt+H
Have an improvement suggestion for this page? Select the text that could be improved and press Ctrl+Enter to send it to the editors.