Crossway Styles

The internal Crossway styleguide.

Under construction

Getting started

Clone the repo:

$ git clone git@github.com:Crossway/styleguide.git

$ cd styleguide

To install:

$ make install

To build the style guide:

$ make build

To build the style guide whenever it changes:

$ make watch

To serve the built style guide on port 8000:

$ make serve

To publish the built style guide on http://crossway.github.io/styleguide/ (be sure to commit your changes locally too!):

$ make publish

Built With Pure

The Crossway default styles are based on Pure, a lightweight set of base styles. The main difference: we have replaced the pure- class namespace with cw-.

All modules in Pure build on top of Normalize.css. It's our foundational layer to maintain some degree of cross-browser consistency.

Extending Pure

One of our goals when developing Pure was to make it extremely extensible. By including Pure and writing some CSS on top of it, you can ensure that your site or app works across browsers, while looking truly unique. Best of all, your CSS file size will remain tiny, which is a great thing for mobile users and others with slow connections.

Want a quick start? Take a look at some layouts that we've built on top of Pure.

Based on SMACSS

Pure is broken up into a set of responsive modules. From the beginning, we adopted SMACSS as a convention for writing our CSS. For those who are new to SMACSS, you should give it a quick read, especially the section on module rules.

Class Name Conventions

One of the conventions in Pure is for every module to have a standard class name for common rules across a module, and then have additional class names for specific presentational rules for a specific sub-module. All classes start with a cw- prefix to prevent collisions. In addition, we try not to have presentational class names. Instead of calling something cw-form-horizontal, we prefer to call it cw-form-aligned. This prevents a tight coupling between class names and styles, which is good for maintainability.

For example, let's consider the HTML and CSS for a Stacked Form:

Stacked Form: HTML

A stacked form is created by adding two class names, cw-form and cw-form-stacked.

<form class="cw-form cw-form-stacked">
    <input>
    <input>
</form>

Stacked Form: CSS

The two class names serve different purposes. One is used as a general selector to group common rules for all forms, while the other defines specific rules for a stacked form.

/*
Standard rules that all Pure Forms have. This includes rules for
styling `.cw-form` `<inputs>`, `<fieldsets>`, and `<legends>`,
as well as layout ules such as vertical alignments.
*/
.cw-form { ... }

/*
Specific rules that apply to stacked forms. This includes rules
such as taking child `<input>` elements and making them 
`display: block` for the stacked effect.
*/
.cw-form-stacked  { ... }

Extending Pure

When you're extending Pure, we recommend that you follow this convention. For instance, if you wanted to create a new type of form, your HTML should look something like this:

<form class="cw-form-custom cw-form">
    <input>
    <input>
</form>

Then, in the CSS:

.form-custom { ... }

One common task that you may wish to do is to style buttons so they look different. The Pure Button Documentation has some examples on how you can create buttons with custom sizes and styles by adopting this modular architecture.

StyleDocco

The style guide is built using a heavily-customized version of StyleDocco. We've modified Docco's template and styles so that it uses the style guide's own styles for styling the style guide. Because why wouldn't you want to do that?

To modify the style guide template, you'll need to modify styledocco/share/docs.jade, a Jade template.

StyleDocco-specific styles can be found in styledocco/share/styledocco.css.