dookie-css
CSS library built on top of the Stylus preprocessor. It provides a couple of useful stylus mixins, utilities and components.
How to install
At first install package into your project:
npm install dookie-cssExpress.js (Connect)
For express or connect framework you can simply include dookie middleware method into Stylus' compiler:
var stylus = require('stylus'),
dookie = require('dookie-css');
...
app.configure(function(){
...
app.use(stylus.middleware({ src: __dirname + '/public', compile: dookie.middleware }));
})More about Stylus middleware here.
###Other environments
As for pure node.js or some other cases dookie has method called css. Here is an example of simple static server.js using Stylus + dookie:
var stylus = require('stylus'),
dookie = require('dookie-css');
...
// use stylus for styling
stylus(str)
.use(dookie.css()) // call dookie.css() function
.render(function (err, css) {
if (err) {
throw err;
}
// do smth with 'css'
});Check out ./examples folder to see how dookie can be introduced with pure node.js static server or express framework.
So now all dookie utilities can be called within your .styl files and it's time to check lib's documentation.
##Stylus cli plugin
If you prefer use Stylus cli executable for converting Stylus to CSS, you can also use dookie with it. In --use option specify path to dookie.js file, for example:
stylus --use ./node_modules/dookie-css/dookie.js --out ./Further reading about Stylus cli here.
##Documentation
###Settings
Dookie contains default configuration settings.styl. So this depends on your needs, but it's recommended to create your own _settings.styl (could be named whatever you like) and specify or overwrite existed variables.
######Examples:
Here is custom _settings.styl file which specifies vendors that are needed, and path to the folder with images:
img-path = '../images/'
vendors = webkit mozNow in your main Stylus file we add @import configuration and start to use dookie easily:
@import '_settings'
...######List of global settings:
-
img-path- path to the app folder with images (empty by default); -
vendors- list of vendors you want to use (by default includeswebkit,moz,ms,oandofficialwhich means unprefixed property); -
ie-support- set totrueto enable special IE properties likefilter: alpha(opacity = 100)etc. -
font-stack- global font-family stack; -
sans-serif-serifandmonospace- default font-families; -
font-size- global font-size variable; -
default-color- global font color fallback;
Settings file is also a good place to put your own configuration on the project.
###Reset mixins
These helpers are global (this also means you should use them in mixin form - mixin(args) instead of mixin: args):
reset() - simple base and recommended reset;
normalize() - popular normalize.css reset;
fields-reset() - reset input fields from sometimes annoying browser based styles (on ::required, ::valid, ::invalid, etc. pseudo-classes);
###Common useful helpers
Shorter replacements for display: block | inline-block | none respectively:
block(), inline-block(), hide();
Frequently used text transformation and decoration properties shorthands:
reset-case(), upcase(), lowcase(), nodecorate(), underline(), etc.
Font styles:
bold(), italic(), normal()
#####fs: [your font-size]
font-size shortener;
#####fw: [your font-weight]
font-weight shortener;
######Examples:
h2
fs: 2em
fw: 500
italic()
.link
block()
nodecorate()
/* yields => */
h2 {
font-size: 2em;
font-weight: 500;
font-style: italic;
}
.link {
display: block;
text-decoration: none;
}#####clearfix()
basic clearfix, simply add it to your class name or call global mixin base-classes() within your project to have it in .clearfix class;
#####size: [width, height]
cool and useful dimensions shortener, example:
.box
size: 30px
.longbox
size: 100px 20px
/* yields => */
.box {
width: 30px;
height: 30px;
}
.longbox {
width: 100px;
height: 20px;
}#####bg: [path], [args optional]
background mixin shortener, example:
.logo
bg: 'logo.png'
.cat
bg: 'cat.jpg' 100px 80px no-repeat #DDD
/* yields => */
.logo {
background: url("../images/logo.jpg") no-repeat;
}
.cat {
background: url("../images/cat.jpg") 100px 80px no-repeat #DDD;
}#####bg-retina:[path], [args optional]
very similar mixin but adds background-size: contain property for retina displays (use it together with @media all and (-webkit-min-device-pixel-ratio: 1.5));
Note: if you specify images folder in your settings img-path variable it allows you to put only picture file name in all dookie mixins;
#####image-block: [path], [dimensions optional]
mixin that replaces block with image specified in it.
Note: .png images could skip dimensions, because of Stylus native image-size() built-in function, example:
.replacer
image-block: 'default.png'
/* yields => */
.replacer {
background: url("../images/default.png") no-repeat;
font: 0/0 a;
text-shadow: none;
color: transparent;
width: 300px;
height: 200px;
}#####text-overflow: [width], [type optional]
useful when long text line need to be overflowed, default type is ellipsis, example:
.description
text-overflow: 300px
/* yields => */
.description {
text-overflow: ellipsis;
white-space: nowrap;
overflow: hidden;
width: 300px;
}#####text-hide()
hiding text mixin;
#####no-select()
disallow user to select element;
#####round()
makes element rounded corners, useful for large ones;
#####opacity: [opacity]
same as native css property but if your settings set ie-support to true mixin adds old-school IE filter property by itself;
#####triangle: [up|down|left|right], [size|default: 10px], [color|default: #000]
cool pure css triangle mixin, example:
.triangle
triangle: down 15px #F80
/* yields => */
.triangle {
width: 0;
height: 0;
border-left: 15px solid transparent;
border-right: 15px solid transparent;
border-top: 15px solid #F80;
}###Positioning
Dookie allows you to shorten css element positioning while using simply one line property.
#####absolute: [name value], ...
#####relative: [name value], ...
#####fixed: [name value], ...
#####static: [name value], ...
######Example:
.box
absolute: top 10px left 15px
/* yields => */
.box {
position: absolute;
top: 10px;
right: 15px;
}###Sprites
Dookie has several helpers to simplify your work with sprites.
#####sprite-grid: [path], [x], [y], [grid]
basic grid helper, [path] to your sprite picture, [x], [y] - square counts where icon is placed and [grid] param is your grid step (also can be as 2 params - gridX and gridY), example:
.sprite-pic
sprite-grid: 'sprite.png' 1 1 32px
/* yields => */
.sprite-pic {
background: url("../images/sprite.png") no-repeat;
background-position: -64px -32px;
}#####sprite-replace: [path], [x], [y], [grid]
same as previous one but also replaces text within an element with icon from the sprite;
Note: nice article describing these techniques by Niels Matthijs;
###Vendor prefixes
Dookie intelligently simplifies usage of css properties that mostly need to be prefixed. Only thing that you should do is to setup in your _settings.styl which prefixes you want to use (by default all of them are included). List of property mixins:
#####box-shadow: [args...]
#####border-radius: [args...]
#####box-sizing: [args...]
#####animation: [args...]
#####transition: [args...]
#####transformation: [args...]
#####perspective: [args...]
#####backface-visibility: [args...]
#####filters: [args...]
Note: Properties like animation, transition, transform and perspective also include all separate dependent props like animation-name, transition-delay, perspective-origin etc.
#####-prefix: [property], [args...]
It is also good to know that if you need some property to be prefixed, you can use dookie's -prefix method while passing into it property name and value, example:
.box
-prefix(some-prop, value1 value2)
/* yields => */
.box {
-webkit-some-prop: value1, value2;
-moz-some-prop: value1, value2;
-o-some-prop: value1, value2;
-ms-some-prop: value1, value2;
some-prop: value1, value2;
}###Easings
Custom timing functions useful for ui-transitions, see all of them in action here:
#####ease-in- quad, cubic, quart, quint, sine, expo, circ, back
#####ease-out- quad, cubic, quart, quint, sine, expo, circ, back
#####ease-in-out- quad, cubic, quart, quint, sine, expo, circ, back
######Example:
.animated
transition: all 300ms ease-in-quad
/* yields => */
.animated {
-webkit-transition: all 0.5s cubic-bezier(0.55, 0.085, 0.68, 0.53);
-moz-transition: all 0.5s cubic-bezier(0.55, 0.085, 0.68, 0.53);
-o-transition: all 0.5s cubic-bezier(0.55, 0.085, 0.68, 0.53);
-ms-transition: all 0.5s cubic-bezier(0.55, 0.085, 0.68, 0.53);
transition: all 0.5s cubic-bezier(0.55, 0.085, 0.68, 0.53);
}###Gradients
#####linear-gradient([start], [stops...])
mixin should be called within the property (background-image or background depends on what you prefer), example:
.gradient
background-image: linear-gradient(red, orange, yellow 80%)
/* yields => */
.gradient {
background-image: -webkit-gradient(linear, left top, left bottom, color-stop(0, #f00), color-stop(0.33333333333333326, #ffa500), color-stop(0.8, #ff0));
background-image: -moz-linear-gradient(top, #f00 0%, #ffa500 33.33333333333333%, #ff0 80%);
background-image: -webkit-linear-gradient(top, #f00 0%, #ffa500 33.33333333333333%, #ff0 80%);
background-image: -o-linear-gradient(top, #f00 0%, #ffa500 33.33333333333333%, #ff0 80%);
background-image: -ms-linear-gradient(top, #f00 0%, #ffa500 33.33333333333333%, #ff0 80%);
background-image: linear-gradient(top, #f00 0%, #ffa500 33.33333333333333%, #ff0 80%);
}#####radial-gradient([stops...])
same as previous one but radial, example:
.circle
background-image: radial-gradient(#f1c40f, #f39c12 50%)
/* yields => */
.circle {
background-image: -webkit-gradient(radial, center center 0px, center center 100%, color-stop(0, #f1c40f), color-stop(0.5, #f39c12), );
background-image: -moz-radial-gradient(center, ellipse cover, #f1c40f 0%, #f39c12 50%);
background-image: -webkit-radial-gradient(center, ellipse cover, #f1c40f 0%, #f39c12 50%);
background-image: -o-radial-gradient(center, ellipse cover, #f1c40f 0%, #f39c12 50%);
background-image: -ms-radial-gradient(center, ellipse cover, #f1c40f 0%, #f39c12 50%);
background-image: radial-gradient(ellipse at center, #f1c40f 0%, #f39c12 50%);
}#####gradient: [colorStart], [colorStop]
shorthand for two colors linear-gradient, example:
.box
gradient: #F80 #F00
/* yields => */
.box {
background: #f00;
background-image: -webkit-gradient(linear, left top, left bottom, color-stop(0, #f80), color-stop(1, #f00));
background-image: -moz-linear-gradient(top, #f80 0%, #f00 100%);
background-image: -webkit-linear-gradient(top, #f80 0%, #f00 100%);
background-image: -o-linear-gradient(top, #f80 0%, #f00 100%);
background-image: -ms-linear-gradient(top, #f80 0%, #f00 100%);
background-image: linear-gradient(top, #f80 0%, #f00 100%);
}#####simple-gradient: [color], [strength percents|default: 10%]
generates linear-gradient from one color;
###Global mixins
As reset helpers these mixins are global and should be called not within css selector but in file root.
#####base-classes()
adds couple of useful classes that you might add anyways, full list of them:
.left, .right, .clear, .show, .hide, .bold, .italic, .bullet, .clearfix, .rounded#####text-selection([highlight color], [text color|default: 'white'])
selection background and text color;
#####border-box()
enable border-box sizing globally;
#####font-face([name], [folder], [weight optional], [style optional])
bulletproof @font-face mixin, keep in mind that font name should be the same as font filename;
######Example:
font-face(DIN, '/fonts')
@font-face
font-family: 'DIN';
src: url('DIN.eot');
src: url('DIN.eot?#iefix') format('embedded-opentype'),
url('DIN.woff') format('woff'),
url('DIN.ttf') format('truetype'),
url('DIN.svg#DIN') format('svg');
font-weight: normal;
font-style: normal;##Test
Together with Stylus and dookie you can easily create tests for your mixins and utilities. Read more how you can test dookie itself with mocha.js and casper.js here - ./test/README.md.
##Contribute
Dookie is in beta yet, so issues or useful pull requests are highly appreciated.
##Why dookie?!
Because it's awesome Green Day's album from my childhood :)
MIT Licensed (c) 2013 Dmitri Voronianski