DMD's Web Development Guidelines
Note to the reader: This document is a work in progress.
Development
Local environment
This assumes the following global installs:
To install dependencies, fork our starter repo (or clone the existing project repo) and run the following in your project directory:
$ npm install
Then run the following command:
$ gulp
...which should:
- Watch files for changes as you dev
- Compile your SCSS to CSS
- Concatenate and minify your JS and CSS
- Update your live browser view via browsersync
Versioning
Work with a "stable master" philosophy, meaning that the master branch is the production deploy. All work should be completed on the develop branch and pushed to master before deploying to production. More information can be found here.
CSS
DMD hopes to impart a "mobile-first" philosophy, utilizing only min-width media queries. This means that the majority of application styling will be in base/_global.scss. Variable names should be camel cased. All the files to be included (along with a reset) in src/scss/app.scss. The scss structure looks like:
# Generic set up
app.scss
/base
_variables.scss
_mixins.scss
_normalize.scss
_global.scss
_utilities.scss
# Additional scss files
/screens
tablet.scss
tabletLarge.scss
desktop.scss
CSS Guidelines are adapted from BEM using the "Block Element Modifier" semantic CSS naming convention Avoid overqualified selectors. The format is as follows:
.<block>[--modifierName|__elementName]
Block
Encapsulates a standalone entity that is meaningful on its own. While blocks can be nested and interact with each other, semantically they remain equal; there is no precedence or hierarchy. Holistic entities without DOM representation (such as controllers or models) can be blocks as well.
Syntax: .nav
<nav class="nav"></nav>
Block__element
Syntax: .nav__item
Parts of a block and have no standalone meaning. Any element is semantically tied to its block.
componentName--modifierName
Syntax: .nav__item--last
<nav class="nav">
<ul class="nav__list">
<li class="nav__item"><a class="nav__link" href="#">Link</a></li>
<li class="nav__item nav__item-last"><a class="nav__link" href="#">Link</a></li>
</ul>
</nav>
We use SCSS as our preprocessor, mostly for variables and mixins. Do not nest selectors as this can quickly become difficult to read.
Utility classes
Syntax: .u-<utilityName>
It is recommended to create utility selectors as necessary, these should be prefixed with u- and should be universal. These selectors should not be modified from their initial definition. If you need to use more than one utility selector in a given element, create a new componentName selector.
.u-textCenter
.u-bgColorRed
Format
Define the css selectors with an opening curly on the first line. All declarations must be indented 2 spaces on the following lines, one declaration per line, in alphabetical order. Single declaration selectors can remain on one line. All indentation should be 2 character spaces. Use 'single quotes' over "double quotes" where applicable.
/* Multi declaration selector */
.row {
float:left;
position: relative;
width: 100%;
}
/* Single declaration selector */
.row--even { background: $altWhite; }
.row--active { background: $blue; }
.u-alignLeft { float:left; }
js- selectors should never be styled and only be used for event interactions.
HTML
Use semantic HTML5 Markup. Never use an ID unless necessary. See CSS section for information about class naming.
Javascript
Use jQuery. All files should be located in src/js. Try to keep all Javascript lines to a maximum of 80 characters. This can be unavoidable in some cases, so if you must break 80 characters, do not exceed 120. All events should be called using js- prefixed selector.
Commenting
Use /*! COMMENT */ as a comment block. Use multiline comments over single line comments.
Format
Each JS file should use jQuery and be wrapped with an IIFE. Each method should be documented with a few words or sentence about what the interaction is doing. Indentation should be 2 character spaces. Use single quotes over double quotes.
;(function(window, $) {
/*!
* Document ready
*/
$(function() {
/*!
* Toggle mobile nav
*/
$('.js-toggleNav').on('click', function(e) {
e.preventDefault();
$('body').toggleClass('is-showingMobileNav');
});
// ...
});
})(window, jQuery);
Custom classes
When creating custom classes, use a separate file with the class created using prototypical inheritance. Private variables should be appended with _ as opposed to prefixing. Comments should be able to be read by jsdoc use multiline, /** COMMENT */. Comments that begin with /*! are ignored by jsdoc.
;(function(window, $){
/**
* A Custom Class
*
* @param {String=} options - description.
* @constructor
*/
function CustomClass(title) {
this.title_ = title || 'Title';
};
/**
* Gets the title
*
* @memberof CustomClass
* @returns {String}
*/
CustomClass.prototype.getTitle = function() {
var self = this;
return self.title_;
};
/**
* Bind to window
*/
window.CustomClass = CustomClass;
})(window, jQuery);
Usage in main application file.
;(function(window, $, CustomClass) {
var item = new CustomClass();
console.log(item.getTitle()); // Title
})(window, $, CustomClass);
Questions
If there are any questions please chat / email / hangout / call joel@uconn.edu