Documentation

Getting started

Step 1

$ yarn add timble/illusion --dev

Step 2

Include Modernizr and at least add JS - No JS detection and flexbox detection if you’re gonna use flexbox.

Step 3

Create a SCSS file, something like:

// Include Normalize before anything else
@import "node_modules/normalize";

// Define your variables before loading Illusion
@import: "variables";

// Load Illusion
@import "node_modules/illusion";

// Start writing code
.foo {
  @include gallery(4);
}

Recommendations

Clean CSS

Use grunt-contrib-cssmin to eliminate duplicate code. Duplicate code is generated because Illusion doesn’t know whether you already used a specific mixin in an element when you use it again.

Autoprefixer

Use autoprefixer to add the browser prefixes you need for your project.

Base styling

To stop all the copy pasting in this world we added some base styling in two levels.

Level 1: Extendalize

The first level we call “Extendalize” and it basically extends Normalize styling the way we think it should be.

By default the extendalize styling is set to false and can be configured using variables.

Enable all extendalize features:

$illusion-extendalize: true;

Enable individual extendalize features:

$illusion-extendalize: false;
$illusion-extendalize-boxsizing: true;
$illusion-extendalize-svg: true;

Disable individual extendalize features:

$illusion-extendalize: true;
$illusion-extendalize-image: false;
$illusion-extendalize-paragraph: false;

Level 2: Element styling

The second level adds default styling for certain elements. The following elements are available:

Body fallback

For browsers that do not support CSS calc() there’s an option to set the body width to make it look better on those older browsers.

Enable the body fallback styling by setting the following variable:

$illusion-body-fallback: true;

All options.

Forms

Default form styling is available.

$illusion-form: true;

All options.

Mixins

All settings are controlled by setting your own variables and load them before the Illusion variables are loaded.

Illusion comes with a great mixin and function library. All the parameters inside mixins are overwriteable.

@mixin breakpoint

Media querie shortcut. Sets a temporary global $inside-breakpoint variable to be used inside other mixins.

Arguments

Name Type Default Description
width string - min-width amount
width--max string false max-width amount for (min-width) and (max-width) media query

SCSS

.foo {
  @include breakpoint($bravo) {
    width: auto;
  }
}

CSS

@media screen and (min-width: 560px) {
  .foo {
    width: auto;
  }
}

@mixin button

Can be used inside your own @mixin button(); and other elements that should behave like a button. No styling is provided.

Arguments

Name Type Default
appearance string none
display string inline-block
vertical-align string  
cursor string pointer

SCSS

.foo {
  @include button-structure;
}

CSS

.foo {
  -webkit-appearance: none;
  display: inline-block;
  vertical-align: middle;
  cursor: pointer;
}

@mixin clearfix

Clears top and bottom floats.

Still using single colon for better browser compatibility.

Arguments

Name Type Default Description
reset boolean false Hides the pseudo elements. Useful when using flex-wrap

SCSS

.bar {
  @include clearfix;
}

.foo .bar {
  @include clearfix(reset);
}

CSS

.bar:before, .bar:after {
  display: table;
  content: " ";
}

.bar:after {
  clear: both;
}

.foo .bar:before, .foo .bar:after {
  display: none;
}

@mixin collapse

Use as direct child of @include span element. Make sure there’s no padding on the parent element

Arguments

Name Type Default Description
sides string both Choose which side(s) to collapse gutter. Defaults to ‘both’
multiplier number 1 Defaults to 1 and can be set to any number dividable by 0.5
fromto list false to false Set starting and stopping breakpoints. Accepts single value: @include collapse(both, 1, $bravo) or list: @include collapse(both, 1, $bravo to $charlie). The second (to) value only means that Illusion is not adding more media queries. The styling is not being reset on this ‘to’ breakpoint
gutter string false Custom gutter value for Illusion to calculate (calc()) with.

SCSS

.foo {
  @include collapse();
}

CSS

.foo {
  margin-right: calc((-1 * 1) * 16px);
  margin-left: calc((-1 * 1) * 16px);
}

@media screen and (min-width: 560px) {
  .foo {
    margin-right: calc((-1 * 1) * 24px);
    margin-left: calc((-1 * 1) * 24px);
  }
}

@media screen and (min-width: 1024px) {
  .foo {
    margin-right: calc((-1 * 1) * 32px);
    margin-left: calc((-1 * 1) * 32px);
  }
}

@mixin container

Shouldn’t be nested. Adds clearfix when used without flexbox and removes clearfix when used as flexbox. Adds a max-width and left and right padding following the responsive gutters.

Arguments

Name Type Default Description
type string $illusion-grid-container-type Choose between clearfix (for floats) or flexbox container. Defaults to clearfix container.
alignment string center Align container to left, center or right

Dependencies

For flexbox to work properly it uses Modernizr .flexbox.flexwrap

SCSS

.foo {
  @include container;
}

CSS

.foo {
  margin-left: auto;
  margin-right: auto;
  max-width: 1176px;
  padding-left: 16px;
  padding-right: 16px;
}

.foo:before, .foo:after {
  display: table;
  content: " ";
}

.foo:after {
  clear: both;
}

@media screen and (min-width: 560px) {
  .foo {
    padding-left: 24px;
    padding-right: 24px;
  }
}

@media screen and (min-width: 1024px) {
  .foo {
    padding-left: 32px;
    padding-right: 32px;
  }
}

@mixin content-block

Adds a margin bottom to element and removes the margin bottom from the last element in it’s parent.

Arguments

Name Type Default Description
spacing string $line-height The amount of margin
location string bottom Can be either bottom or top

SCSS

.foo {
  @include content-block;
}

CSS

.foo {
  margin-bottom: 24px;
}

.foo:last-child {
  margin-bottom: 0;
}

@mixin coverall

Cover entire closest element that has position: absolute or relative.

Arguments

Name Type Default Description
offset string 0 Default offset for all four directions
top string true Separate offset for top
right string true Separate offset for right
bottom string true Separate offset for bottom
left string true Separate offset for left
position string absolute Defaults to absolute
reset string false Resets all properties

SCSS

.foo {
  @include coverall;
}

CSS

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

@mixin flexbox

Style only when browser supports flexbox.

Arguments

Name Type Default Description
horizontal string $flexbox-horizontal Flex when viewport reached this amount
vertical string $flexbox-vertical Flex when viewport reached this amount

Dependencies

For flexbox to work properly it uses Modernizr .flexbox and .flexboxlegacy

SCSS

.foo {
  @include flexbox($bravo, $charlie) {
    display: flex;
  }
}

SCSS

@media (min-width: 560px) and (min-height: 768px) {
  .flexbox .foo,
  .flexboxlegacy .foo {
    display: flex;
  }
}

@mixin fluid-type

Fluid font-size between breakpoints

Arguments

Name Type Default Description
min-value string $fluid-type-min-value The minimum font-size
max-value string $fluid-type-max-value The maximum font-size
min-screen string $fluid-type-min-screen Breakpoint for fluid-type to kick in
max-screen string $fluid-type-max-screen Breakpoint for fluid-type to stop

SCSS

.foo {
  @include fluid-type(16px, 24px);
}

SCSS

.foo {
  font-size: 16px;
}

@media screen and (min-width: 560px) {
  .foo {
    font-size: calc(1.724137931vw + 6.3448275862px);
  }
}

@media screen and (min-width: 1024px) {
  .foo {
    font-size: 24px;
  }
}

@mixin font-smoothing

Only use for light text on dark backgrounds.

SCSS

.foo {
  @include font-smoothing;
}

CSS

.foo {
  -webkit-font-smoothing: antialiased;
  -moz-osx-font-smoothing: grayscale;
}

Shortcut to create gallery-style grids. Adds clearing on nth-child items.

Arguments

Name Type Default Description
span list - Set how many columns should be spanned. Accepts single value: @include gallery(6) or list: @include gallery(4 of 12). Amount of columns defaults to $illusion-grid-container
fromto list false to false Set starting and stopping breakpoints. Accepts single value: @include gallery(6, $bravo) or list: @include gallery(6, $bravo to $charlie). The second (to) value only means that Illusion is not adding more media queries. The styling is not being reset on this ‘to’ breakpoint
multiplier number 1 Gutter multiplier. defaults to 1 and can be set to any number dividable by 0.5
bottom boolean true Set to false if you don’t want bottom gutters
defaults boolean true If set to false the mixin won’t add the float and margin property on :first-child and :last-child for cleaner code
gutter string false Custom gutter value for Illusion to calculate (calc()) with.

SCSS

.foo {
  @include gallery(4);
}

CSS

.foo {
    width: calc((100% - 32px) / 3);
    margin-left: calc(16px);
    margin-bottom: calc(16px);
    float: left;
}

.foo:nth-child(3n) {
    margin-right: -1px;
}

.foo:nth-child(3n+1) {
    margin-left: 0;
    clear: left;
}

.foo:first-child {
    margin-left: 0;
}

@media screen and (min-width: 560px) {
    .foo {
        width: calc((100% - 48px) / 3);
        margin-left: calc(24px);
        margin-bottom: calc(24px);
    }

    .foo:nth-child(n) {
        clear: none;
        margin-left: calc(24px);
        margin-right: 0;
    }

    .foo:nth-child(3n) {
        margin-right: -1px;
    }

    .foo:nth-child(3n+1) {
        margin-left: 0;
        clear: left;
    }
}

@media screen and (min-width: 1024px) {
    .foo {
        width: calc((100% - 64px) / 3);
        margin-left: calc(32px);
        margin-bottom: calc(32px);
    }

    .foo:nth-child(n) {
        clear: none;
        margin-left: calc(32px);
        margin-right: 0;
    }

    .foo:nth-child(3n) {
        margin-right: -1px;
    }

    .foo:nth-child(3n+1) {
        margin-left: 0;
        clear: left;
    }
}
Breakpoints use

It’s best not to use this mixin inside a breakpoint since the mixin itself is creating media queries. So to avoid creating a LOT of duplicate code rather use the mixin itself to create breakpoints:

// BAD
.foo {
    @include gallery(6);
    @include breakpoint($bravo) {
        @include gallery(4);
    }
}

// GOOD
.foo {
    @include gallery(6, 0 to $bravo);
    @include gallery(4, $bravo to $charlie, $defaults: false);
    @include gallery(3, $charlie to $delta, $defaults: false);
}

// $defaults set to false on all except first mixin
// While this is not mandatory it is adviced to minimize compiled code

@mixin hover

Shortcut for styling both hover and focus.

SCSS

.foo {
  @include hover {
    text-decoration: underline;
  }
}

CSS

.foo:hover, .foo:focus {
  text-decoration: underline;
}

@mixin js-disabled

If you need styling that only applies to browsers that do not support JavaScript. Progressive enhancement for the win!

SCSS

.foo {
  @include js-disabled {
    display: block;
  }
}

CSS

.no-js .foo {
  display: block;
}

@mixin js-enabled

If you need styling that only applies to browsers that support JavaScript. Progressive enhancement for the win!

SCSS

.foo {
  @include js-enabled {
    display: none;
  }
}

CSS

.js .foo {
  display: none;
}

@mixin modernizr

If you need styling that only applies to browsers that support certain features. Progressive enhancement for the win!

Arguments

Name Type Default Description
classes list - Comma separated list of modernizr classes

SCSS

.foo {
  @include modernizr(csscalc, flexbox) {
    width: calc(100% - 20px);
    display: flex;
  }
}

CSS

.csscalc.flexbox .foo {
  width: calc(100% - 20px);
  display: flex;
}

@mixin no-flexbox

Style only when browser does not support flexbox.

Dependencies

For flexbox to work properly it uses Modernizr .flexbox and .flexboxlegacy

SCSS

.foo {
  @include no-flexbox {
    display: table;
  }
}

SCSS

.no-flexbox .foo,
.no-flexboxlegacy .foo {
  display: table;
}

@mixin pseudo

Arguments

Name Type Default Description
pseudo string after Either before or after
parent-position string relative Set to false if you don’t want to set the parent’s position. Set to fixed or absolute if you don’t want it to be relative
position string absolute Set to false if you don’t want to set the pseudo element’s position. Set to static or relative if you don’t want it to be absolute
content string " " Defaults to a space but can be anything you want it to be
display string block Defaults to display: block but can be anything you want it to be

SCSS

.foo {
  @include pseudo(after) {
    width: 24px;
    height: 24px;
    background: grey;
  }
}

CSS

.foo {
  position: relative;
}

.foo:after {
  position: absolute;
  content: " ";
  display: block;
  width: 24px;
  height: 24px;
  background: grey;
}

@mixin ratio-block

Create blocks that keep set aspect ratio. Blocks will grow when content exceeds the content area. To stop this add an absolute positioned child the the ratio block.

Arguments

Name Type Default Description
ratio list 16 by 9 Width to height ratio
overflow string hidden Hides overflowing content when an absolute positioned child exceeds the content area

SCSS

.foo {
  @include ratio-block(4 to 3);
}

CSS

.foo:before {
  display: block;
  float: left;
  content: " ";
  padding-top: 75%;
}

.foo:after {
  content: " ";
  clear: left;
  display: table;
}

@mixin reset

Arguments

Name Type Default
margin string 0
padding string 0
list-style string none
border string none
background string transparent

SCSS

.foo {
  @include reset;
}

CSS

.foo {
  margin: 0;
  padding: 0;
  list-style: none;
  border: none;
  background: transparent;
}

@mixin row

Arguments

Name Type Default Description
type string $illusion-grid-container-type Choose between clearfix (for floats) or flexbox container. Defaults to clearfix container.

SCSS

.foo {
  @include row();
}

CSS

.foo:before, .foo:after {
  display: table;
  content: " ";
}

.foo:after {
  clear: both;
}

@mixin shift

Visually change the order of elements.

Arguments

Name Type Default Description
shift list - Set how many columns should be shifted. Accepts single value: @include shift(2) or list: @include shift(3 of 12). Amount of columns defaults to $illusion-grid-container
fromto list false to false Set starting and stopping breakpoints. Accepts single value: @include shift(6, $bravo) or list: @include shift(6, $bravo to $charlie). The second (to) value only means that Illusion is not adding more media queries. The styling is not being reset on this ‘to’ breakpoint
multiplier number 1 Gutter multiplier. defaults to 1 and can be set to any number dividable by 0.5
defaults boolean true If set to false the mixin won’t add the position property
gutter string false Custom gutter value for Illusion to calculate (calc()) with.

SCSS

.foo {
  @include shift(4);
}

CSS

.foo {
    left: calc(((100% - 16px) / 2) + 16px);
    position: relative;
}

@media screen and (min-width: 560px) {
    .foo {
        left: calc(((100% - 24px) / 2) + 24px);
    }
}

@media screen and (min-width: 1024px) {
    .foo {
        left: calc(((100% - 32px) / 2) + 32px);
    }
}
Breakpoints use

It’s best not to use this mixin inside a breakpoint since the mixin itself is creating media queries. So to avoid creating a LOT of duplicate code rather use the mixin itself to create breakpoints:

// BAD
.foo {
    @include shift(6);
    @include breakpoint($bravo) {
        @include shift(4);
    }
}

// GOOD
.foo {
    @include shift(6, 0 to $bravo);
    @include shift(4, $bravo to $charlie, $defaults: false);
    @include shift(3, $charlie to $delta, $defaults: false);
}

// $defaults set to false on all except first mixin
// While this is not mandatory it is adviced to minimize compiled code

@mixin spacing

Add spacing that follows the responsive breakpoints so you don’t have to worry about that yourself.

Arguments

Name Type Default Description
sides list all minus none Accepts all minus [top, right, bottom, left], vertical, horizontal, top, right, bottom and left
type text padding Accepts padding or margin
multiplier number 1 Defaults to 1 and can be set to any number dividable by 0.5
fromto list false to false Set starting and stopping breakpoints. Accepts single value: @include spacing(6, padding, 1, $bravo) or list: @include spacing(6, padding, 1, $bravo to $charlie). The second (to) value only means that Illusion is not adding more media queries. The styling is not being reset on this ‘to’ breakpoint
lastchildnone boolen false If set to true :last-child will not have the set spacing
minus number 0 Substract an amount of pixels off of the spacing. If an element has a 2 pixel border you’d best substract 2 pixels form the spacing to stay inside the 8 pixel grid

SCSS

.foo {
  @include spacing;
}

CSS

.foo {
  padding-top: 16px;
  padding-right: 16px;
  padding-bottom: 16px;
  padding-left: 16px;
}

@media screen and (min-width: 560px) {
  .foo {
    padding-top: 24px;
    padding-right: 24px;
    padding-bottom: 24px;
    padding-left: 24px;
  }
}

@media screen and (min-width: 1024px) {
  .foo {
    padding-top: 32px;
    padding-right: 32px;
    padding-bottom: 32px;
    padding-left: 32px;
  }
}

@mixin span

…

Arguments

Name Type Default Description
span list - Set how many columns should be spanned. Accepts single value: @include span(6) or list: @include span(4 of 12). Amount of columns defaults to $illusion-grid-container
fromto list false to false Set starting and stopping breakpoints. Accepts single value: @include span(6, $bravo) or list: @include span(6, $bravo to $charlie). The second (to) value only means that Illusion is not adding more media queries. The styling is not being reset on this ‘to’ breakpoint.
multiplier number 1 Gutter multiplier. defaults to 1 and can be set to any number dividable by 0.5
bottom boolean false When set to true it also adds a bottom gutter
defaults boolean true If set to false the mixin won’t add the float and margin property on :first-child and :last-child
omega number null Used by the gallery mixin
gutter string false Custom gutter value for Illusion to calculate (calc()) with.

SCSS

.foo {
  @include span(6);
}

CSS

.foo {
  width: calc((100% - 16px) / 2);
  margin-left: calc(16px);
  float: left;
}

.foo:first-child {
  margin-left: 0;
}

.foo:last-child {
  margin-right: -1px;
}

@media screen and (min-width: 560px) {
  .foo {
    width: calc((100% - 24px) / 2);
    margin-left: calc(24px);
  }
}

@media screen and (min-width: 1024px) {
  .foo {
    width: calc((100% - 32px) / 2);
    margin-left: calc(32px);
  }
}
Breakpoints use

It’s best not to use this mixin inside a breakpoint since the mixin itself is creating media queries. So to avoid creating a LOT of duplicate code rather use the mixin itself to create breakpoints:

// BAD
.foo {
    @include span(6);
    @include breakpoint($bravo) {
        @include span(4);
    }
}

// GOOD
.foo {
    @include span(6, 0 to $bravo);
    @include span(4, $bravo to $charlie, $defaults: false);
    @include span(3, $charlie to $delta, $defaults: false);
}

// $defaults set to false on all except first mixin
// While this is not mandatory it is adviced to minimize compiled code

@mixin svg-background

Add an SVG icon as background to an element. Especially useful when trying to override 3rd party generated markup.

Arguments

Name Type Default Description
svg string - Accepts anything that nomally goes inside the <svg></svg> element. Although try to only use small single element SVG files for performance. Only use if you can’t use a real SVG instead
color string $svg-background-color Color of the SVG. SVGs can only be one color
width number $svg-background-width The width the SVG background should be displayed as
height number $svg-background-height The height the SVG background should be displayed as. Set to false if it’s the same as width
viewboxWidth number $svg-background-viewboxWidth The actual viewboxWidth number. See original SVG file for this number
viewboxHeight number $svg-background-viewboxHeight The actual viewboxHeight number. See original SVG file for this number. Set to false if it’s the same as width
background-position string $svg-background-position SVG background-position
background-repeat string $svg-background-repeat SVG background-repeat

SCSS

.foo {
  @include svg-background('<g transform="matrix(2.18679,0,0,2.18679,5.43964,-0.0421697)"><path d="M5.9 5.3L0.5 0.1C0.4 0 0.2 0 0.1 0.1 0 0.2 0 0.4 0.1 0.5L5.2 5.5 0.1 10.5C0 10.6 0 10.8 0.1 10.9 0.2 11 0.2 11 0.3 11 0.4 11 0.5 11 0.5 10.9L5.9 5.7C6 5.6 6 5.4 5.9 5.3Z"/></g>', black, 16);
}

CSS

.foo {
  background-image: url('data:image/svg+xml;utf-8,<svg style="fill: black;" xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24"><g transform="matrix(2.18679,0,0,2.18679,5.43964,-0.0421697)"><path d="M5.9 5.3L0.5 0.1C0.4 0 0.2 0 0.1 0.1 0 0.2 0 0.4 0.1 0.5L5.2 5.5 0.1 10.5C0 10.6 0 10.8 0.1 10.9 0.2 11 0.2 11 0.3 11 0.4 11 0.5 11 0.5 10.9L5.9 5.7C6 5.6 6 5.4 5.9 5.3Z"/></g></svg>');
  background-position: center;
  background-repeat: no-repeat;
  background-size: 16px 16px;
}

@mixin transitation

Shortcut to set one or more transition properties.

Arguments

Name Type Default Description
transitions list - Comma separated list. Each item can have three sub-items and will fall back to the default values.

SCSS

.foo {
  @include transition(opacity 1s, transform);
}

CSS

.foo {
  transition: opacity 1s cubic-bezier(0.195, 0.4, 0.45, 0.785) 0ms, transform 0.2s cubic-bezier(0.195, 0.4, 0.45, 0.785) 0ms;
}

@mixin triangle

CSS only triangles using borders.

Arguments

Name Type Default Description
direction string right Direction of triangle
size string 4px Size of triangle
color string false Defaults to text color

SCSS

.foo {
  @include triangle(top, 4px, blue);
}

CSS

.foo {
  border-left: 4px solid transparent;
  border-right: 4px solid transparent;
  border-bottom: 4px solid;
  border-bottom-color: blue;
}

@mixin visually-hidden

Visually hide or show elements while keeping the element accessible for screenreaders.

Arguments

Name Type Default
position string absolute
overflow string hidden
backface-visibility string hidden
clip string rect(0 0 0 0)
height string 1px
width string 1px
margin string -1px
padding string 0
border string none

SCSS

.foo {
  @include visually-hidden;
}

CSS

.foo {
  position: absolute;
  overflow: hidden;
  backface-visibility: hidden;
  clip: rect(0 0 0 0);
  height: 1px;
  width: 1px;
  margin: -1px;
  padding: 0;
  border: 0;
}

@mixin visually-shown

Visually show elements that were visually hidden before.

Arguments

Name Type Default
position string static
overflow string visible
backface-visibility string visible
clip string auto
height string auto
width string auto
margin string 0
padding string 0
border string none

SCSS

.foo {
  @include visually-shown;
}

CSS

.foo {
  position: static;
  overflow: visible;
  backface-visibility: visible;
  clip: auto;
  height: auto;
  width: auto;
  margin: 0;
  padding: 0;
  border: 0;
}

Functions

@function spacing

Returns set spacing or calculate current spacing when inside breakpoint

Accepts a value of 0.5, 1 or 2. If used in @include breakpoint it uses that current gutter. Also possible to define which ‘size’ it should use.

SCSS

@include breakpoint($charlie) {
  padding-top: spacing();
}

CSS

@media screen and (min-width: 560px) {
  .foo {
    padding-top: 24px;
  }
}