Installation & Usage #

Integrating Rucksack into your workflow is easy. It’s built on PostCSS, which provides plugins for most build tools. You can also compile CSS directly on the command line, or with the JavaScript API.

With Gulp

Use gulp-postcss

const gulp = require('gulp');
const postcss = require('gulp-postcss');
const rucksack = require('rucksack-css');

gulp.task('rucksack', () => {
  return gulp.src('src/*.css')
    .pipe(postcss([ rucksack() ]))
    .pipe(gulp.dest('dist'));
});

With Grunt

Use grunt-postcss

grunt.initConfig({
  postcss: {
    options: {
      processors: [
        require('rucksack-css')()
      ]
    },
    dist: {
      src: 'css/*.css'
    }
  }
});

Command Line

Use Rucksack on the command line with postcss-cli

$ npm i postcss-cli -g

postcss.config.js

module.exports = {
  use: [ 'rucksack-css' ]
};

$ postcss "input.css" -o 'output.css'

Javascript API

Since Rucksack is just a PostCSS plugin, you can also use it in JS/Node directly, via the PostCSS API

const postcss = require('postcss');
const rucksack = require('rucksack-css');

postcss([ rucksack() ])
  .process(css, { from: 'src/style.css', to: 'style.css' })
  .then(result => {
      fs.writeFileSync('style.css', result.css);
      if ( result.map ) fs.writeFileSync('style.css.map', result.map);
  });

See the PostCSS Docs for examples for your environment.

With Stylus

Rucksack can be used as a Stylus plugin with PostStylus

stylus(css).use(poststylus('rucksack-css'))

See the PostStylus Docs for more examples for your environment.

Options #

Rucksack is fully modular, you can turn any of its features on or off to customize it to your needs. Just pass the feature name and a boolean during initialization in your build tool. By default core features are set to true, and optional addons are set to false.

For example:

// Set in build tool
.rucksack({
  clearFix: false,
  fallbacks: true
});

Core feature toggles

All default to true.

• responsiveType

• shorthandPosition

• quantityQueries

• alias

• inputPseudo

• clearFix

• fontPath

• hexRGBA

• easings

Addon toggles

All default to false.

• fallbacks

• autoprefixer

Error reporting

Enable reporting, which outputs verbose errors and messages from all of the plugins used inside Rucksack to your console, with the reporter flag. Defaults to false.

Responsive Typography #

Create automagical fluid typography with a new responsive property on font-size. All the type on this site is responsive, resize your browser to see it in action!

Quick start

Rucksack’s responsive typography is fully adjustable, but all you need to get started is to specify responsive as a font-size.

.foo {
  font-size: responsive;
}

Specifying parameters

You’ll probably want to change those defaults and have some control over the bounds of a font size. The best way to do this is with a new shorthand syntax in font-size, and a new property called font-range. Font range specifies the viewport widths between which the font size is fluid, outside of this range the font sizes are set to min/max values.

The format of each property is very simple

font-size: responsive [min-font-size] [max-font-size]
font-range: [lower-bound] [upper-bound]

For example

html {
  font-size: responsive 12px 21px;
  font-range: 420px 1280px;
}

All values can be in px, rem, or em.

Expanded syntax

You can also specify all of these values with independent properties

html {
  font-size: responsive;
  min-font-size: 12px;
  max-font-size: 21px;
  lower-font-range: 420px;
  upper-font-range: 1280px;
}

Output

Rucksack’s responsive typography outputs complex calc and vw based font-sizes, along with media queries to set the range between which a font size is fluid.

html {
  font-size: calc(12px + 9 * ( (100vw - 420px) / 860));
}

@media screen and (max-width: 420px) {
  html {
    font-size: 12px;
  }
}

@media screen and (min-width: 1280px) {
  html {
    font-size: 21px;
  }
}

With the calc expression above being equivalent to

min-size + (min-size - max-size) * ( (100vw - min-width) / ( max-width - min-width) )

Defaults

To get started you only need to specify font-size: responsive;, all other properties have sane defaults.

min-font-size: 14px
max-font-size: 21px
lower-font-range: 420px
upper-font-range: 1280px

Supporting legacy browsers

Rucksack’s responsive typography works on all modern browsers (IE9+). Legacy browsers will ignore the output font-size, so it’s very easy to provide a static fallback.

html {
  font-size: 16px;
  font-size: responsive;
}

Shorthand Positioning #

Rucksack brings the shorthand methods used by properties like margin and padding to position offsets. The same syntaxes apply

- position: [type] [all];
- position: [type] [y] [x];
- position: [type] [top] [x] [bottom];
- position: [type] [top] [right] [bottom] [left];

Input

.foo {
  position: absolute 0;
}

.bar {
  position: relative 20% auto;
}

.baz {
  position: fixed 0 20px 10px;
}

Output

.foo {
  position: absolute;
  top: 0;
  right: 0;
  bottom: 0;
  left: 0;
}

.bar {
  position: relative;
  top: 20%;
  right: auto;
  bottom: 20%;
  left: auto;
}

.baz {
  position: fixed;
  top: 0;
  right: 20px;
  bottom: 10px;
  left: 20px;
}

Quantity Pseudo-Selectors #

Rucksack adds pseudo-selectors to select and style elements based on their quantity. Use them to build powerful, responsive, content-driven designs.

:at-least

Applies if there are a certain number of items or more

li:at-least(4) {
  color: blue;
}

:at-most

Applies if there are a certain number of items or less

li:at-most(4) {
  color: blue;
}

:between

Applies to all items between a certain range

li:between(4, 6) {
  color: blue;
}

:exactly

Applies when there are exactly a number of items

li:exactly(4) {
  color: blue;
}

How it works

The quanitity based pseudo-selectors style elements based on their sibling count, using constructions like

li:nth-last-child(n+4),
li:nth-last-child(n+4) ~ li

For a more in-depth look at how this works and how to take advantage of it in your designs, read the recent article on A List Apart - Quantity Queries for CSS.

Input Pseudo-Elements #

Rucksack adds new pseudo-elements that allow you to easily style the inner elements of HTML5 inputs across browsers. Currently the only element supported is the range input (and ::placeholder if you enable automatic vendor prefixing), more will be added as browser vendors open up their APIs.

Note that the rules in the output generated (see below) are duplicated, since if a browser finds a single selector it doesn’t understand in a group the whole group is ignored (see Selectors Level 3).

Range Elements

Style the notoriously tricky range input with ::track and ::thumb. Track targets the ‘line’, while thumb targets the ‘button’. They can be applied to any range element, or at the root of your stylesheet for global styling.

Input

input[type="range"]::track {
  background: #9d9d9d;
  height: 3px;
}

input[type="range"]::thumb {
  background: #4286be;
  width: 16px;
  height: 8px;
}

Output

input[type="range"]::-webkit-slider-runnable-track {
  -webkit-appearance: none;
  background: #9d9d9d;
  height: 3px;
}

input[type="range"]::-moz-range-track  {
  -moz-appearance: none;
  background: #9d9d9d;
  height: 3px;
}

input[type="range"]::-ms-track  {
  background: #9d9d9d;
  height: 3px;
}

input[type="range"]::-webkit-slider-thumb {
  -webkit-appearance: none;
  background: #4286be;
  width: 16px;
  height: 8px;
}

input[type="range"]::-moz-range-thumb {
  -moz-appearance: none;
  background: #4286be;
  width: 16px;
  height: 8px;
}

input[type="range"]::-ms-thumb {
  background: #4286be;
  width: 16px;
  height: 8px;
}
input[type="range"] {
  -webkit-appearance: none;
}
input[type=range]::-moz-focus-outer {
  border: 0;
}

The -webkit-appearance: none; and -moz-appearance: none; declarations are added to relevant elements so that your custom styles are properly applied. Note that this means that for webkit (Chrome, etc) you must style both ::track and ::thumb, since the appearance must be set on the root element.

The additional ::-moz-focus-outer rule simply removes the dotted outline around the element on some versions of firefox.

Native Clearfix #

Rucksack bundles up common clearfix methods into native methods of the clear property. A ‘clearfix’ is a method of making a parent element self-clear it’s children, so floats are contained.

Two new methods are added, fix and fix-legacy. Both achieve the same outcome, with different levels of browser support. fix outputs cleaner code and is all that is needed for IE8+, fix-legacy support IE6/7.

Input

.foo {
  clear: fix;
}

.bar {
  clear: fix-legacy;
}

Output

/* fix */
.foo:after{
  content: '';
  display: table;
  clear: both;
}

/* fix-legacy */
.bar:before,
.bar:after {
  content: '';
  display: table;
}
.bar:after {
  clear: both;
}
.bar {
  zoom: 1;
}

Font Src Expansion #

Rucksack provides a shortcut method to generate bulletproof src sets in @font-face, with a new font-path property. Just set the path to your font files in font-path, and it will output a src set based on the FontSpring syntax. Note that font-path must be to the font file, not just the directory containing the files.

Input

@font-face {
  font-family: 'My Font';
  font-path: '/my/font/file';
  font-weight: normal;
  font-style: normal;
}

Output

@font-face {
  font-family: 'My Font';
  src: url("/my/font/file.eot");
  src: url("/my/font/file.eot?#iefix") format('embedded-opentype'),
       url("/my/font/file.woff") format('woff'),
       url("/my/font/file.ttf") format('truetype'),
       url("/my/font/file.svg") format('svg');
  font-weight: normal;
  font-style: normal;
}

Hex RGBA Shortcuts #

Rucksack provides an easy shortcut to add an alpha channel to any hex color. Just add the hex value you want to convert in place of the RGB value in rgba(). The hex is converted to RGB and output as a proper rgba() property.

Input

.foo {
  color: rgba(#fff, 0.8);
}

Output

.foo {
  color: rgba(255,255,255, 0.8);
}

Property Aliases #

Rucksack allows you to set aliases for long property names and save some of those precious keystrokes. To set an alias simply add it to the @alias rule in the format of [alias]: [property];. Aliases are global in a stylesheet, so it’s a good idea to have just a single @alias rule in your project and specify all aliases in one place.

Input

@alias {
  fs: font-size;
  fw: font-weight;
}

.foo {
  fs: 16px;
  fw: bold;
}

Output

.foo {
  font-size: 16px;
  font-weight: bold
}

Note: Using aliases inside propety values is not supported

@alias {
  op: opacity;
}

.foo {
  /* Not supported! */
  transition: op 300ms ease;
}

All The Easings #

Rucksack comes with a whole library of modern easing functions for you to instantly use in CSS transitions and animations. The new easings are translated to cubic-bezier() functions on output that CSS can natively understand.

Input

.foo {
  transition: all 250ms ease-in-cubic;
}

Output

.foo {
  transition: all 250ms cubic-bezier(0.55, 0.055, 0.675, 0.19);
}

Legacy Fallbacks #

Rucksack can pass your styles through Laggard, which provides legacy fallbacks for many properties, making old browser support a breeze.

This is an optional add-on, and can be toggled on or off with the fallbacks option, passed to Rucksack on initialization. By default fallbacks is set to false.

var rucksack = require('rucksack-css');

// Set in build tool, etc.
rucksack({
  fallbacks: true
});

Opacity

Generates the appropriate ms filter for achieving transparencies on IE8.

.foo {
  opacity: 0.8;
}

.foo {
  -ms-filter: "progid:DXImageTransform.Microsoft.Alpha(Opacity=80)";
  opacity: 0.8;
}

RGBA

Generates a hexidecimal fallback to rgba() for <IE8

.foo {
   background: rgba(153, 221, 153, 0.8);
}

.foo {
  background: #99DD99;
  background: rgba(153, 221, 153, 0.8);
}

Rem units

Creates a px fallback to rem unit sizing, calculated from the document root (defined in html, :root, or falling back to 16px).

.foo {
  font-size: 2rem;
}

.foo {
  font-size: 32px;
  font-size: 2rem;
}

Pseudo elements

Converts ::pseudo elements to the CSS2-friendly single-colon style.

.foo::before {
  content: '';
  color: blue;
}

.foo:before {
  content: '';
  color: blue;
}

vmin

Creates a vm fallback to the vmin unit for IE9

.foo {
  width: 50vmin;
}

.foo {
  width: 50vm;
  width: 50vmin;
}

will-change

Inserts a 3D acceleration hack to emulate the will-change property, using backface-visibility.

.foo {
  will-change: transform;
}

.foo {
  backface-visibility: hidden;
  will-change: transform;
}

Automatic Prefixing #

Rucksack comes with the option to run your code through Autoprefixer. Autoprefixer automatically applies relevant vendor prefixes based on current browser popularity and property support (from CanIUse).

This is an optional add-on, and can be toggled on or off with the autoprefixer option, passed to Rucksack on initialization. By default autoprefixer is set to false.

var rucksack = require('rucksack-css');

// Set in build tool, etc.
rucksack({
  autoprefixer: true
});

Prefixing

Head over to CanIUse to see what kind of prefixes will be applied for various properties.

.foo {
  display: flex
}

.foo {
  display: -webkit-box;
  display: -webkit-flex;
  display: -ms-flexbox;
  display: flex
}

Cleaning

Autoprefixer also cleans your code of old, unnecessary vendor prefixes.

.foo {
  -webkit-border-radius: 5px;
          border-radius: 5px;
}

.foo {
  border-radius: 5px;
}