Lightweight mixin library to help you get the best of Stylus

About

Chouchenn is a very lightweight mixin library for Stylus. It provides tools to help day-to-day CSS coding:

maths and dimensions
positioning
visual effects like custom timing functions
text and font helpers

Basic Installation

You can download Chouchenn or clone it from the Github repository. The main files are located in the lib/chouchenn/ folder.

Drop Chouchenn in your project folder (even the root index.styl file).
Import it from your main Stylus file like so: @import 'path/to/chouchenn'
Have fun!

Install via NPM

Chouchenn is also available through NPM.

Install it via npm install chouchenn.
Import it in your favorite task manager. Check the example for a sample stylus task with Grunt.
Have fun!

Example:

var chouchenn = require('chouchenn');
module.exports = function() {
   return { 
     dev:{ 
       files: { 
         src: 'styles.styl', 
         dest: 'styles.css' 
       },
       options: { 
        'use': [ chouchenn ], 
        'import': ['chouchenn'] 
       } 
     } 
   }; 
 };

Documentation

Maths and Dimensions

Percentage

This mixin translates a value to a percentage value. Useful to keep code readable.

What you write:

p
  width: pct( 280 / 320 )

What you get:

p {
  width: 87.5%;
}

Round

Assists with value calculations. Furthermore, the code is also more maintainable and readable.
The $rounding global variable can be used to adjust rounding decimals as needed. Defaults to 3 decimals.

What you write:

$rounding = 3
div
  padding: rnd( 7em / 9 ) rnd( 34em / 9 )

What you get:

div {
  padding: 0.778em 3.778em;
}

Positioning

Clearfix

Outputs a micro clearfix to clear your floats.

What you write:

div
  clearfix()

What you get:

div:after {
  clear: both;
  content: "";
  display: table;
}

Vertical Align

Provides a "ghost" reference element to vertically align all sibling elements.
Note: all sibling elements must have their vertical-align property set.

What you write:

div
  &:before
     valign()

What you get:

div:before {
  content: "";
  display: inline-block;
  height: 100%;
  vertical-align: middle;
  width: 0;
}

Shapes and Visual Effects

Diamond

Draws diamond-shaped block with CSS (it’s trendy these days). It takes up to five parameters, the first two being mandatory:

What you write:

div
  //diamond( size, color, [translateX], [translateY], [transformOrigin] ), for exemple :
  diamond( 40px, #dddddd, x: 20px, origin: 100% 100% )

What you get:

div { 
  background-color: #ddd;
  height: 28.284271247461902px;
  transform:translateX(20px) rotate(45deg);
  transform-origin: 100% 100%;
  width: 28.284271247461902px;
}

Example:

Hide

Visually hides content. You can use it for image replacement. The benefits of this mixin are:

Hidden text remains accessible by screen readers.
The browser does not draw a huge box (like it does with the left:-9999px; technique) and no weird outline either.
Hidden element does not interfere with page flow.

Chouchenn also provides a reverse mixin called hide-reset() to cancel the hiding.

What you write:

h1 span
  hide()

What you get:

h1 span {
  clip: rect(0 0 0 0);
  height: 1px;
  margin: -1px;
  overflow: hidden;
  padding: 0;
  position: absolute;
  width: 1px;
}

Hide-Reset

Cancels out the effects of the hide() mixin.

What you write:

h1 span
  hide-reset()

What you get:

h1 span {
  clip: auto;
  height: auto;
  margin: 0;
  overflow: visible;
  position: static;
  width: auto;
}

Triangle

Generates CSS triangles.
Available direction values: up, down, left, right, up-left, up-right, down-left and down-right.

What you write:

span.triangle
  triangle( 25px, #808080, up-right )

What you get:

div {
  border-left: 25px solid transparent;
  border-top: 25px solid #808080;
  height: 0;
  width: 0;
}

Example:

up
down
left
right
up-left
up-right
down-left
down-right

Timing-Functions

Defines variables to extend the timing functions initially provided by CSS (based upon jQuery UI timing functions).
Chouchenn provides variants for ease-in, ease-out and ease-in-out to use in your stylesheets:

What you write:

div
  transition: width 1.2s ease-in-out-quart

What you get:

div {
  transition: width 1.2s cubic-bezier(0.77, 0, 0.175, 1);
}

All available timing functions:

$ease-in-quad
$ease-out-quad
$ease-in-out-quad

$ease-in-cubic
$ease-out-cubic
$ease-in-out-cubic

$ease-in-quart
$ease-out-quart
$ease-in-out-quart

$ease-in-quint
$ease-out-quint
$ease-in-out-quint

$ease-in-sine
$ease-out-sine
$ease-in-out-sine

$ease-in-expo
$ease-out-expo
$ease-in-out-expo

$ease-in-circ
$ease-out-circ
$ease-in-out-circ

$ease-in-back
$ease-out-back
$ease-in-out-back

Text and Font Properties

Font-Face

Easy and shorter way to import your different custom fonts. Please refer to the Settings section to understand how to change the font types and their order.

What you write:

$url ='/fonts/Source_Sans_Pro/'
$name ='SourceSansPro-Regular'
fontface( SourceSansPro, '/fonts/Source_Sans_Pro/SourceSansPro-Regular' )
fontface( SourceSansPro, $url + $name )
fontface( SourceSansPro, '/fonts/Source_Sans_Pro/SourceSansPro-Bold', bold )
fontface( SourceSansPro, '/fonts/Source_Sans_Pro/SourceSansPro-Italic', normal, italic )

What you get:

@font-face{
  font-family: SourceSansPro;
  font-style: normal;
  font-weight: normal;
  src: url("/fonts/Source_Sans_Pro/SourceSansPro-Regular.eot");
  src: url("/fonts/Source_Sans_Pro/SourceSansPro-Regular.eot?#iefix") format("embedded-opentype"),
url("/fonts/Source_Sans_Pro/SourceSansPro-Regular.woff") format("woff"),
url("/fonts/Source_Sans_Pro/SourceSansPro-Regular.ttf") format("truetype"),
url("/fonts/Source_Sans_Pro/SourceSansPro-Regular.svg#SourceSansPro") format("svg");
}

@font-face{
  font-family: SourceSansPro;
  font-style: normal;
  font-weight: normal;
  src: url("/fonts/Source_Sans_Pro/SourceSansPro-Regular.eot");
  src: url("/fonts/Source_Sans_Pro/SourceSansPro-Regular.eot?#iefix") format("embedded-opentype"),
url("/fonts/Source_Sans_Pro/SourceSansPro-Regular.woff") format("woff"),
url("/fonts/Source_Sans_Pro/SourceSansPro-Regular.ttf") format("truetype"),
url("/fonts/Source_Sans_Pro/SourceSansPro-Regular.svg#SourceSansPro") format("svg");
}

@font-face{
  font-family: SourceSansPro;
  font-style: normal;
  font-weight: normal;
  src: url("/fonts/Source_Sans_Pro/SourceSansPro-Bold.eot");
  src: url("/fonts/Source_Sans_Pro/SourceSansPro-Bold.eot?#iefix") format("embedded-opentype"),
url("/fonts/Source_Sans_Pro/SourceSansPro-Bold.woff") format("woff"),
url("/fonts/Source_Sans_Pro/SourceSansPro-Bold.ttf") format("truetype"),
url("/fonts/Source_Sans_Pro/SourceSansPro-Bold.svg#SourceSansPro") format("svg");
}

@font-face{
  font-family: SourceSansPro;
  font-style: normal;
  font-weight: normal;
  src: url("/fonts/Source_Sans_Pro/SourceSansPro-Italic.eot");
  src: url("/fonts/Source_Sans_Pro/SourceSansPro-Italic.eot?#iefix") format("embedded-opentype"),
url("/fonts/Source_Sans_Pro/SourceSansPro-Italic.woff") format("woff"),
url("/fonts/Source_Sans_Pro/SourceSansPro-Italic.ttf") format("truetype"),
url("/fonts/Source_Sans_Pro/SourceSansPro-Italic.svg#SourceSansPro") format("svg");
}

Line Height

Does the line-height maths for you. The mixins takes the context font-size value as a unique parameter.
This mixin adds the $lh-base variable value to the font-size provided, divides the sum by the font-size value and returns the result of the calculation. $lh-base defaults to 4.

What you write:

// let's assume the font-size is 28px
p
  line-height: lh( 28 )

What you get:

p {
  line-height: 1.143;
}

EM Size

Returns the result of the calculation in ems.

What you write:

p
  font-size: em( 12 / 16 )

What you get:

p {
  font-size: 0.75em;
}

REM Size

Returns the value passed as a parameter in rem. Uses the $rem-base variable to do the maths (in case you redefine the root font-size of the page). This variable defaults to 16px.

What you write:

p
  font-size: rem( 10 )

What you get:

p {
  font-size: 0.625rem;
}

Settings

In addition to the mixins, Chouchenn provides several configuration settings to give you more control over the way mixins behave.

$font-type: sets the font-face formats and their order. Used in the font-face mixin.
$rounding: adjusts the rounding mixin decimal numbers.
$lh-base: sets the value added to the font-size of the line-height mixin.
$rem-base: sets the base font-size reference for the rem-size mixin.

Global variables default values:

$font-type     ?= eot woff ttf svg
$rounding      ?= 3
$lh-base       ?= 4
$rem-base      ?= 16

Switch's tips

Chouchenn is a tool library. It is not (and never will be) intended to support prefixes or special syntaxes, etc. There are better tools for this (like autoprefixer) and we strongly encourage you to use them in addition of Chouchenn.

Licence

Chouchenn is free software and licenced under the BSD licence. For more details, please refer to the LICENCE file.