Styleguide -

A style guide and code standards document is a way of ensuring brand and code consistency. By maintaining all of a website's primary elements on a single page, we can see how we can modularly reuse components as well as how changes to semantic elements will effect the site overall. This style guide also serves as a curated, archival collection for design and UX/UI decisions made during the course of the site's development. Creating code that tends to avoid arbitrary decisions if a predefined choice presents itself.

Slab Colors

Typography Colors

Fonts

ABCDEFGHIJKLMNOPQRSTUVWXYZ
abcdefghijklmnopqrstuvwxyz
0123456789
ABCDEFGHIJKLMNOPQRSTUVWXYZ
abcdefghijklmnopqrstuvwxyz
0123456789

Headings

h1 / .h1 - The H1 is the main page heading

Page Title / Section Title
h2 / .h2 - The H2 is the page level or section heading

Page Title / Section Title

The secondary header above is an h2 element, which may be used for any form of important page-level header. More than one may be used per page. Consider using an h2 unless you need a header level of less importance, or as a sub-header to an existing h2 element.
h3 / .h3 - The H3 is a third-level heading

Section Header / Banner Title / Section Subhead

The header above is an h3 element, which may be used for any form of page-level header which falls below the h2 header in a document hierarchy.
h4 / .h4 - The H4 is the fourth-level heading

Sub Header

Typically used for article title or call-to-action elements.
h5 / .h5 - The H5 is the fifth-level heading

Sub Header
h6 / .h6 - The H6 is the sixth-level heading and the lowest

Sub Header

Each heading has an accompanying class that can be used for styling any element without the need or restriction of SEO impact.
This is an .hgroup

This is the heading group's main heading

This is the heading group's subheading

Body

.lede (Intro text)

A lede, or lead, paragraph in literature is the opening paragraph of an article, essay, news story or book chapter. It usually occurs together with the headline or title. It precedes the main body of the article, and it gives the reader the main idea of the story. In both spellings, the word rhymes with the word need.
<p> or .body-text

All paragraphs are wrapped in p tags. Additionally, p elements can be wrapped with a blockquote element if the p element is indeed a quote. Historically, blockquote has been used purely to force indents, but this is now achieved using CSS. Reserve blockquote for quotes.

<small> or .small-body-text

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
.disclaimer-text

The disclaimer is always 11px.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum id molestie nunc. Suspendisse eu lorem ipsum, in luctus nunc. Etiam in sapien ut nunc cursus tempus non lacus.

Inline

<a> - This is a text link
<a> - This is an external text link
<strong> - Strong is used to indicate strong importance
<em> - This text has added emphasis
<b> - The b element is stylistically different text from normal text, without any special importance
<i> - The i element is text that is set off from the normal text
<u> - The u element is text with an unarticulated, though explicitly rendered, non-textual annotation
<del> & <ins> - This text is ~~deleted~~ and This text is inserted
<s> - ~~This text has a strikethrough~~
<sup> - Superscript^®
<sub> - Subscript for things like H₂O
<abbr> - Abbreviation: HTML
<kbd> - Keybord input: Cmd
<q> - This text is a short inline quotation
<cite> - This is a citation
<dfn> - The dfn element indicates a definition.
<mark> - The mark element indicates a highlight
<var> - The var element defines a variable
<address>

Address Name
1234 Main St.
Anywhere, US 12345
<tel> - 1-800-851-9530
<time> - 19 Dec 2015
<blockquote>
One small step for man, one giant leap for mankind.
.text-info - This text is informative
.text-error - This text is an error
.text-success - This text is a success

Icons

Font Awesome is employed for scalable vector icons that can be customized — size, color, drop shadow, and anything that can be done with CSS. These icons will always match the font color.

.fa.fa-search ()
.fa.fa-user ()
.fa.fa-check ()
.fa.fa-times ()
.fa.fa-search-plus ()
.fa.fa-search-minus ()
.fa.fa-power-off ()
.fa.fa-cog ()
.fa.fa-home ()
.fa.fa-inbox ()
.fa.a-repeat ()
.fa.fa-refresh ()
.fa.fa-bookmark ()
.fa.fa-print ()
.fa.fa-pencil ()
.fa.fa-map-marker ()
.fa.fa-chevron-left ()
.fa.fa-chevron-right ()
.fa.fa-plus ()
.fa.fa-minus ()
.fa.fa-asterisk ()

Alignment

.text-left

.text-center

.text-right

.text-justify

<p class="text-left"><code>.text-left</code></p>
<p class="text-center"><code>.text-center</code></p>
<p class="text-right"><code>.text-right</code></p>
<p class="text-justify"><code>.text-justify</code></p>

A button is a required function to perform or complete an action.

For the purposes of consistency, buttons and links can be styled to look identical.

Link Link

<a href="" class="btn button-primary mobile-full">Link</a>

<button class="btn button-primary mobile-full" type="button">Button</button>

<button class="btn button-primary mobile-full progression active" type="button"><i class="fa fa-circle-o-notch"></i> Button w/Icon</button>

<a href="" class="btn mobile-full">Link</a>

Button Types

Error Success Info Dark Disabled

<a href="" class="btn btn-error mobile-full">Error</a>

<a href="" class="btn btn-success mobile-full">Success</a>

<a href="" class="btn btn-info mobile-full">Info</a>

<a href="" class="btn btn-black mobile-full">Dark</a>

<a href="" class="btn button-primary js-disabled mobile-full">Disabled</a>

Button Sizes

Extra Large Large Default Small

<a href="" class="btn button-primary btn-xl mobile-full">Extra Large</a>

<a href="" class="btn button-primary btn-lg mobile-full">Large</a>

<a href="" class="btn button-primary mobile-full">Default</a>

<a href="" class="btn button-primary btn-sm mobile-full">Small</a>

Button Bar

<div class="button-bar">
  <button class="btn button-bar-item">
    One
  </button>
  <button class="btn button-bar-item">
    Two
  </button>
  <button class="btn button-bar-item">
    Three
  </button>
</div>

A CTA is specifically an encouragement of behavior by the user

Download This Thing

<a href="" class="cta cta-primary mobile-full">Download This Thing <i class="fa fa-download"></i></a>

<div class="row">
  <div class="half grid"></div>
  <div class="half grid"></div>
</div>

Combinations

<div class="row text-center">
    <div class="fourth">
        
    </div>
    <div class="three-fourths">
        
    </div>
</div>

Marginless

<div class="row marginless">
    <div class="half">
        
    </div>
    <div class="half">
        
    </div>
</div>

Marginless Combinations

<div class="row marginless">
  <div class="fourth">
    
  </div>
  <div class="three-fourths">
    
  </div>
</div>

Bill Murray Y'all — I'm a figcaption - I tell a bit about the image

<figure>
  <img alt="Bill Murray Y'all" src="http://www.fillmurray.com/g/1500/450">
  <figcaption>I'm a figcaption - I tell a bit about the image</figcaption>
</figure>

<figure>
  <img alt="Bill Murray Y'all" src="http://www.fillmurray.com/640/480" alt="Bill Murray">
</figure>

<figure>
  <img class="image-bordered" alt="Bill Murray Y'all" src="http://www.fillmurray.com/640/480" alt="Bill Murray">
</figure>

<figure>
  <img class="image-rounded" alt="Bill Murray Y'all" src="http://www.fillmurray.com/640/480" alt="Bill Murray">
</figure>

<figure>
  <img class="image-circular" alt="Bill Murray Y'all" src="http://www.fillmurray.com/640/480" alt="Bill Murray">
</figure>

<video controls="controls" poster="http://sandbox.thewikies.com/vfe-generator/images/big-buck-bunny_poster.jpg" width="100%" height="auto">
  <source src="http://clips.vorwaerts-gmbh.de/big_buck_bunny.mp4" type="video/mp4" />
  <source src="http://clips.vorwaerts-gmbh.de/big_buck_bunny.webm" type="video/webm" />
  <source src="http://clips.vorwaerts-gmbh.de/big_buck_bunny.ogv" type="video/ogg" />
  <object type="application/x-shockwave-flash" data="http://releases.flowplayer.org/swf/flowplayer-3.2.1.swf" width="640" height="360">
    <param name="movie" value="http://releases.flowplayer.org/swf/flowplayer-3.2.1.swf" />
    <param name="allowFullScreen" value="true" />
    <param name="wmode" value="transparent" />
    <param name="flashVars" value="config={'playlist':['http%3A%2F%2Fsandbox.thewikies.com%2Fvfe-generator%2Fimages%2Fbig-buck-bunny_poster.jpg',{'url':'http%3A%2F%2Fclips.vorwaerts-gmbh.de%2Fbig_buck_bunny.mp4','autoPlay':false}]}" />
    <img alt="Big Buck Bunny" src="http://sandbox.thewikies.com/vfe-generator/images/big-buck-bunny_poster.jpg" width="640" height="360" title="No video playback capabilities, please download the video below" />
  </object>
</video>

<audio src="assets/audio/test.mp3" controls>
  <p>Your user agent does not support the HTML5 Audio element.</p>
</audio>

The Golden Rule

All code in any part of the code base should look like a single person typed it, no matter how many people contributed.

HTML

Human Readable

Code is written and maintained by people. Ensure your code is descriptive, well commented, and approachable by others.
HTML5 doctype

Enforce standards mode in every browser possible with this simple doctype at the beginning of every HTML page.
```
<!doctype html>
```
Syntax
- Use soft-tabs with two spaces
- Nested elements should be indented once (2 spaces)
- Don't include a trailing slash in self-closing elements
Attributes
- Attributes should be lowercase.
- Always use double quotes ("), never single quotes.
- Boolean attributes should be used without quoted values to avoid redundancy.
Attribute order

HTML attributes should come in this particular order for easier reading of code.
- id
- class
- data-*
- for | type | href | src
HTML Comments
- Section comments are separated from the previous block by one line, and should have one following line of space.
- Prepend section headings with an equal sign (=), to make a Find operation easier.
```

<div class="componentName">
  ...
</div>

```

CSS

- Use soft-tabs with two 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
- Don't include spaces after commas in RGB or RGBa colors
- Do not specify units for zero values, e.g., margin: 0; instead of margin: 0px;
- Use shorthand hex values where available, e.g., #fff instead of #ffffff
- Lowercase all hex values, e.g., #fff instead of #FFF
- Quote attribute values in selectors, e.g., input[type="text"]

Declaration Organization

Box (Display, Float, Position, Left, Top, Width, Height, Margin, Padding, etc.)
Border
Background
Text
Other

.declaration-order {
  /* Positioning */
  position: absolute;
  top: 0;
  right: 0;
  bottom: 0;
  left: 0;
  z-index: 100;

  /* Box-model */
  display: block;
  float: right;
  width: 100px;
  height: 100px;

  /* Typography */
  font: normal 13px "Helvetica Neue", sans-serif;
  line-height: 1.5;
  color: #333;
  text-align: center;

  /* Visual */
  background-color: #f5f5f5;
  border: 1px solid #e5e5e5;
  border-radius: 3px;

  /* Misc */
  opacity: 1;
}

.some-div { color: #222; }

.some-other-div,
.some-additional-div {
  margin: 0 auto;
  color: #222;
}

General Formatting

Use a new line for every block, list or table element, and indent every such child element to show heirarchy and improve understanding. This applies to elements nested in Sass as well.
```
.print {
  display: block;
  margin: 0;
  padding: 0 7px;
  height: 30px;
  background: #4f799f;
  line-height: 30px;
}

.print:hover { background: #265a83; }
```

Avoid Qualifying ID and class names with type selectors

// this is bad
ul#example { color: #ff0; }
div.error { color: red; }

// this is good
#example { color: #0f0; }
.error { color: green; }

p.s. ID's are bad for CSS, only use ID's for javascript hooks when necessary

Hexadecimal Notation

For color values that permit, 3 character hexadecimal is preferred
```
/* not recommended */
color: #00ff00;
```
```
/* recommended */
color: #0f0;
```
!important

Just don't do it.

Use greater specificity to workaround using !important; -- you will be judged in the afterlife

Use the SMACSS Approach

.componentName {

  Base {
  ...
  }

  Layout {
  ...
  }

  Module {
  ...
  }

  State {
  ...
  }

  Theme {
  ...
  }

}

Commenting

// File headers are commented thusly:

/* ==========================================================================
    Component Name -- Version: 1.0.0.0 - Updated: MM/DD/YYYY
   ========================================================================== */

/**
 * Helper class to truncate and add ellipsis to a string too long for it to fit
 * on a single line.
 * 1. Prevent content from wrapping, forcing it on a single line.
 * 2. Add ellipsis at the end of the line.
 */
.ellipsis {
  white-space: nowrap; /* 1 */
  text-overflow: ellipsis; /* 2 */
  overflow: hidden;
}

/* Hints get styled like this */

Sass (or less or stylus, whatever! you choose)

File Organization

Mixins and variables go in scss/global/.
Styles related to components/modules/views go in sass/components/.
Sass and CSS from other projects goes in sass/vendor/.

scss/
├── main.scss
├── globals/
|   ├── _functions.scss
|   ├── _grid.scss
|   ├── _mixins.scss
|   ├── _placeholders.scss
|   ├── _var.scss
├── partials/
|   └── component/
|       └── _component.scss
|       └── _component-theme.scss
└── vendor/
    └── jquery.1.11.2.min.js

Main Stylesheet

All files get compiled into the main.scss stylesheet, and should be scoped accordingly.

The main.scss file serves as a "table of contents" and the @import directives should be listed with vendor dependencies first, then author dependencies and core stylesheets, then components.

Organize the components imports in a manner that makes sense, in other words, group components with the component they extend or inherit from.

/* Mixins and Variables */
// All globals are combined in allGlobals.scss to reduce the nuber of updates necessary to add new files
@import "global/allGlobals";

/* Base */
@import "partials/base";

/* Layout */
@import "partials/layout";

/* Modules */

@import "partials/colors";

@import "partials/typography";

@import "partials/helpers";

@import "partials/lists";

@import "partials/buttons";

@import "partials/pagination";

@import "partials/accessibility";

@import "partials/forms";

@import "partials/images";

@import "partials/videos";

@import "partials/modules";

@import "partials/jumpTo";

@import "partials/_prototype";

@import "partials/_styleguide";

/* Components */

Structuring Code

@extends and @includes are likely to be overwritten by future elements, placing them at the top of the property list calls them out and avoids the beginning of a specificity war.
- @extends should be grouped together at the top of the selector.
- @includes should be grouped together after @extends.
- Regular styles for the current selector should be after @includes.
- Nested selectors appear last, with space seperating each block.
- Nested selectors using & should appear above child (>) nested selectors.
Limit nesting to 3 levels and/or 50 lines

Nesting selectors more than three levels deep and the code is at risk of being to reliant on HTML structure, overly-specific and difficult to understand.

50 lines is reasonable length for keeping an entire block on a code editor screen without having to scroll.
Variabilize ALL THE THINGS!
- Variabilize all colors.
- Numbers (other than 0 or 100%) with strong meaning or frequent use should be variables.
- Use hyphens (-) in variable names.
- Name variables based on what they represent, not their values, e.g. $text-size-large instead of $text-size-24.
- Colors, fonts, and base measurements are all great candidates for variables. If you find yourself writing a number other than 0 or 100% more than once, make it a variable.
- Most variables should be stored in the _vars.scss partial; however, it's acceptable to define component specific variables in the component files.
- In this case, the variables should be stored at the top of the file.
Comments

Try to stick with standard CSS comments, but you can use the Sass style (//) comments for trivial comments or quickly debugging.

JS

Prefix all javascript-based selectors with js-. The idea is that you should be able to tell a presentational class from a functional class. Do it!

SEO

Only One h1 Tag Per Page

While technically we could load a page up with h1 tags, it's a bad SEO practice and can cause penalties.

Use Title Attributes with Links

Using a title="" attribute in your anchor elements will improve accessibility when used the right way.

It is important to understand that the title attribute should be used to increase the meaning of the anchor tag.

How Much Will A Reader Read?

"A sentence should contain no unnecessary words, a paragraph no unnecessary sentences, for the same reason that a drawing should have no unnecessary lines and a machine no unnecessary parts."
William Strunk, Jr.

ARIA & Accessibility

Making it possible to provide an enhanced user experience for people with disabilities when using internet applications with assistive technologies.
Landmark Roles

banner - typically the "header" of the page
```
<header role="banner" class="header"></header>
```
navigation - any navigation list, typically the nav element
```
<nav role="navigation" class="nav"></nav>
```
main - the main content area
```
<section role="main" class="main"></main>
```
complimentary - information that is tangentially related to the main content
```
<aside role="complimentary" class="aside"></aside>
```
contentinfo - contains information about the parent document such as copyrights and privacy statements
```
<footer role="contentinfo" class="footer"></footer>
```
Using alt Text Properly

A few tips on how and when to use the alt attribute:
- Use the alt attribute for any image that is used as content.
- Use an empty alt atribute for any image that is decorative or not necessary for understanding the content of the page (alt=”“).
- Make sure the description of the image is useful. For example, if the image is your logo your alt should be your company name and not “logo”
The alt attribute is meant to help users using assitive techonology not miss any content, so make sure your text is helpful to anyone not seeing the image.
<.visually-hidden> - The Visually-Hidden class allows for 508 Compliance on an element needed for visually assisted users.

About the Style Guide

Slab Colors

Typography Colors

h1 / .h1 - The H1 is the main page heading

Page Title / Section Title

h2 / .h2 - The H2 is the page level or section heading

Page Title / Section Title

h3 / .h3 - The H3 is a third-level heading

Section Header / Banner Title / Section Subhead

h4 / .h4 - The H4 is the fourth-level heading

Sub Header

h5 / .h5 - The H5 is the fifth-level heading

Sub Header

h6 / .h6 - The H6 is the sixth-level heading and the lowest

Sub Header

This is an .hgroup

This is the heading group's main heading

This is the heading group's subheading

.lede (Intro text)

<p> or .body-text

<small> or .small-body-text

.disclaimer-text

Button Types

Button Sizes

Button Bar

Combinations

Marginless

Marginless Combinations

The Golden Rule

HTML

Human Readable

HTML5 doctype

Syntax

Attributes

Attribute order

HTML Comments

CSS

Declaration Organization

General Formatting

Hexadecimal Notation

Just don't do it.

Use the SMACSS Approach

Commenting

Sass (or less or stylus, whatever! you choose)

File Organization

Main Stylesheet

Structuring Code

Limit nesting to 3 levels and/or 50 lines

Variabilize ALL THE THINGS!

Comments

JS

SEO

Only One h1 Tag Per Page

Use Title Attributes with Links

How Much Will A Reader Read?

ARIA & Accessibility

Landmark Roles

Using alt Text Properly

FIN.

`h1` / `.h1` - The H1 is the main page heading

`h2` / `.h2` - The H2 is the page level or section heading

`h3` / `.h3` - The H3 is a third-level heading

`h4` / `.h4` - The H4 is the fourth-level heading

`h5` / `.h5` - The H5 is the fifth-level heading

`h6` / `.h6` - The H6 is the sixth-level heading and the lowest

This is an `.hgroup`

`.lede` (Intro text)

`<p>` or `.body-text`

`<small>` or `.small-body-text`

`.disclaimer-text`