Application

+ +

The application consists of one file, application.sass, and it acts as the loader file for MVCSS. The file consists of imports and the inbox.

+ +

Imports

+ +

Compass (optional, see below)
Core
Modules

+ +

Note: Compass provides utilities and niceties to make your life easier. We use it, and we recommend that you give it a try.

+ +

Inbox

+ +

The inbox allows developers, and those not actively working on the CSS, to quickly add styles that are easily seen by the maintainer of the file. This section of the Application has worked wonders for us.

Changelog

+ +

v3.0.1

+ +

June 27, 2013

+ +

New comment hierarchy

+ +

v3.0.0

+ +

May 15, 2013

+ +

Add new Core - Helper file
Add new Core - Content file (replaces Containers Module file)
Add new Core - Layout file
Move extends, mixins, animations to new Core - Helper file
Change Core - Reset to Normalize v2.1.0
Add better variable naming conventions
Add more base variables
Add em() function
Add rem() function
Use rems as the default typographic unit
Add better documentation for Core - Helper file elements
Add better documentation for Application file imports
Add better documentation for variables

+ +

v2.1.0

+ +

March 6, 2013

+ +

Remove States as part of Core

+ +

v2.0.1

+ +

March 5, 2013

+ +

Modify the ellipsis, group, and ir extends (commit)

+ +

v2.0.0

+ +

February 22, 2013

+ +

Initial version applied

Base

+ +

Core - Base sets any base-level styles for tags, such as p or blockquote, beyond what's included in the reset or normalize. Text styles set here reflect the most common appearance of that tag in the design.

+ +

Content

+ +

Core - Content and Core - Layout are the bridge between base-level tags and modules. They give you the ability to set up abstractions that make contextual tweaks easier.

+ +

The difference between Core - Content and Core - Layout is that Core - Content applies mainly to typography (fonts, colors), while Core - Layout applies to just that, layout (margin, padding, sizing, positioning).

+ +

Note: The c- prefix is an implicit module. There is no c base module; it's only used as a prefix for the content modules.

+ +

Headings

+ +

We set the headings in the Core - Content rather than Core - Base, because we want the ability to share heading styles.

h1, .c-h1, %c-h1
  font-size: 40px
  margin-bottom: 20px

Borrowed from OOCSS, sometimes we want an h2 on a page to look like an h3. This gives us the ability to do that:

%h2.c-h3 Heading

Or, using the placeholder selector:

.tagline
  @extend %c-h3

%h2.tagline This is a tagline for my site.

Utilities

+ +

We set default Core - Content utilities. Let's look at an example to show how this works. Here are a couple of the default utilities available to you:

%c-center, .c-center
  text-align: center

%c-condense, .c-condense
  font-size: 85%

And in your markup:

%form.form-field
  %input(type="text")
  %p.c-condense This is a note.

Or, if you prefer to use Sass placeholder selectors as silent classes:

%form.form-field
  %input(type="text")
  %p.form-field-desc This is a note.

.form-field-desc
  @extend %c-condense

Note: You can set your own custom content utility modules for your project.

+ +

Custom Submodules

+ +

You can extend multiple content utilities, or even form another content submodule:

.c-tagline
  @extend %c-center
  @extend %c-condense

Helpers

+ +

Core - Helpers consists of:

+ +

Extends
Functions
Mixins
Keyframe Animations

+ +

A Note About Sizing

+ +

By default, MVCSS sizes all elements (font-size, margin, padding) with rems. We do this through the rem() function, that simply divides the target pixel value by the $base-fontSize. Here's an example:

h4
  font-size: rem(20px)

Note: Be sure to look at your site's browser support to determine if rems are the right option. Take a look at the current browser support for rem.

+ +

If you'd like to use ems, there is an em() function available as well:

h4
  font-size: em(20px)

However, with ems, if you were to alter the context from the default $base-fontSize, you would need to pass the new context in as the second argument:

h4
  font-size: em(20px)
  padding-bottom: em(10px, 20px)

To make adjustments easier, create a local $context variable for the size:

h4
  $context: 20px
  font-size: em($context)
  padding-bottom: em(10px, $context)

Core

+ +

The core consists of six components:

+ +

1. Reset

+ +

Standard Normalize.css reset.

+ +

2. Settings

+ +

@font-face and global variables.

+ +

3. Helpers

+ +

Extends, functions, mixins, keyframe animations.

+ +

4. Base

+ +

Base-level tags.

+ +

5. Content

+ +

Base-level typography (colors, fonts).

+ +

6. Layout

+ +

Base-level layout (margin, padding, sizing).

Layout

+ +

Just like Core - Content, the Core - Layout gives you a higher level of abstraction for your modules.

+ +

Note: The l- prefix is an implicit module. There is no l base module; it's only used as a prefix for the layout modules. This is borrowed from SMACSS, which uses the l- convention in its layout section.

+ +

A good example of a Core - Layout submodule is what we call the cell module (l-cell), which gives your site a max-width, centers it, and applies horizontal padding. Let's take a look:

%l-cell, .l-cell
  margin: 0 auto
  max-width: 900px
  padding: 0 60px

Utilities & Custom Submodules

+ +

Just like Core - Content, there are default utilities provided to you, and you can create your own custom submodules as well. Be sure to read through the MVCSS project files to get familiarized.

Reset / Normalize

+ +

As long as the project size warrants it, we always get things started with a style reset. Normalize.css is what we use, but alternatives like the infamous Eric Meyer Reset CSS are easily interchangeable.

+ +

With Normalize.css, we recommend that you alter it on a per-project basis, and make the proper overrides in Core - Base.

+ +

Settings

+ +

Core - Settings centers on two things:

+ +

@font-face declarations
Variables

+ +

Grouping all the app-wide settings into one file allows newcomers to the project the means to find out what's available to them quickly.

+ +

About

+ +

MVCSS is a Sass-based CSS architecture for creating predictable and maintainable application style.

+ +

As front-end devs at Envy Labs, we work primarily in medium-to-large-sized Rails applications. Each of these projects has a sizable amount of CSS undergoing normal maintenance and iteration. Depending on complexity and setup, changes to existing style can be difficult or done poorly if the right way is too convoluted.

+ +

What? Another Way to Write CSS?

+ +

We're big fans (and often employ tenets of) well-documented methods like OOCSS, BEM, and SMACSS. This bit of architecture and accompanying Styleguide/Library meshes all of our preferred practices into one place.

+ +

All This for CSS?

+ +

CSS in and of itself is simple to pick up, but difficult to apply maintainably to large applications - hence the popularity of the methods listed above. MVCSS is one such manner to organize styles, and the one that we've had the most success in employing.

+ +

Do I Have to Use Sass?

+ +

Sass is not required to employ this paradigm, but all the project files are written in it, so it's definitely recommended.

+ +

Organizational Overview

+ +

MVCSS is broken down into three primary sections:

+ +

Library

+ +

The Library is a collection of Sass modules/helpers and JavaScript (CoffeeScript) components we commonly use. If you're seeking a framework moreso than a methodology, this is your jumping off point for items like grids, tabs, buttons, and forms. You can just plug the modules/components into your base MVCSS project.

Modules

+ +

Modules in this context refer to any unit of style that can be found across multiple pages. Most of your styles should be found here. This draws from the OOCSS idea of separating everything into reusable chunks, making it second-nature if you're familiar with that method.

+ +

Examples of Modules

+ +

Here are some commonly occurring examples of modules:

+ +

Modals
Buttons
Tooltips
Navigation
Re-appearing chunks of content, like a user info card or sidebar

Basics

+ +

Alphabetize properties
Use soft-tabs with two-space indent
Put a space after :
Put a space after the // for comments
Put a space after commas (e.g. rgba(#000, 0.5))
Choose a hexidecimal format and stick to it (e.g. #FFF or #fff)
Do not use ids (only classes)

// This is an example!

.module
  background: #fff
  color: #000
  font-size: 1.6em

.module-submodule
  font-size: 2em
  margin-bottom: 1em

Styleguide

+ +

Everyone has a favorite way to write CSS and determine how to name modules. Realizing that everyone includes us, here are our compiled standards for stylesheet authoring and module naming.

+ +

The styleguide is broken down into:

+ +

Naming Conventions

+ +

Modules

+ +

Note: Module files should be named in the singular, unless your module's name is plural. For example:

+ +

modules/_button.sass
modules/_grid.sass
modules/_form.sass

+ +

Modules are broken down into the base module, submodules, modifiers, and states. If your module or submodule name is two words, use camelCase. For example, .moduleName.

+ +

Submodules

+ +

Submodules use the hyphen - separator to denote that it is a submodule to another module. For example, module-submodule.

+ +

Note: If you have a plural module (e.g. .tabs), you can name your submodule .tab as an exception to this rule. The assumption is made that .tab is a submodule of .tabs.

+ +

Modifiers

+ +

Use -- for a modifier on a module or submodule. For example:

+ +

.module--modifier
.module-submodule--modifier.

+ +

Note: Module and submodule modifier variables contain the same convention. For example:

$module--modifier-background: #000

States

+ +

Use the is-state, is-module-state, is-module-submodule-state pattern for your states. For example:

+ +

.is-active
.is-sidebar-toggled
.is-nav-item-active

+ +

Context

+ +

Use has- for adding a context with specific styles on a module or submodule. For example:

<div class="nav has-dropdown">
  <!-- ... -->
</div>

.has-dropdown
  position: relative

Note: This idea is borrowed from suitcss.

+ +

Note: This is different than a Modifier, which sets custom, alternate styles on the base module.

+ +

Sass Variables

+ +

Variables, as documented in Core - Settings, should follow the same naming conventions as your modules, referenced above. The most global variables (used in multiple places, multiple contexts) are prefixed with $base-. Let's look at some examples:

$base-background: #eee
$base-color: #444
$base-borderRadius: 3px
$base-fontSize: 16px
$base-lineHeight: 1.6
$base-whitespace: 20px

Content and layout variables are prefixed with $c- and $l-, respectively.

$c-header-color: #999
$c-header-fontFamily: sans-serif
$l-maxWidth: 960px
$l-sidebar-width: 200px

You may also create module-specific variables, like so:

$grid-breakpoint-lap: 480px
$grid-breakpoint-desk: 800px
$grid-gutter: 20px
$form-fontSize: 12px
$form-input-background: #ddd

Hierarchy

+ +

Do not use .block--left or .block--right
Do use .block--a and .block--b to semantically establish hierarchy

+ +

Images

+ +

A section about naming images? I know. Let's just get through it.

+ +

bg-* for backgrounds
icn-* for icons
logo-* for logos
img-* for generic images
Sub-folders for larger groups

Sass-specific (.sass)

+ +

Follow the same rules listed in the Basics section
Do not nest deeper than 3 levels (with the exception of pseudo/hover states)
Place mixin(+) and @extend calls at the top of the properties list

+ +

Comments

+ +

There are four levels of comments:

// *************************************
//
//   First Level
//   -> Description
//
// *************************************

// -------------------------------------
//   Second Level
// -------------------------------------

// ----- Third Level ----- //

// Fourth Level