Table of Contents

  1. Introduction
    1. What is Winston?
    2. Download
    3. Why?
    4. Usage
    5. Test suite
    6. Thanks!
  2. Conventions
    1. Commenting
    2. Indentation
    3. Handling the default content problem
    4. On presentational markup
  3. Documentation by module
    1. Module: Layout
      1. Grid based columns
      2. Percentage based columns
      3. Center anything (horizontally)
      4. Center anything (vertically)
    2. Module: Reset
    3. Module: Avatars
    4. Module: General
    5. Module: Typography
    6. Module: Links
    7. Module: Buttons
    8. Module: Simple pagination
    9. Module: Forms

Conventions

This part of the documentation documents the conventions used in Winston stylesheets and markup to keep code understandable and readable. These conventions provide a good start to build websites and apps with Winston in a proper manner. You can, of course, always use your own ways of doing things. These are guidelines.

Comments in Winston

Every CSS file starts with some metadata: author, copyright, license (if any).

					/*

						Stylesheet for PROJECTNAME

						Media:      screen, projection
						Copyright:  Company Name <http://www.companyname.com>
						Author:     Name Surname <name@domain.com>

					*/

This is the standard way of marking up block comments in your CSS: (e.g. "this is the css for the buttons")

					/*
						Buttons
					*/

And inline comments:

					#container {
						display: inline; /* Fix double margin bug */
					}

Indentation is important

Properly indent your files to produce readable code, for yourself and for your team. Don't do this:

					<ul>
					<li>Don't do this</li>
					</ul>
				
					<ul><li><a href="#"><span>Nor</span> <strong>this</strong> one line crap</a></li>
					 

As a general rule, block elements should live on their own line, e.g. the opening <ul> and closing </ul> should be on the same line. Inline elements can be on the same line as long as things stay clear. If lines get too long (longer than 100 characters for instance) then you should start putting inline elements on separate lines. This happens, for instance, when constructing button CSS that includes a lot of inline elements to work around lacking browsers.

So do this (preferred):

					<div class="buttonHolder">
						<a href="#" class="button buttonSmall">
							<span>Something</span>
						</a>
					</div>

Or this:

					<div class="buttonHolder">
						<a href="#" class="button buttonSmall"><span>Something</span></a>
					</div>

Not this:

					<div class="buttonHolder"><a href="#" class="button buttonSmall"><span>Something</span></a></div>

Naming IDs and classes

  • Use camelCase for everything
  • Use non-trivial, English language id and class-names

How Winston handles the default styling problem

Browsers have their default way of styling HTML elements. In order to get a consistent look across browsers, we use a CSS reset to reset every element, and then build the styling back up. The problem with this is that it leads to a horrendous amount of extra CSS. Let's clarify with an example.

One of the most commonly used elements in building websites is the unordered list. It default to what you would think an unordered list looks like: bullet points and a bit of margin and/or padding on the <ul> and <li> elements.

This is what it looks like:

When we reset the unordered list, this is what it looks like:

  • Item one
  • Item two

So, the common thing for a web designer to do is to define some styles so it ends up looking like this:

  • Item one
  • Item two

This fits with the other styling. Good. But now, for the problem. The designer has to build a navigation and he doesn't need to the bullets. This is what he's going to do:

						#navigation ul {
							list-style: none;
							padding: 0;
						}

Reset, build up again, reset again. Not good. Winston has a better way to handle this, and it's called the .content class. Whenever you add the .content class to a parent elements, the HTML elements within are styled accordingly.

In base.css you might find rules like these one then:

						.content ul,
						.content ol {
							padding: 0 0 12px 24px;
						}

						.content ul {
							list-style: disc;
						}

						.content ol {
							list-style-type: decimal;
							padding: 0 0 12px 24px;
						}

Why? Most of the unordered lists you use when building a website or web application do not function as standard unordered lists, but as navigation, step selectors et cetera. The content class can clearly define which areas are actual content.

On presentational markup

Winston occasionally uses presentational markup. Many HTML purists won't like this. But they're the only ones who care. For designers and developers, the HTML and CSS decisions made lead to cleaner and maintainable code. Users will be served a lighter page. You might not think there's too much difference between <span class="item"> and <b>, but when a list contains a thousand items there is indeed a difference, namely one of many bytes.

For example, when hooking up an image via a CSS sprite, we might use the <b> and <i> tags, since they are short and offer us another option instead of yet another classname. Much of this has to do with the way the cascade in CSS works and document weight.