This is a tiny library of mixins and styles for developing large-ish stylesheets with Sass.
I extracted these styles from a bunch of larger-than-average projects I have worked on, as I found I was repeating myself over and over again. There is nothing groundbreaking in here, just a useful collection of snippets to build your own stylesheets with.
This library does not aim to help you write CSS, but better stylesheets. It provides re-usable components and patterns to help you simplify styling common objects on your page.
Note: this is very much a work in progress. Mind the gap.
Installation for Rails 3.1+ projects
Include Rocks in your Gemfile:
Let Bundler install it:
$ bundle install
Make sure your
application.css file is compiled by Sass by renaming it to
application.css.scss. Import the Rocks stylesheets:
Add your own styles and imports below that.
Note if you also include Bourbon in your project, make sure put
@import "bourbon"; before
@import "rocks";, as per its installation
Installation for non-Rails 3.1+ projects
Unsupported so far. I may write a simple installer script one day that automatically copies all the stylesheets into a directory of your choosing. For now, you'll have to do that manually.
If you are using Sass directly, you could try to just add the Rocks gem to
load_path, using something like the following:
Sass::Engine.new(my_stylesheet, :syntax => :scss, :load_path => [ File.join(`bundle show rocks`, 'app', 'assets', 'stylesheets') ] )
This would allow you to
@import 'rocks'; in the
Contains functions and mixins for working with a grid-based layout. The grid is
based on variables
$grid-margin. It provides the
span(n): get a width value for
nnumber of columns.
columns(n): get the total width of a number of columns.
The difference between
columns is inclusion of
It contains the following mixins:
column($span, $with_margin: true): make an element a column, spanning
$spannumber of columns.
container: container for
columnelements. Simply a relatively positioned wrapped with clearfix applied.
rcontainer: container for
rcolumnelements. Contains negative left margin, that counters the left margin of the first
rcolumn($span): same as
columnbut with margin applied to the left, so you don't need to remove margin from the last column in a group.
prepend($span): pad an element with
$spancolumns to the left.
append($span): pad an element with
$spancolumns to the right.
push($span): move an element to the right over
pull($span): move an element to the left over
Contains simple layout helper mixins:
float($dir: 'left'): float en element left or right, including the
display: inlineso often needed for IE.
outdent($selector, $amount, $dir: 'left', $with-padding): make a child element outdented. Useful for a story with some text and an image, where all the text should be beside the image.
align($dir: 'left', $v: $line, $h: $grid-margin, $mirror: false): float an element with margins. Useful for left- or right floating images.
clearfix: clears floated elements inside.
outset-left($gutter: $grid-margin, $with-padding): create an outdent to the left, using a negative margin and opposing padding.
outset-right($gutter: $grid-margin, $with-padding): create an outdent to the right, using a negative margin and opposing padding.
outset($gutter: $grid-marign, $with-padding: true): outdent to both the left and right.
leading($amount: $line): add whitespace before an element.
trailing($amount: $line): add whitespace after an element.
surrounding-lines: adds a single line-height whitespace before and after the element.
voutset-top($amount, $border: 0): vertically outset an element, adding negative margin and positive padding to the top.
voutset-bottom($amount, $border: 0): vertically outset an element, adding negative margin and positive padding to the bottom.
voutset($amount, $border: 0): vertically outset an element by applying negative marings and countering paddings top top and bottom.
voutset-bottom can take both
pixel values as arguments, or a unit-less number. When given a unit-less
number, it will be fed to the
When using any of the
voutset mixins, you can add an optional
argument to reduce the amount of padding that is applied, leaving room for a
border on element while preserving vertical rhythm.
It also contains a plain class
.clearfix that you can use in your HTML. It is
meant, however, to be used with
@extend. When your stylesheet needs a lot of
clearfixes, the end result will contain a lot of duplicated code. Using
@extend .clearfix you can define the class once, and simply apply many
selectors to it.
Provides mixins for common link behaviours:
link-hover: hide underline on normal links, show it on hover and focus.
link-colors($link, $visited, $hover, $active): set all colors at once.
link-colorsto use a single color for all links, but lighten the hover, focus and active styles slightly using the
link-colors-lightenbut using the
darkenfunction instead of
link-press: make a link 'pressable' by offsetting it 1px in its active state.
link-unstyled($color: $color-text): make a link appear as regular text.
link-block($target: .target)make a link work as a block, wrapping multiple elements that will be clickable. The (optional) target selector applies styles to a child element that should appear as a link, by extending
.block-link-target-- which you should define yourself.
Provides basic building blocks for styling lists:
list-no-bullets: removes list bullets.
list-plain: removes bullets and spacing.
list-inline: removes bullets and shows elements inline.
list-horizontal($margin: $grid-margin, $dir: 'left'): floats all chilren to a horizontal list.
list-dl-table($width, $margin: $grid-margin): show a term and its definition (dt and dd) on a single line.
list-image-bullets($img, $padding: $grid-margin, $x: 0, $y: 0): use an image as list bullet using the background-image technique.
Provides a single
reset mixin that reset all styles. You probably want to mix
this into your
body selector, but you could also use it for a local reset in
a specific element.
Defines the following variables:
$line: the base line height of your site. Used in many different places for marigns, paddings and heights to achieve a sensible vertical rhythm. Defaults to
$size-text: the default text size. Defaults to
$color-text: the default text color. Defaults to
Defines the following functions:
lines($n): returns a mutliple of
It defines the following mixins:
rhythm(...): apply various aspects of vertical rhythm in one go, using a combination of arguments. See the inline docs for more information.
text-icon($img, $padding: $grid-margin, $x: 0, $y:0): give an element an icon by setting an image to the background and applying some padding.
text-replace($img, $x: 0, $y: 0, $w: false, $h: false): replace an element's text with an image by setting it to the background. You can optionally specify width, height and background positioning.
See CHANGELOG.md for a full of changes.
Author: Arjan van der Gaag
See the LICENSE file for more information.