Front-end style guide

This style guide covers the interaction of HTML, CSS, and JavaScript on OpenHatch's main website.

The "front end" refers to what people see in their web browsers. We create that experience using HTML, CSS, and JavaScript. We tend to use the jQuery library so we write less JavaScript, and we try to follow good conventions.

This document contains links to high-quality style suggestions from others, and also names some common problems that have occurred in the OpenHatch code in the past.

NOTE: Most of the HTML/CSS advice applies to the upcoming site redesign, so it may not cross-apply well to the live site for the moment.

HTML/CSS

Colors

Main background: lightest grey, #f8f8f8, with light-hatch.png background image. Header and footer: dark grey, #333, with dark-hatch.png background image.

Default text color: darkest grey, #222; black is used sometimes for emphasis.

Links: orange, #FF6D3D; white; darkest grey, #222;

Links don't ever change color; on mouseover, they get underlined.

Borders: translucent light blue, rgba(100, 200, 255, .3); dashed light grey, #e4e4e4;

Module interiors are slightly translucent white: rgba(255,255,255,.6); Occasionally (e.g. the front page) a module can have a full-white interior for emphasis.

Try to avoid font-weight: bold; if possible; differentiate headers and so forth by size, or maybe color, instead.

Cartoons

Cartoons are always 141px high. They should always be flush with the module beneath them. They are only used on one-column pages (even if there are multiple-column areas farther down the page, the first module should be a full-width module).

Layout

There are two base template layouts for pages: one-column and two-columns. Two-columns has a left 1/3 column and a main 2/3 column, cut on the same lines as a three-columns outline.

The template that a page uses should be based on what the first module set on the page looks like. If you want to add more columns on a one-column page, just create the appropriate divs. If you want one or three columns on a two-column page, put them inside the {% more_content %} block.

Two column CSS layout:

<column column-left> <column column-right>

Three column CSS layout:

<column three-column> <column three-column> <column three-column three-column-last>

Modules and submodules

Modules have the following structure:

<module>
    <module-head>
    Optional. 
    The name of the module goes here, inside a h3. 
    Inside of the h3 tag, you can make the title a link, if you want.
    </module-head>
    <module-body>
    Has a white background, the module contents all go in here, including submodules.
    </module-body>
    <module-foot>
    Optional. 
    Want one of those clever links below your module content on the bottom right? Put it in here. 
    If you want a link to also appear on the left, give it the "module-foot-left" class.
    </module-foot>
</module>

Submodules have the following structure:

<submodule>
    <submodule-head>
    Optional. 
    This is where the title for the submodule goes, if you want to differentiate it somehow. 
    Styling for this isn't standardized yet... see /missions/ for an example. 
    Recommended to put the title inside an <h3>.
    </submodule-head>
    <submodule-body>
    Also optional. 
    If you don't want to bother with a head/body distinction, you can just put content straight inside the submodule.
    </submodule-body>
</submodule>

(all tags are the class names of the relevant divs, unless otherwise stated)

You may want to put your submodules inside a <submodule-container> with a <clearer>, if you're floating them but don't want other content to ride up.

CSS

Name IDs and classes using hyphens, not underscores or camelcase. (e.g. "#front-page", not "#front_page" or "#frontPage"). CSS file names should use the same convention. (Not all of them do, but hopefully that can eventually be corrected.)

JavaScript

This is a list of strategies for avoiding problems that have plagued OpenHatch code in the past. Note that the OpenHatch code does not yet follow this guide. It ought to. Perhaps it can be a release goal in the future.

If it's not a link, don't make it a link

If there's no fallback for non-JS users, don't use the <A> tag.

http://openhatch.org/bugs/issue478 covered a problem where a user was clicking on what appeared to be a link. Because there is no JavaScript equivalent for the functionality the user clicked, it simply should not be a link. (Though style-wise it may look the same to the user.)

Don't rely on "return false;"

It is easy to mistakenly use "return false;" at the end of a JavaScript callback when you really mean event.preventDefault(). You can read more about this problem.

Good references

This document by isobar looks great.