Toolkit

Think of Toolkit as your swiss army knife for modern design and development. Those little bits and bobs that make your life easy and you want to reuse throughout projects but never really had a place to put? They're here, and they're designed to make your life happy. Toolkit is broken out into individual pieces, so grab what you want, grab what you need, or grab the lot; the choice is yours.

Table of Contents

1. Basics

• Requirements
• Installation
• Changing Settings
• Extends

1. Art
2. Clearfix
3. Colors

• Tint and Shade
• Luma
• Color Stacks
• Color Scales

1. DRY Mixins
2. Font Helpers

• Enable Ligatures
• Font Face
• Icon Font
• Content Fade In

1. Intrinsic Ratios
2. Kickstart
3. Nested Context
4. Parallax
5. Reset
6. RTL
7. Settings
8. Triangles
9. Center
   • Vertical Center
   • Horizontal Center
   • Absolute Center
10. Viewport
11. Underline
12. Target
13. Set Multiple

Basics

Working with, and understanding how, Toolkit is fairly easy as long as you keep the following in mind:

Requirements

Toolkit is a Sass plugin available both as a Compass Extension or as Bower Package. To use, make sure you have Sass installed. Any Sass compiler that is feature-compatible with Sass 3.3 can be used with Toolkit, so feel free to use whatever you feel is best!

Installation

To install as a Compass extension, add the following to your Gemfile:

gem 'toolkit', '~>2.0'

Then, add require 'toolkit' to your config.rb file and @import "toolkit"; to your Sass file.

To install as a Bower package, run the following:

bower install sass-toolkit --save-dev

Even as an Eyeglass module!

npm install sass-toolkit --save-dev

Changing Settings

All of Toolkit's settings can be changed with a simple mixin. Whenever you would like to change a default, include the following mixin, and from then on out, whenever that default is needed, the value you've changed it to will be used:

@include toolkit-set('setting', value);

Extends

Where appropriate, Toolkit mixins provide an $extend option to allow the shared output of a mixin to be set to an extendable class instead of duplicating the properties. Toolkit is super smart about this and will create the extendable class in place where you first call the mixin, allowing you to not worry about blowing up your cascade if you use it. All mixins that have an extend setting can have a portion of their mixin extended. By default, mixins won't extend, but you can change that by changing their global setting or by passing $extend: true to the mixin.

Documentation Format

Each mixin/function definition looks like the following:

@include clearfix([$extend])

Settings

• 'clearfix extend': false

Mixins start with @include, functions don't. Variables in [brackets] are optional. Settings are global setting variables that provide the defaults for optional variables, with their default.

Art

Create pixel art using CSS Box Shadows! Simply write a string with x for where you'd like a pixel, and where you wouldn't. When you want a new line, simply write \n. The "pixel" size is the size of one pixel and doesn't have to be px. Border radius will apply to each "pixel", as will color.

@include art($art[, $px-size, $color, $radius])

• 'art pixel size': 1px
• 'art color': black
• 'art border radius': 0%

Clearfix

Use a clearfix to ensure a parent element that contains floated children encompasses its children. Toolkit's clearfix is a modern clearfix.

@include clearfix([$extend])

Settings

• 'clearfix extend': false

Colors

Sass comes with a slew of great color functions, made even better by color schemer, but there are a few handy things missing to make working with groups of colors easier

Tint and Shade

While Sass's built in lighten and darken functions are great if you're looking not to change the base color, they aren't what designers think of when they think of lightening or darkening a color. The mental model for those is actually mixing white or black to lighten or darken a color. So, like so many others, we have a tint and shade function that will do just that. Simply pass the color and the amount you want. For instance, if you wanted a red that was 25% lighter or darker than the standard CSS red, you'd do one of the followings:

@include tint($color, $amount)

Settings

• 'tint color': #fff

@include shade($color, $amount)

Settings

• 'shade color': #000

Luma

Luma represented the brightness in an image (the "black-and-white" or achromatic portion of the image). As human vision is much more sensitive to luminance ("black and white") than it is to chromatic differences ("colors"), luma provides an effective means of determining how a human will react to the relative brightness of a color. The Luma functions are based on the conversion to the YIQ color space, with Y being luma (also, the only component used in black-and-white televisions). The luma function provided will return the luma value for a color, and the additional helpers can be used for common tasks related to luma, such as if one color's luma is greater than and equal to or less than or equal to a second colors, and the difference between two colors' luma.

@include luma($color)

@include luma-gte($color1, $color2)

@include luma-lte($color1, $color2)

@include luma-diff($color1, $color2)

Color Stacks

One technique for working with color that is very useful is to create color stacks that get either lighter or darker as they go, allowing me to easily create full color pallets with only a handful of base colors and then only needing to remember those base colors. These are called color stacks, and making them with Toolkit is super easy. A sample color stack, if written by hand, may look something like the following:

$red: red, #ff3f3f, #ff7f7f, #ffbfbf, #ffd8d8, #fff2f2;

This is a color stack for red that gets tinted as it goes (25%, 50%, 75%, 85%, 90%). To make figuring these out easier, there is the color-stack function that takes two required parameters, the main color you want to use and the secondary color you want to use (in the case of shading red, the main color would be red and the secondary color would be black), and a variable number of arguments of what percent you want them mixed. Tint stacks, shade stacks, and tint to shade stacks are also available.

@include color-shade($main, $secondary [, $amounts...])

Settings

• 'color stack amounts': 25% 50% 75% 85% 90%

@include tint-stack($main [, $amounts...])

Settings

• 'tint color': #fff
• 'color stack amounts': 25% 50% 75% 85% 90%

@include shade-stack($main [, $amounts...])

Settings

• 'shade color': #000
• 'color stack amounts': 25% 50% 75% 85% 90%

@include tint-shade-stack($main [, $amounts...])

Settings

• 'tint color': 75% 50% 25%
• 'shade color': #000
• 'tint shade amounts': 75% 50% 25%

Color Scales

Color scales allow you to step from one color to another in even steps. Color scale will scale your first color to your second color evenly by hue, saturation, lightness, and alpha. Hue will take the fastest path around the color wheel

@include color-scale($main, $secondary [, $steps...])

Settings

• 'color scale steps': 6

DRY Mixins

The pattern that inspired the A List Apart article DRY-ing Out Your Sass Mixins, now available for you to use in your projects! The full writeup on the why can be found in the article, and examples can be found all throughout Toolkit.

@include dynamic-extend($id) { @content }

The dynamic-extend mixin is the core mixin for dynamically creating placeholder selectors and extending them directly.

@include mixin-dryer($id [,$extend: true]) { @content }

The mixin-dryer mixin is a one-stop-shop mixin for working with the whole pattern. It wraps the contents of the static portion of the pattern into a single mixin. If you don't think someone would want to use the static mixin on its own, simply drop mixin-dryer into your core mixin and you're good to go! The button example from A List Apart can be written with this mixin as follows:

@mixin button($color, $extend: true) {
  background-color: $color;
  border-color: mix(black, $color, 25%);

  &:hover {
    background-color: mix(black, $color, 15%);
    border-color: mix($black, $color, 40%);
  }

  @include mixin-dryer('button', $extend) {
    border: 1px solid;
    border-radius: 5px;
    padding: .25em .5em;

    &:hover {
      cursor: pointer;
    }
  }
}

Font Helpers

Web fonts are absolutely awesome, but working with them can be a bit tricky