Raven Framework Starter Page

Introduction

This simple starter page provides some basic information and examples for working with Raven. When you’re ready to start building, just follow these quick steps:

Delete the file at scss/vendor/_demo.scss and the reference to it in scss/main.scss.
Remove the content of this HTML file or create a new one.
Write your HTML and Sass.

About Raven

Still here? Let me tell you about some of the cool things Raven provides and how you can get the most out of it.

At its core, Raven is just a CSS grid system that uses Sass. If that’s all you need, no problem, we won’t be pushy. But just so you’re aware, Raven is an extensible framework with much more to offer.

Raven Dev Environment* — Work in real-time with Sass auto-compilation and LiveReload. Then build optimized code for production environments.
Raven Pattern Library* — Add a style guide and auto-updated documentation to your project, based on the principles of atomic design.
Raven UI* — Take advantage of common interfaces such as carousels, accordions, off-canvas menus, and more.
Raven Forms* — Improve your form layouts and styles.
Raven RequireJS* — Create AMD-compliant JavaScript modules and keep your code organized.
Raven Unit Tests* — Write unit tests with Karma and Jasmine. Then automate them with Grunt or Gulp using the PhantomJS headless browser.
Raven Code Collab* — Specify EditorConfig rules and common linting configurations for your team.
Raven High-DPI Sprites* — Use the Compass sprite map generator to create separate sprite maps for low- and high-DPI images.

* These components are currently in development.

Configuration

Raven is very light-weight. Basically, you get this file, a few Sass files, and sample Grunt and Gulp configuration files. If you don’t use Grunt or Gulp, not to worry — you can delete those files and forget you ever saw them. All you need to know is how to work with Sass.

See the Build Systems section at the bottom of this page for more details about using Grunt and Gulp.

File Structure

The Sass file structure is as follows:

▾ scss
  ▾ modules
      _config.scss
      _grids.scss
  ▾ partials
  ▾ vendor
      _demo.scss
    main.scss

The modules directory contains functions, mixins, and any file that doesn’t output any CSS. Style definitions for headers, footers, and other components should be placed in the partials directory. Finally, the vendor directory is for third-party style sheets.

The main.scss file should only contain imports to other Sass files. Remember to update it every time you want to include a new Sass file.

Settings

Raven currently provides only two settings: gutters and layout. Be assured, if there were more settings that we deemed useful, they’d be here. Some frameworks provide a ton of configuration options, but most of them just complicate things with no real benefit. Memorizing numerous options on the off-chance you need one doesn’t seem like a beneficial use of time.

To change Raven’s settings, open the scss/modules/_config.scss file and update the values. Change the space between columns by editing the gutters value, and change the layout method value to either float or flexbox. Flexbox is the preferred layout method, but if you need to support older browsers, you should leave it set to float.

Grid Layouts

The grid system allows you to specify your columns in an intuitive way. Simply pass the width of each column to the row() mixin. The row() mixin accepts three parameters: column-spans (a string of column widths), [column-gutter] (the space between columns), and [layout] (float or flexbox). Only column-spans is required. The gutters and layout method can be defined globally.

HTML

<div class="sample-row">
	<div>25%</div>
	<div>25%</div>
	<div>50%</div>
</div>

Sass

.sample-row {
	@include row(25% 25% 50%);
}

Result

25%

50%

You can even mix units within a row. In the following example, the left and right columns will always by 200px wide, but the center column will stretch to the fill the remaining space.

HTML

<div class="sample-row">
	<div>200px</div>
	<div>100%</div>
	<div>200px</div>
</div>

Sass

.sample-row {
	@include row(200px 100% 200px);
}

Result

200px

100%

200px

Note: A Flexbox layout will be automatically triggered when using units other than percentages. Keep this in mind if you need to support older browsers.

If you prefer the more traditional grids (e.g., 2 out of 12 columns), you can use the following syntax.

HTML

<div class="sample-row">
	<div>2 of 12</div>
	<div>4 of 12</div>
	<div>6 of 12</div>
</div>

Sass

.sample-row {
	@include row(200%/12 400%/12 600%/12);
}

Result

2 of 12

4 of 12

6 of 12

Nested Rows

Nesting rows is easy. Just use the same row() mixin on the child rows.

HTML

<div class="sample-parent">
	<div>25%</div>

	<div class="sample-nested">
		<div>5em</div>
		<div>100%</div>
	</div>
</div>

Sass

.sample-parent {
	@include row(25% 75%);
}

.sample-nested {
	@include row(5em 100%);
}

25%

5em

100%

Centered Columns

Easily center columns using the native justify-content CSS property.

HTML

<div class="sample-row">
	<div>15rem</div>
	<div>15rem</div>
</div>

Sass

.sample-row {
	@include row(15rem 15rem);
	justify-content: center;
}

Result

15rem

Note: If you want to center columns with percentage width values, you will have to use Flexbox layout. This can be configured globally or by passing the $layout:flexbox argument to the row() mixin.

Column Reordering

The column-order() mixin can easily reorder columns for you — none of that push/pull columns nonsense that other frameworks use.

HTML

<div class="sample-row">
	<div>First</div>
	<div>Second</div>
	<div>Third</div>
</div>

Sass

.sample-row {
	@include row(100%/3 100%/3 100%/3, $layout: flexbox);
	@include column-order(3 1 2);
}

Result

First

Second

Third

Note: The column-order() mixin makes use of Flexbox, so set it globally or pass it as an argument as in the example above.

Gallery Layout

If you only need a simple grid of thumbnail images or all of your columns are the same width, you can take advantage of the gallery() mixin. Then you can add as many items as you want without having to place them in separate rows.

HTML

<ul class="sample-gallery">
	<li>1</li>
	<li>2</li>
	<li>3</li>
	<li>4</li>
	<li>5</li>
	<li>6</li>
</ul>

Sass

.sample-gallery {
	@include gallery(3);
}

Result

Equal Columns

Sometimes it just isn’t possible to know how many columns will go in your row. For example, you may need to create a horizontal menu that will be managed by authors in a content management system. In these cases, the equal-columns() mixin is helpful.

The sample below can have any number of columns, and they will automatically adjust to fill the row.

HTML

<ul class="sample-row">
	<li>1</li>
	<li>2</li>
	<li>3</li>
	<li>4</li>
</ul>

Sass

.sample-row {
	@include equal-columns($layout: flexbox);
}

Result

We use display: table when Flexbox is not specified. If you decide not to use the Flexbox layout, be aware that you may need to tweak some margins and spacing around the container element.

Build Systems

If you are familiar with Grunt or Gulp, you will notice that Raven comes with config files for both. Follow these steps:

Delete the config file you don’t need (either Gruntfile.js or gulpfile.js).
Open package.json and remove the dependencies you won’t be using. For example, if you will be using Gulp, you may remove all of the Grunt dependencies.
Run npm install from the root directory of this project.

Grunt

Use grunt watch to automatically compile your Sass into CSS as you make changes. Run grunt by itself to generate optimized CSS.

Gulp

Use gulp watch to automatically compile your Sass into CSS as you make changes. Run gulp by itself to generate optimized CSS.

If you’re looking for a more robust development environment, consider using Raven Dev Environment.