The Kraken Code Guide

Some basic standards to ensure that Kraken add-ons and forks share a common language and approach.

The Golden Rule
HTML
- HTML Syntax
- Attribute Order
CSS
JavaScript
- JavaScript Syntax
- Progressive Enhancement
Organization & Documentation

Guidelines
Section Headings
Inline Documentation

Thanks

The Golden Rule

Write code for humans. That means clear section headers, ample white space, and lots of inline documentation.

HTML

HTML Syntax

Use soft-tabs with four spaces.
Nested elements should be indented once (four spaces).
Always use double quotes, never single quotes.
Don't include a trailing slash in self-closing elements.
Always use the HTML5 doctype.

Incorrect example:

<HTML PUBLIC '-//W3C//DTD HTML 4.01 Transitional//EN' 'http://www.w3.org/TR/html4/loose.dtd'>
<html>
<head>
<title>Page title</title>
</head>
<body>
<img src='img/company-logo.png' alt='Company' />
<h1 class='text-muted'>Hello, world!</h1>
</body>
</html>

Correct example:

<!DOCTYPE html>
<html>
    <head>
        <title>Page title</title>
    </head>
    <body>
        <img src="img/company-logo.png" alt="Company">
        <h1 class="text-muted">Hello, world!</h1>
    </body>
</html>

Attribute Order

HTML attributes should be written in this order for easier reading of code:

class
id
data-*
for/type/href

Example:

<a class="" id="" data-target="" href="">Example link</a>

CSS

CSS Syntax

Use soft-tabs with four spaces.
When grouping selectors, keep individual selectors to a single line.
Include one space before the opening brace of declaration blocks.
Place closing braces of declaration blocks on a new line.
Include one space after : in each property.
Each declaration should appear on its own line.
End all declarations with a semi-colon.
Comma-separated values should include a space after each comma.
Lowercase all hex values (ex. #ffffff instead of #FFFFFF).
Use full hex values instead of shorthand (ex. #ffffff instead of #fff).
Quote attribute values in selectors (ex. input[type="text"]).
Avoid specifying units for zero values (ex. margin: 0; instead of margin: 0em;).
Avoid shorthand for margins and padding unless they're all the same value (ex. margin-left: auto; and margin-right: auto; instead of margin: 0 auto;).
Omit units on the line-height property (ex. line-height: 1.2; instead of line-height: 1.2em;).
Always use relative sizing - ems and percentages, not pixels.

Incorrect example:

.selector, .selector-secondary, .selector[type=text] {
font-size:15px;
line-height:1.2em;
color:#FFFFFF;
margin:0px auto;
padding:17px}

Correct example:

.selector,
.selector-secondary,
.selector[type="text"] {
    font-size: .882352941em
    line-height: 1.2;
    color: #fff;
    margin-left: auto;
    margin-right: auto;
    padding: 1em;
}

Declaration Order

Related declarations should be grouped together, placing box-model and positioning properties closest to the top, followed by typographic properties, margin and padding, and visual properties.

.declaration-order {
    /* Box-model */
    display: block;
    width: 100%;
    max-height: 20em;
    float: right;

    /* Positioning */
    position: absolute;
    top: 0;
    left: 0;
    z-index: 100;

    /* Typography */
    font-size: .875em;
    line-height: 1.5;
    color: #272727;
    text-align: center;

    /* Margin & Padding */
    margin-bottom: 1em;
    padding: 2em;

    /* Visual */
    background-color: #e5e5e5;
    border: 1px solid #808080;
    border-radius: .25em;

    /* Misc */
    opacity: .7;
}

Formatting Exceptions

When using vendor prefixed properties, indent each property such that the value lines up vertically for easy multi-line editing.
In instances where several rules are present with only one declaration each, consider removing new line breaks for readability and faster editing.
In instances where selectors are so short that breaking them up across multiple lines makes them harder to read, consider including them on one line.

.selector {
    -webkit-transition: opacity 0.35s ease;
       -moz-transition: opacity 0.35s ease;
        -ms-transition: opacity 0.35s ease;
         -o-transition: opacity 0.35s ease;
            transition: opacity 0.35s ease;
}
            
.icon-logo:before   { content: "\e000"; }
.icon-github:before { content: "\e001"; }
.icon-docs:before   { content: "\e002"; }

h1, h2, h2, h4, h5, h6 { 
    line-height: 1.2; 
    font-weight: normal;
}

Class Names

Keep classes lowercase and use dashes (not underscores or camelCase).
Avoid arbitrary shorthand notation.
Keep classes as short and succinct as possible.
Use obvious, meaningful names.
Prefix classes based on the closest parent component's base class.

Bad example:

.b { ... }
.btnWarning { ... }
.btn_Large { ... }

Good example:

.btn { ... }
.btn-red { ... }
.btn-large { ... }

Selectors

Use classes, not IDs or generic element tags.
Keep them short and limit the number of elements in each selector to three.

Bad example:

header { ... }
.container #main #nav .icon { ... }

Good example:

.text-large { ... }
.nav .icon { ... }
.icon-bar { ... }

JavaScript

JavaScript Syntax

Always use vanilla JS or jQuery for add-ons (unless, of course, you're forking Kraken to another framework).
Wrap all functions in a .noConflict() ready function.
Use camelCase for all variables.
Omit the unneeded $ before variables.

Incorrect example:

$('.collapse-toggle').click(function(e) {
    e.preventDefault();
    var $data_id = $(this).attr('data-target');
    $(data_id).toggleClass('active'); 
});

Correct example:

(function($) {
    $('.collapse-toggle').click(function(e) {
        e.preventDefault();
        var dataID = $(this).attr('data-target');
        $(dataID).toggleClass('active'); 
    });
});

Progressive Enhancement

JavaScript should always be a progressive enhancement. Check for JS support before hiding or altering content.

JavaScript:

(function($) {
    $(function () {
        $('body').addClass('js'); // On page load, add the .js class to the  element.
    });
})(jQuery);

CSS:

.selector { /* Default styles */ }
.js .selector { /* Progressively-enhanced styles */ }

Organization & Documentation

Guidelines

Combine like file-types into a single file (ex. all CSS in one file, all JS in another).
Break content up into meaningful sections.
Add inline documentation to everything.

Headings & Sections

File headings and section titles should be clear and distinct. Include five line breaks of white space between sections. Use the following format for files headings and section titles.

File Headings:

/* =============================================================

    Name v1.0
    Description of file by your name
    http://your-url.com

    Free to use under the MIT License.
    http://opensource.org/licenses/MIT
    
 * ============================================================= */

Section Titles:

/* =============================================================
    SECTION TITLE
    Section description
 * ============================================================= */

Inline Documentation

Inline documentation should describe both what a snippet of is and what it does.

/*  Removes list styling.
 *  For semantic reasons, should only 
 *  be used on unordered lists. */
.list-unstyled { 
    margin-left: 0; 
    list-style: none; 
}

Thanks

Thanks for helping make Kraken better. This code guide was inspired by Mark Otto.

Kraken

The Kraken Code Guide

Table of Contents

The Golden Rule

HTML

HTML Syntax

Attribute Order

CSS

CSS Syntax

Declaration Order

Formatting Exceptions

Class Names

Selectors

JavaScript

JavaScript Syntax

Progressive Enhancement

Organization & Documentation

Guidelines

Headings & Sections

Inline Documentation

Thanks