Documentation

Getting started

Step 1

$ npm install --save-dev github:marsvaardig/illusion normalize.css

Or with Yarn: yarn add marsvaardig/illusion normalize.css --dev. Add a tag to pin a version, for example github:marsvaardig/illusion#v8.1.3. Illusion installs from GitHub: the illusion package on the npm registry is a different project.

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
@use "node_modules/normalize.css/normalize";

// Load Illusion and pass in your settings
@use "node_modules/illusion/scss/illusion" as * with (
  $illusion-extendalize: true
);

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

Still using @import? Declare your settings as variables before you import node_modules/illusion/scss/illusion.

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.

Settings

All settings are !default variables. Pass them in the with (...) map when you load Illusion with @use, or declare them before @import. The examples on this page write them as plain variable declarations.

Most mixin arguments take their default from an $illusion- variable named after the mixin and the argument, for example $illusion-span-multiplier for the multiplier of @mixin span. All variables.

Grid and breakpoints

Variable Default Description
$alfa, $alfa--plus, $bravo, $charlie, $delta, $echo 320px, 440px, 560px, 768px, 1024px, 1112px Breakpoints. All except $alfa also have a -min version that is 1px smaller for max-width media queries, for example $bravo-min
$illusion-grid-container 12 Amount of columns
$illusion-grid-maxwidth $echo Max width of the content in @mixin container. The largest gutter is added on both sides
$illusion-grid-breakpoints default: 0 / 16px, bravo: $bravo / 24px, delta: $delta / 32px Widths and gutters used by the grid and spacing mixins and functions. Set the width and gutter variables, like $illusion-grid-bravo-gutter, or replace the whole map
$illusion-grid-type float float or flex. Default for $illusion-grid-container-type and $illusion-grid-row-type. @mixin span only adds floats and clears when this is float
$illusion-breakpoint-width-max false Default max-width of @mixin breakpoint
$illusion-breakpoint-type inherit Unit for @mixin breakpoint. inherit keeps the unit of the width; em or rem converts px widths (16px per em)

Type, spacing and color

Variable Default Description
$font-family System font stack Used by the body styling
$font-size 16px Used by the body styling and @mixin fluid-property
$line-height 24px Used by the body styling, @mixin content-block and the form styling
$root-site-font-size 18 Used by px() and fluid() to convert design pixels to rem
$weight-light, $weight-normal, $weight-bold 300, 400, 700 Font weights
$spacing-xs, $spacing-s, $spacing-m, $spacing-l, $spacing-xl 4px, 8px, 16px, 24px, 32px Spacing that doesn’t grow with the responsive gutters
$color-type, $color-error, $color-success, $color-warning, $color-focus, $color-form-input #0b0c0c, #e74c3c, #27ae60, #e67e22, #febd22, #ffffff Colors. The base styling and forms use $color-type, $color-focus and $color-form-input

Fluid values

Variable Default Description
$illusion-fluid-from $alfa Viewport width where fluid() starts scaling
$illusion-fluid-to $illusion-grid-maxwidth + 2 × the largest gutter (1176px) Viewport width where fluid() stops scaling: where @mixin container stops growing
$illusion-fluid-property-min-value, $illusion-fluid-property-max-value, $illusion-fluid-property-min-screen, $illusion-fluid-property-max-screen $font-size, 20px, $bravo, $delta Defaults of @mixin fluid-property
$illusion-fluid-property-clamp false Set to true to let @mixin fluid-property use clamp()

Logical properties

$illusion-logical-properties: true;

Makes @mixin property write logical properties, for example margin-inline-start instead of margin-left. The mixins and base styling that use @mixin property follow automatically. It also makes @mixin cluster use gap, @mixin fluid-property output only a clamp() and @mixin ms output only the custom property version. Which properties are converted is set in the logical properties maps.

Other settings

Variable Default Description
$illusion-layout-flex-gap false Set to true to let @mixin cluster use gap
$illusion-css-variables-prefix '' Prefix for the --spacing custom property that @mixin ms uses. For example il- gives --il-spacing
$illusion-fallback false Set to true to leave out the custom property version of @mixin ms, to test the fallback for older browsers
$illusion-fallback-amount 1.5 Multiplier for the rem fallback of @mixin ms
$illusion-ms-ratio 1.5 Ratio of the modular scale. The steps -4 to 4 are stored in $illusion-ms-sizes, starting from $illusion-ms0 (1)
$illusion-flexbox true Set to false to leave out everything inside @mixin flexbox, to test the fallback
$illusion-display-warnings true Set to false to hide the warnings Illusion shows

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-box-sizing: true;
$illusion-extendalize-svg: true;

Disable individual extendalize features:

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

Extendalize features

Each feature defaults to default, which follows $illusion-extendalize. true turns a feature on even when $illusion-extendalize is false, and false turns it off.

Variable Styles
$illusion-extendalize-box-sizing box-sizing: border-box on html, inherited by all elements
$illusion-extendalize-anchor a: inherits the color, no underline on hover and focus
$illusion-extendalize-address address: margins and normal font style
$illusion-extendalize-body body: margin, font family, size, weight, line height and color
$illusion-extendalize-fieldset fieldset: full width without border, padding and margin. legend: bottom margin
$illusion-extendalize-figure figure: margins
$illusion-extendalize-heading h1 to h6: margins, font size and font weight
$illusion-extendalize-image img: max width, auto height and vertical alignment
$illusion-extendalize-list ul and ol: margins
$illusion-extendalize-paragraph p: margins
$illusion-extendalize-picture picture img: vertical alignment
$illusion-extendalize-svg svg: a fill of $illusion-extendalize-svg-color (currentColor, or set a color) and a width and height of $illusion-extendalize-svg-width and -height (1em) when the SVG has no width or height attribute. Set any of these to false to leave it out. Also hides .svg-sprite

Every element with base styling gets its margins from its own settings, for example $illusion-extendalize-paragraph-margin-bottom. Two settings control the margin at the edge of the parent, so the first or last element adds no space there:

Variable Default Description
$illusion-extendalize-last-children default Set to false to keep the edge margins. default and true remove them
$illusion-extendalize-last-children-direction bottom bottom removes the bottom margin of the last child, top the top margin of the first child. Applies to addresses, figures, headings, lists and paragraphs. legend, .form__group and .multiple-choice only have a bottom margin, so they always reset the last child

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;
Variable Default Description
$illusion-body-fallback-align center Align the body left, center or right
$illusion-body-fallback-width $bravo Width of the body

All options.

Forms

Default form styling is available.

$illusion-form: true;

This styles .form, .form__group, .form__label and .form__input. It also sets a height on all select elements and adds button styling to [type=submit]. Change the class names with $illusion-form-selector, $illusion-form-group-selector, $illusion-form-label-selector and $illusion-form-input-selector.

The custom select and multiple choice styling below are turned on together with $illusion-form. Set their variable to false to leave them out, or to true to use them without the rest of the form styling.

$illusion-form: true;
$illusion-custom-select: false;
$illusion-multiple-choice: false;

All options.

Custom select

Styles a native select inside a .custom-select element and adds a custom arrow. Set $illusion-custom-select-theme to false to leave out the border, font and focus styling. Change the class name with $illusion-custom-select-selector.

Multiple choice

Styles radio buttons and checkboxes inside a .multiple-choice element with a custom box, dot and checkmark. The input needs to be directly followed by its label. Change the class name with $illusion-multiple-choice-selector.

Mixins

All settings are controlled with variables, see Settings.

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

@mixin breakpoint

Media query 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
type string inherit inherit uses the widths as they are. em or rem converts px widths, 16px per em as in all media queries. px converts em and rem widths

SCSS

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

CSS

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

@mixin button-structure

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 middle
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.

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 cluster

Lines up child elements in a wrapping flex row with space between them. By default the space is made with margins on the children. When $illusion-logical-properties or $illusion-layout-flex-gap is true it uses gap instead.

Arguments

Name Type Default Description
margin string 1rem Space between the items
flex-wrap string wrap Wrapping of the items
align-items string center Vertical alignment of the items
justify-content string flex-start Horizontal alignment of the items

SCSS

.foo {
  @include cluster;
}

CSS

.foo {
  display: flex;
  flex-wrap: wrap;
  align-items: center;
  justify-content: flex-start;
  margin-bottom: calc(1rem * -1);
  margin-left: calc(1rem * -1);
}

.foo > * {
  margin-bottom: 1rem;
  margin-left: 1rem;
}
With gap

With $illusion-layout-flex-gap: true the same SCSS compiles to:

.foo {
  display: flex;
  flex-wrap: wrap;
  align-items: center;
  justify-content: flex-start;
  gap: 1rem;
}

@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 Set starting and stopping breakpoints. false uses all 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 flex for a flexbox container, any other value for a clearfix (float) container. Defaults to float
align string center Align container to left, center or right

SCSS

.foo {
  @include container;
}

CSS

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

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

.foo::after {
  clear: both;
}

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

@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 boolean false Resets the offsets to $illusion-coverall-reset-top etc. (auto), and position to $illusion-coverall-reset-position when that is set

SCSS

.foo {
  @include coverall;
}

CSS

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

@mixin flexbox

Style only when browser supports flexbox. Outputs nothing when $illusion-flexbox is false, so you can test the fallback.

Arguments

Name Type Default Description
horizontal string $illusion-flexbox-horizontal Flex when viewport reached this width. Defaults to 0
vertical string $illusion-flexbox-vertical Flex when viewport reached this height. Defaults to 0

Dependencies

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

SCSS

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

CSS

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

@mixin fluid-property

Fluid value between two breakpoints. With $illusion-fluid-property-clamp: true the in-between media query is replaced by a clamp() inside @supports. With $illusion-logical-properties: true only a clamp() is output. Use the same unit for the values and the screens; other units give a warning. See also the fluid() function.

Arguments

Name Type Default Description
property string - The property to set
min-value string $illusion-fluid-property-min-value The minimum value. Defaults to $font-size
max-value string $illusion-fluid-property-max-value The maximum value. Defaults to 20px
min-screen string $illusion-fluid-property-min-screen Breakpoint for fluid-property to kick in. Defaults to $bravo
max-screen string $illusion-fluid-property-max-screen Breakpoint for fluid-property to stop. Defaults to $delta

SCSS

.foo {
  @include fluid-property(font-size, 16px, 24px);
}

CSS

.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. The column count has to divide the grid, for example 2, 3, 4 or 6 of 12; other counts give an error.

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 Set starting and stopping breakpoints. false uses all 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.
includeWidth boolean true Define whether to calculate and return the width.
includeMargin boolean true Define whether to calculate and return the left margin.

SCSS

.foo {
  @include gallery(4);
}

CSS

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

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

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

.foo {
  float: 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) {
    margin-left: calc(24px);
    margin-right: 0;
  }

  .foo:nth-child(n) {
    clear: none;
  }

  .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) {
    margin-left: calc(32px);
    margin-right: 0;
  }

  .foo:nth-child(n) {
    clear: none;
  }

  .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 and added option for focus-within

Arguments

Name Type Default Description
focusWithin boolean false Define whether to return &:focus-within as well

SCSS

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

CSS

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

@mixin if-breakpoint

Works like the breakpoint mixin, but leaves out the media query when width is 0. The grid mixins use it to loop over $illusion-grid-breakpoints.

Arguments

Name Type Default Description
width number - min-width amount. 0 outputs the content without a media query

SCSS

.foo {
  @include if-breakpoint(0) {
    color: red;
  }

  @include if-breakpoint($bravo) {
    color: blue;
  }
}

CSS

.foo {
  color: red;
}

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

@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 ms

Sets a property to a step of the modular scale multiplied by the --spacing custom property. Illusion does not define --spacing, so set it yourself. Browsers without custom property support get a rem fallback: ms(1, rem) times the step times $illusion-fallback-amount.

With $illusion-fallback: true only the fallback is output. With $illusion-logical-properties: true only the custom property version is output, using the logical property.

Arguments

Name Type Default Description
property string - The property to set
amount number 0 Step on the scale, from -4 to 4 (the keys of $illusion-ms-sizes). Other numbers are used as they are
multiplier number 1 Multiplies the step value. Set to false to use amount as the value without looking it up
subtractFrom string false Subtracts the result from this value, for example 100%

SCSS

.foo {
  @include ms(margin-top, 1);
}

CSS

.foo {
  margin-top: calc(1.5rem * 2.25);
}

@supports (--css: variables) {
  .foo {
    margin-top: calc(var(--spacing) * 1.5);
  }
}

@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;
  }
}

CSS

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

@mixin property

Writes a property and its value. With $illusion-logical-properties: true it writes the logical property instead, for example margin-inline-start for margin-left, and splits margin and padding shorthands into block and inline values. Most Illusion mixins write their properties with it.

Arguments

Name Type Default Description
property string - The physical property, for example margin-left
value string - The value. false leaves the property out
nested boolean false Not used at the moment

SCSS

.foo {
  @include property(margin-left, 16px);
  @include property(padding, 8px 16px);
  @include property(float, left);
}

CSS

.foo {
  margin-left: 16px;
  padding: 8px 16px;
  float: left;
}
With logical properties

With $illusion-logical-properties: true the same SCSS compiles to:

.foo {
  margin-inline-start: 16px;
  padding-block: 8px;
  padding-inline: 16px;
  float: inline-start;
}

@mixin pseudo

Adds a ::before or ::after element with content, display and position, and sets the position of the parent.

Arguments

Name Type Default Description
illusion-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 to 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
after boolean true Adds an ::after element that clears the floated ::before element

SCSS

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

CSS

.foo {
  overflow: hidden;
}

.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

Wraps grid columns: adds a clearfix for floats or makes it a wrapping flex container.

Arguments

Name Type Default Description
type string $illusion-grid-row-type flex for a flexbox row, any other value for a clearfix (float) row. Defaults to float

SCSS

.foo {
  @include row();
}

CSS

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

.foo::after {
  clear: both;
}

@mixin selectors

Writes the content as a separate rule for each selector. Selectors that are false are skipped. Illusion uses it for the configurable form selectors.

Arguments

Name Type Default Description
selectors list - Comma separated list of selectors

SCSS

@include selectors('.foo', '.bar') {
  color: red;
}

CSS

.foo {
  color: red;
}

.bar {
  color: red;
}

@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 Set starting and stopping breakpoints. false uses all 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 {
  position: relative;
  left: calc(((100% - 32px) / 3) + 16px);
}

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

@media screen and (min-width: 1024px) {
  .foo {
    left: calc(((100% - 64px) / 3) + 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 Accepts all, vertical, horizontal, top, right, bottom and left. Add minus and a side to skip that side, for example all minus top
type string 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 Set starting and stopping breakpoints. false uses all breakpoints. Accepts single value: @include spacing(all, padding, 1, $bravo) or list: @include spacing(all, 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 boolean 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

Sets the width of an element to a number of grid columns, with a left margin that follows the responsive gutters.

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 Set starting and stopping breakpoints. false uses all 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.
includeWidth boolean true Define whether to calculate and return the width.
includeMargin boolean true Define whether to calculate and return the left margin.

SCSS

.foo {
  @include span(6);
}

CSS

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

.foo {
  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 stack

Adds a top margin to every direct child except the first, so stacked elements get the same space between them.

Arguments

Name Type Default Description
value string 1.5em The space between the children

SCSS

.foo {
  @include stack;
}

CSS

.foo > * + * {
  margin-top: 1.5em;
}

@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 normally 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 $illusion-svg-background-color Color of the SVG. SVGs can only be one color. Defaults to black
width number $illusion-svg-background-width The width the SVG background should be displayed as. Defaults to 24
height number $illusion-svg-background-height The height the SVG background should be displayed as. Set to false if it’s the same as width. Defaults to false
viewboxWidth number $illusion-svg-background-viewboxWidth The actual viewboxWidth number. See original SVG file for this number. Defaults to 24
viewboxHeight number $illusion-svg-background-viewboxHeight The actual viewboxHeight number. See original SVG file for this number. Set to false if it’s the same as viewboxWidth. Defaults to false
background-position string $illusion-svg-background-position SVG background-position. Defaults to center
background-repeat string $illusion-svg-background-repeat SVG background-repeat. Defaults to no-repeat
unit string $illusion-svg-background-size-unit Unit added to width and height in background-size. Defaults to px
aspectRatio string $illusion-svg-background-aspect-ratio Value for the preserveAspectRatio attribute. Defaults to xMidYMid meet

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,%3Csvg style='fill: black;' xmlns='http://www.w3.org/2000/svg' width='16' height='16' viewBox='0 0 24 24' preserveAspectRatio='xMidYMid meet'%3E%3Cg transform='matrix(2.18679,0,0,2.18679,5.43964,-0.0421697)'%3E%3Cpath 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'/%3E%3C/g%3E%3C/svg%3E");
  background-position: center;
  background-repeat: no-repeat;
  background-size: 16px 16px;
}

@mixin svg-mask

Uses an SVG as a CSS mask, so the background color of the element shows in the shape of the SVG. Unlike svg-background the color can follow the text color.

Arguments

Name Type Default Description
svg string - Accepts anything that normally goes inside the <svg></svg> element
color string currentColor Background color that shows through the mask. Set to false to leave out the background-color
width string 100% Width of the mask
height string false Height of the mask. Set to false if it’s the same as width
viewboxWidth number 24 The viewBox width of the original SVG
viewboxHeight number false The viewBox height of the original SVG. Set to false if it’s the same as viewboxWidth
aspectRatio string xMidYMid meet Value for the preserveAspectRatio attribute

SCSS

.foo {
  @include svg-mask('<circle cx="12" cy="12" r="12"/>', currentColor, 16px);
}

CSS

.foo {
  background-color: currentColor;
  -webkit-mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' preserveAspectRatio='xMidYMid meet'%3E%3Ccircle cx='12' cy='12' r='12'/%3E%3C/svg%3E");
  mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' preserveAspectRatio='xMidYMid meet'%3E%3Ccircle cx='12' cy='12' r='12'/%3E%3C/svg%3E");
  -webkit-mask-size: 16px 16px;
  mask-size: 16px 16px;
}

@mixin transition

Shortcut to set one or more transition properties.

Arguments

Name Type Default Description
transitions list all Comma separated list. Each item can have up to four values (property, duration, easing, delay). Missing values fall back to $illusion-transition-duration (200ms), $illusion-transition-easing and $illusion-transition-delay (0ms)

SCSS

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

CSS

.foo {
  transition: opacity 1s cubic-bezier(0.195, 0.4, 0.45, 0.785) 0ms, transform 200ms 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: none;
}

@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: none;
}

Functions

@function calc-interpolation()

Returns a calc() that grows linearly from min-value at min-screen to max-value at max-screen. It doesn’t stop growing, so use it within a media query range. Used by the fluid-property mixin.

Arguments

Name Type Default Description
min-screen number - Viewport width where the value is min-value. Use px
min-value number - Value at min-screen. Use px; the output uses this unit
max-screen number - Viewport width where the value is max-value. Use px
max-value number - Value at max-screen. Use px

SCSS

.foo {
  @include breakpoint($bravo) {
    font-size: calc-interpolation($bravo, 16px, $delta, 24px);
  }
}

CSS

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

@function calculate-ratio()

Calculates a ratio between two numbers and returns it as percentage. Calculated by using the width of the element. The output will not work for flex items.

Arguments

Name Type Default Description
ratio list - Returns ratio as percentage. Accepts a list like 16 by 9

SCSS

.foo {
  padding-top: calculate-ratio(16 by 9);
}

CSS

.foo {
  padding-top: 56.25%;
}

@function fluid()

Scales a value fluidly between two viewport widths and returns a clamp() in rem. Give it the value from the mobile design and the value from the desktop design, in design pixels. A $min larger than $max gives a value that shrinks as the viewport grows. Values are converted to rem with px(), so they are divided by $root-site-font-size (default 18). When $min and $max are equal it returns that value in rem instead of a clamp().

Arguments

Name Type Default Description
min number - Value at the from viewport width. Unitless, px, rem or em
max number - Value at the to viewport width. Unitless, px, rem or em
from number $illusion-fluid-from Viewport width where scaling starts. Defaults to $alfa
to number $illusion-fluid-to Viewport width where scaling stops. Defaults to where @mixin container stops growing: $illusion-grid-maxwidth plus the largest gutter on both sides (1176px)

SCSS

.foo {
  font-size: fluid(16, 24);
  margin-top: fluid(40, 16);
}

CSS

.foo {
  font-size: clamp(0.8889rem, 0.7227rem + 0.9346vw, 1.3333rem);
  margin-top: clamp(0.8889rem, 2.7207rem - 2.8037vw, 2.2222rem);
}

@function get-margin()

Returns the gutter (margin) times multiplier, also within a breakpoint. Outside a breakpoint it uses the smallest gutter.

Arguments

Name Type Default Description
multiplier number 1 Multiplier. defaults to 1 and can be set to any number dividable by 0.5

SCSS

.foo {
  @include breakpoint($bravo) {
    margin-top: get-margin();
  }
}

CSS

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

@function get-width()

Returns the width of a number of grid columns, also within a breakpoint.

Arguments

Name Type Default Description
span list - Set how many columns should be spanned. Accepts single value: get-width(6) or list: get-width(4 of 12). Amount of columns defaults to $illusion-grid-container
multiplier number 1 Gutter multiplier. defaults to 1 and can be set to any number dividable by 0.5
gutter string false Custom gutter value for Illusion to calculate (calc()) with.

SCSS

.foo {
  @include breakpoint($bravo) {
    width: get-width(6);
  }
}

CSS

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

@function map-collect()

Merges any number of maps into one. Keys in later maps overwrite the same keys in earlier maps. Throws an error when one of the arguments is not a map.

Arguments

Name Type Default Description
maps list - Comma separated list of maps

SCSS

$small: (s: 8px);
$large: (l: 24px);
$sizes: map-collect($small, $large);

.foo {
  margin-top: map-get($sizes, s);
  margin-bottom: map-get($sizes, l);
}

CSS

.foo {
  margin-top: 8px;
  margin-bottom: 24px;
}

@function map-deep-get()

Returns a value from nested maps by following a chain of keys.

Arguments

Name Type Default Description
map map - The map to read from
keys list - Comma separated chain of keys

SCSS

.foo {
  padding: map-deep-get($illusion-grid-breakpoints, bravo, gutter);
}

CSS

.foo {
  padding: 24px;
}

@function map-get-next()

Returns the key that comes after key in map. Returns fallback when key is the last key. When the map or the key doesn’t exist it also returns fallback and shows a warning.

Arguments

Name Type Default Description
map map - The map to look in
key string - The key to start from
fallback string false Returned when there is no next key

SCSS

$sizes: (small: 8px, medium: 16px, large: 24px);

.foo {
  margin-top: map-get($sizes, map-get-next($sizes, small));
  margin-bottom: map-get-next($sizes, large, auto);
}

CSS

.foo {
  margin-top: 16px;
  margin-bottom: auto;
}

@function ms()

Returns a step of the modular scale ($illusion-ms-sizes) with a unit. Defaults to em so larger fonts get a larger scale. The result is a string, so it can’t be used in Sass calculations.

Arguments

Name Type Default Description
size number 0 Step on the scale, from -4 to 4. Other numbers are used as they are
type string em Unit to add. Use rem to ignore the font size of the element

SCSS

.foo {
  font-size: ms(2);
  margin-top: ms(-1, rem);
}

CSS

.foo {
  font-size: 2.25em;
  margin-top: 0.6666666667rem;
}

@function non-destructive-map-merge()

Merges child-map into parent-map. Unlike map-merge() it also merges nested maps instead of replacing them.

Arguments

Name Type Default Description
parent-map map - The map to merge into
child-map map - The map with the values to add or overwrite

SCSS

$base: (button: (color: black, padding: 8px));
$theme: (button: (padding: 16px));
$merged: non-destructive-map-merge($base, $theme);

.foo {
  color: map-deep-get($merged, button, color);
  padding: map-deep-get($merged, button, padding);
}

CSS

.foo {
  color: black;
  padding: 16px;
}

@function px()

Converts a pixel value from the design to rem by dividing it by $root-site-font-size (default 18).

Arguments

Name Type Default Description
size number - Pixel value, unitless or px. Other units give an error
type string rem Unit of the result: rem, em or false for a unitless number

SCSS

.foo {
  font-size: px(16);
  padding: px(9, em);
  line-height: px(27, false);
}

CSS

.foo {
  font-size: 0.8888888889rem;
  padding: 0.5em;
  line-height: 1.5;
}

@function spacing()

Returns the gutter of the current breakpoint times multiplier, also within a breakpoint. Outside a breakpoint it uses the smallest gutter.

Arguments

Name Type Default Description
multiplier number 1 Gutter multiplier. defaults to 1 and can be set to any number dividable by 0.5
breakpoint string false Name of a breakpoint in $illusion-grid-breakpoints (default, bravo or delta) to return the gutter of

SCSS

.foo {
  @include breakpoint($bravo) {
    padding-top: spacing();
  }
}

CSS

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

@function strip-unit()

Removes the unit from a number. Values that are not a number or have no unit are returned as they are.

Arguments

Name Type Default Description
number number - The value to remove the unit from

SCSS

.foo {
  --breakpoint: #{strip-unit($bravo)};
}

CSS

.foo {
  --breakpoint: 560;
}

@function svg-url()

Encodes SVG markup as a data URI and returns it as url(). Used by the svg-background and svg-mask mixins.

Arguments

Name Type Default Description
svg string - The complete SVG markup, including the xmlns attribute

SCSS

.foo {
  list-style-image: svg-url('<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 8 8"><circle cx="4" cy="4" r="4" fill="#f00"/></svg>');
}

CSS

.foo {
  list-style-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 8 8'%3E%3Ccircle cx='4' cy='4' r='4' fill='%23f00'/%3E%3C/svg%3E");
}