CSS Coding Style

Note: This page is a work-in-progress. Feedback and suggested improvements are welcome. Please join the discussion on moodle.org or use the page comments.

The Moodle CSS coding style (a Work in Progress, see MDLSITE-1796 for the effort to make it official)

Overview

Scope

This document describes style guidelines for developers working on or with Moodle code. It talks purely about the mechanics of code layout and the choices we have made for Moodle.

Goals

Consistent coding style is important in any development project, and particularly when many developers are involved. A standard style helps to ensure that the code is easier to read and understand, which helps overall quality.

Abstract goals we strive for:

• simplicity
• readability
• tool friendliness

File naming

Within plugins, CSS files are normally named styles.css.

In the theme, files can be named according to the theme designer's wishes but should:

• use lowercase letters only
• be as short as possible
• be descriptive
• be placed in the folder style/ for CSS files, or in less/ for LESS files.

Blocks

• Each selector should be on its own line. If there is a comma in a selector list, follow it with a line break.
• Property-value pairs should be on their own line, with four spaces of indentation and an ending semicolon.
• The closing brace should use the same level of indentation as the opening selector.
• Leave one line between blocks.

Correct

@media only screen and (min-width: 768px) {

   .selector-one,
   .selector-two {
       color: #fff;
       background-color: #000;
   }

}

Incorrect

.selector_one, .selector_two { color: #fff; background-color: #000; }

Selectors

• Always use lower case and underscores or hyphens. Hyphens are preferred.
• Names should be made of simple English words.
• Verbosity is encouraged: names should be as illustrative as is practical to enhance understanding.
• Use semantic names: names tell what this is instead of what should it look like.
• Avoid using IDs. They are far more difficult to maintain and override.
• Do not over-qualify your rules by combining a tagname with a class or ID.

Correct

.selector_name {

   color: #fff;

}

.selector-name {

   color: #fff;

}

Incorrect

div#selName {

   color: #fff;

}

.Color-White {

   color: #fff;

}

Properties and values

• Should be separated by a colon and a single space, do not minify them.
• Should be lowercase, except for font names and vendor-specific properties.
• For color codes, lowercase is preferred and a shorthand whenever possible.
• For color codes, if you use HSLA or RGBA, always provide a hex fallback.
• Use shorthand (except when overriding styles) for background, border, font, list-style, margin, and padding values.
• Do not use !important. If there is no alternative something is wrong with the CSS you are trying to override.
• Prefixed vendor-specific properties pairs should appear directly before the generic property they refer to.
• Indent vendor prefixed declarations so that their values are aligned

Correct

.selector {

   color: #fff;
   -webkit-border-radius: 4px;
      -moz-border-radius: 4px;
           border-radius: 4px;

}

.selector {

   margin-top: 1px;
   color: #f90;
   color: hsla(0, 0%, 100%, 1);

}

Incorrect

#selector {

   color: hsla(0, 0%, 100%, 1);
   -webkit-border-radius: 4px;
   -moz-border-radius: 4px;
   border-radius: 4px;

}

1. selector {

   margin-top:1px;
   color :#ff9900 !important;

}

Units

• Prefer the usage of em over px.
• Do not use the units pt or rem. MDL-39934
• Do not declare the unit when the value is 0.

Correct

.something {

   margin-top: 0;
   font-size: 1.25em;

}

Incorrect

.something {

   margin-top: 0px;
   font-size: 1.25rem;

}

Documentation and comments

Following the general Coding style, comments should start with a capital letter and end with a period.

A block-style comment at the top of the CSS file should explain the purpose of the rules in the file. /**

* File base.css.
* Contains base styles for theme basic.
*/

Block-style comments can also be used to denote a section in a CSS file where all rules pertain to a specific component, view, or functionality: /**

* SCORM Navigation Sidebar.
*/

Use single-line comments to provide more information to other developers about a single rule or small subset of rules: /* Required because YUI resets add a black border to all tables */

Progressive enhancement

• Fallbacks should always be provided. For example, provide a background color fallback to background images and gradients.
• Use vendor prefixes only when the supported browser in question does not support the unprefixed property.
• The standard property should come after the vendor-prefixed property.

.selector {

   background-color: #444; /* Fallback for browsers that don't support gradients. */
   filter: progid:DXImageTransform.Microsoft.gradient(startColorStr='#444', EndColorStr='#999'); /* IE6-IE9. */
   background-image: -webkit-gradient(linear, left top, left bottom, from(#444), to(#999)); /* Safari 4+, Chrome. */
   background-image: -webkit-linear-gradient(top, #444, #999); /* Chrome 10+, Safari 5.1+, iOS 5+. */
   background-image: -moz-linear-gradient(top, #444, #999); /* Firefox 3.6. */
   background-image: -ms-linear-gradient(top, #444, #999); /* IE10. */
   background-image: -o-linear-gradient(top, #444, #999); /* Opera 11.10+. */
   background-image: linear-gradient(top, #444, #999); /* W3C Standard. */

}

Browser Hacks

• Do not use any browser-specific hacks. Moodle provides a more appropriate way to write browser-specific CSS using classes that are added to the body element. For example:

.ie7 .forum-post {

   min-height: 1px;

}

• It is not necessary to include hacks for versions of browsers that Moodle core does not provide support for (e.g. IE6 in Moodle 2, except legacy theme).

Plugins

In plugins, the file names can be:

• styles.css (Recommended)
• styles_<theme name>.css (Not recommended, reserved to 3rd party plugins)

Barebones

Plugins should define the strict minimum, no text sizes, colours, etc ... those should belong to the theme and not be hardcoded in plugins to allow for easy theming. Of course, this requires Moodle core to provide re-usable classes to style the elements. As Moodle 2.7 has made Bootstrap 2 by default we can start using their classes, but we should make sure that there is a sensible fallback for themes not extending bootstrapbase, such as base.

Right-to-left

Developers always have to pay attention to RTL languages.

Selector

Always use the selector .dir-rtl to define RTL rules. That class is set on the BODY tag, and it should be placed first if you are combining it with another BODY class. When you are using LESS, encapsulate all the rules in .dir-rtl.

Correct

.dir-rtl .something

   margin-left: 0;
   margin-right: 1em;

} .dir-rtl.page-mod-something p

   padding-left: 0;
   padding-right: 1em;

}

.dir-rtl {

   &.page-mod-something {
       p {
           padding-left: 0;
           padding-right: 1em;
       }
   }
   .something {
       margin-left: 0;
       margin-right: 1em;
   }

}

Incorrect

body.dir-rtl .something

   margin-left: 0;
   margin-right: 1em;

} .page-mod-something.dir-rtl p

   padding-left: 0;
   padding-right: 1em;

}

.dir-rtl {

   &.page-mod-something {
       p {
           padding-left: 0;
           padding-right: 1em;
       }
   }

} .dir-rtl {

   .something {
       margin-left: 0;
       margin-right: 1em;
   }

}

Rule placement

The RTL rules should be written close to the LTR ones, not in another file. Placing them close to the LTR ones helps (and reminds) the developers to fix both, without the need to search for the existence of RTL rules. If you are using LESS, it is advised to split a huge block into smaller chunks to help locating the corresponding LTR rules.

Automatic compliance

Whenever possible you should try to avoid writing specific RTL rules. It is more often than one would think possible to have one rule working for both LTR and RTL.

Recommended

p {

   margin: 0 1em;

}

To avoid

p {

   margin-left: 1em;

} .dir-rtl p {

   margin-right: 1em;
   margin-left: 0;

}

What to style

RTL rules should only apply to positioning properties, nothing else. And in most cases you will want to revert the LTR rules, to make sure that the rest works as expected.

Correct

.something {

   text-color: red;
   padding-left: 1em;

} .dir-rtl .something {

   padding-left: 0;
   padding-right: 1em;

}

Incorrect

.dir-rtl .something {

   text-color: red;
   padding-right: 1em;

}

LESS

LESS works like CSS with some extra features. It should follow the CSS guidelines.

Variables

• They should use camelCase to follow Bootstrap 2 that is used in core.
• As for CSS selectors, use semantic names: names tell what this is instead of what should it look like.
• As Bootstrap 2 does, do not add the word "Color" to variables for _background_ or _border_ and their derivatives.
• Declaring new variables should be done sparingly, too many variables kill the purpose of using them. If you declare one, try to set its default value from another one.
• Do not declare more variables than necessary. E.g.: If the background color and border color are likely to always be the same, prefer one variable.

Correct

@textColor: red; @wellBackground: #ccc; @tableBackground: blue; @blockBackground: @wellBackground; @calendarGroupEvent: #f90;

Incorrect

@text-color: red; @wellBackground: #ccc; @tableBackgrounColor: blue; @blockBackground: #ccc; @calendarGroupEventBackground: #f90; @calendarGroupEventBorder: #f90;

Selectors

• Selectors should be encapsulated rather than duplicated.

Correct

div {

   .something {
       color: red;
       a {
           color: blue;
       }
   }
   .something-else a {
       color: green;
   }

}

Incorrect

div .something {

   color: red;

} div .something a {

   color: blue;

} div .something-else a {

   color: green;

}

Values and properties

• Colours, font sizes, etc... should never be hardcoded, use a variable instead.
• Use mixins instead of duplicating values and properties.

Correct

.error {

   font-size: @fontSizeSmall;
   color: @errorText;
   padding: 1em;
   background-color: @errorBackground;

} div .form-error {

   .error;

}

Incorrect

.error {

   font-size: 12px;
   color: red;
   padding: 1em;
   background-color: white;

} div .form-error {

   font-size: 12px;
   color: red;
   padding: 1em;
   background-color: white;

}

Javascript

Use constants

Any Javascript code using some CSS to style or target elements should use constants, not directly use the class names or IDs in the code. This greatly helps maintenance of the code.

Correct

var CSS = {

   GROUP: 'some-group'

} var SELECTORS {

   GROUP: '.' + CSS.GROUP

}

Y.Node.create('

');

Y.all(SELECTORS.GROUP);

Incorrect

Y.Node.create('

');

Y.all('.some-group');

Themes Clean and More

Clean theme should not contain any CSS or LESS content, it should fully inherit from theme_bootstrapbase. More can contain a little portion of LESS to ensure that customization is possible, but it should be almost inherit fully from theme_bootstrapbase.

Credits

This document was drawn from the following sources:

1. The WordPress CSS Coding Standards

See Also

• Coding
• Coding style