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
$ bower install jquery

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.

Link

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

dmd-web-and-mobile/dmd-wp-theme

About

Resources

Stars

Watchers

Forks

Releases

Languages