Documentation
Table of Contents
HTML/CSS coding guidelines
HTML
Naming conventions
- Class names, IDs and data attributes should be written with a dash, e.g.
.item-formordata-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.
.errorinstead 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.
strongmay be used to highlight something important, but not just to make the text bold. Tags, that have no semantic value, such asfontorbr, should not be used at all. - The visual appearance of the elements should not be defined using HTML tags, such as
fontorbr, 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.
/* 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.
- 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
styleattribute. - 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".