CSS-On-Diet

a preprocessor for designers

CSS-On-Diet Developer Guide

Introduction

CSS-On-Diet is a CSS preprocessor with quite unique features. Author's (mine) intention was to make it easy to use and fast to learn. The other preprocessors seem to be focusing on adding tons of new functionalities making the learning processes a bit complicated and time consuming. CSS-On-Diet focuses on writing CSS faster. Actually it not only makes writing, but also changing and reading it faster.

Lets use COD as a shortcut for CSS-On-Diet. This guide applies to COD Specification Version 1.8 which is a technical and detailed document, and this is a more human friendly version.

For more information check out the home page.

Installation and usage

As of current (1.8) version of the COD Specification we have only a command line tool. It's written in Python and called cod. There are plans for writing a windows application which will be easier to install.

Please note that COD files should have the .cod extension in order to enable a proper syntax highlighting and build system in the supported editors.

To check if the cod tool is already installed try to print the version number:

cod -v

To install the cod command line tool you have few choices. Lets start from the most simple:

  1. If you are using Sublime Text Editor just type:

     CSS-On-Diet
    

    in the Install Package box. That is an editor plugin which includes cod command line tool, and it's connected to Sublime Text build system. So when you save a file with the .cod extension, the syntax will be highlighted and the file will be compiled to CSS when build button is clicked.

    Note that Package Controller (where you have above Install Package box) has to be installed separately from here. But you know that already if you are a Sublime Text user.

  2. If you have installed Python (default on Linux and MacOS) just use the pip tool.

     pip install CSSOnDiet
    

    That's recommend and most flexible way. On some systems pip command is not installed by default. You have to install it first.

  3. You can also download the latest COD package from our website, unpack it like this:

     tar xfvz CSSOnDiet-1.5.tar.gz
    

    get inside the unpacked directory and execute:

     python setup.py install
    

Note that only 1st choice doesn't require Python. Sublime Text Editor has the embedded Python interpreter. But it doesn't give you access to the cod script on the system level, just from that editor.

Usage

The command line tool cod translates the COD files to CSS:

cod input.cod -o output.css

Add the -m switch to also minify your CSS:

cod input.cod -o output.css -m

Check out more options from the help message:

cod -h

Prefixer

The cod tool has a built-in CSS3 prefixer. If you write for example

li {
  animation-name: mymove;
  box-sizing: border-box;
}

the prefixer will add needed declarations (unless you instruct cod to not to do it by adding the -p switch):

li {
  -webkit-animation-name: mymove;
  animation-name: mymove;
  box-sizing: border-box;
}

Note that box-sizing doesn't require prefixing anymore along with many others. The prefixing table is updated every release and you can also modify it directly in the beginning of the cod file.

Formatting

In order to make writing CSS faster the colons and semicolons in COD are not needed. It was always annoying for me to put a colon after every first word and a semicolon at the end of a line. Why to use colons and semicolons if they are always at the same position...

display: none;
display none;
display: none
display none

In COD all 4 lines above have the same meaning. If you question that feature will lets write CSS faster I agree that's not a big time saver. But wait for the next chapter, when you will learn more about the COD mnemonics. Just to have a quick look compare this line:

dis no

to this:

dis: no;

That's 25% less characters. And not need to remember two more tokens is a quite relief for the brain.

Optional semicolons put one restriction to our code: every COD declaration has to be on a separate line. The newline character is replaced by semicolon in the final CSS. But there is a way to put more declarations on a single line: just use semicolon in that case:

display none; padding 0

On the other hand, one line sometimes can be not enough for writing long declaration. You may want to spread it across multiple lines to keep a better visibility:

background-image:
    linear-gradient(
      to right, 
      #fffdc2,
      #fffdc2 15%,
      #d7f0a2 15%,
      #d7f0a2 85%,
      #fffdc2 85%
    );

That code is not valid in COD. Every line is treated as a single declaration. In that situation use the escape character '\' just before new line to join lines before proper preprocessing will take place:

background-image: \
    linear-gradient( \
      to right, \
      #fffdc2, \
      #fffdc2 15%, \
      #d7f0a2 15%, \
      #d7f0a2 85%, \
      #fffdc2 85% \
    );

Just remember that the '\' has to be exactly before the new line. Any spaces after it will make it invalid.

Comments

In COD we can use two types of comments. The standard CSS comments /* */ and the single line comments //. The single line comment starts from the // sequence and finishes at the end of a line.

// This is a one line comment
color red // a quite ugly color - not constructive comment

The standard CSS comments can be nested, unlike in pure CSS.

/* comment /* inside another comment */ Still comment! */ 

That's very useful if you want to comment out code which already has comments in it.

/*
li {
  /* background: black; */
  background: white;
}
*/

Mnemonics

The mnemonics (abbreviations) are the sugar of the COD preprocessor. The whole idea to create COD was born when I was playing with Emmet. As you may know CSS for Emmet allows you to type in your editor as few characters as possible to write CSS (Emmet is an editor plugin). Because it's so useful for so many people why not use that all along CSS development? It's faster to type, faster to modify (very often changing just one letter), and even faster to read it.

The mnemonics are available for

  1. properties names
  2. declaration values
  3. size units

Here are the lists of all mnemonics: CSS-On-Diet Mnemonics in the Specification

Every property mnemonic is 3 letters long. As you will start using them you will find few patterns in construction. Those patterns can faster your learning process significantly:

Mnemonics for values are just 2 letters long. Usually they are constructed from first two letters, but not always.

no = none
rx = repeat-x
bh = both
db = double

The units mnemonics are only one letter and there is only 7 of them. But even small change (p = px, e = em) saves a lot of typing when doing it over and over.

Here are the 3 lists of all mnemonics: CSS-On-Diet Mnemonics in the Specification

Medias

The media breakpoints are the biggest time saver in nowadays CSS development. Responsive Web Design is a must, no many will dare to denied that. Copying your declarations together with selectors just to place it in the right @media rule is a huge time waste. And is so hard to keep your eyes on all media versions.

Good preprocessors allow nesting the media queries. That solves the readability problem. COD additionally let you to write media specific declarations just next to other declarations:

p {
  col #000000
  les 2p
  les 3p @Medium
  les 4p @Big
}

As you can see above COD reduces required text to minimum. You can use labels for media breakpoints:

@cod-media {
  Medium  screen and (min-width : 480px)
  Big     screen and (min-width : 768px)
}

Media breakpoint label is written one per line in the above @cod-media rule. The first word is a breakpoint label (here Medium and Big). Rest of the line is a breakpoint definition which will be used in the final @media rule.

Breakpoints usage doesn't need much explanation. Just put the breakpoint label at the end of the declaration and your are ready. Above code produces following CSS:

p {
  color: #000000;
  letter-spacing: 2px;
}

/**  Breakpoint: Medium  **/
@media screen and (min-width : 480px) {
p  {
  letter-spacing: 3px ;
}
}
/**  Breakpoint: Big  **/
@media screen and (min-width : 768px) {
p  {
  letter-spacing: 4px ;
}
}

Breakpoints are expanded at the end of the file in the order they were declared. The label of the breakpoint can include letters, digits, underscore, hyphen and it's case sensitive.

Defines

The most advanced (hope still easy to learn) feature are the defines. That's what behind variables, mixins and macros/functions.

A define is a word which will be replaced by other word, multiple words, or any text at all. Defines are declared in the @cod-define rule, which is similar to the already presented @cod-media. The rule consist of declarations, one per line, where first word is a name and the rest of it is a define body:

@cod-define {
  BRAND-COLOR #431255
  boxspace 10p 20p
}

Declared define can be used in any place of COD file (even before it's declaration):

p {
  col BRAND-COLOR
  ma- boxspace
}

Notice that you don't have to use '$' or any special character like in the other preprocessors. Although defines has to be surrounded by no words characters (a word in COD consists of digits, letters, underscore and hyphen).

A define can be use inside the other define:

@cod-define {
  A 10p
  B A+3p
}

In that case only earlier declared defines are taken under consideration. Unlike everywhere else, inside @cod-defines they don't have to be the whole words, but longer defines have precedence over shorter

@cod-define {
  BAC black
  BACGROUND red
  BRAND_BG BACGROUNDish
}

In the above example BRAND_BG will be expanded to "redish" color, not "blackGROUNDish".

Here is an example of a mixin:

@cod-define {
  mixme mal 10p; pal 5p
}

Because a define body is always just one line long, semicolon is needed in our code. Although we can use escaping character '\' before new line to join lines

@cod-define {
  mixme mal 10p;\
        pal 5p
}

That way you can write one define on multiple lines. Note that the '\' joins lines, before main preprocessing.

Macros (functions) are defines with arguments:

@cod-define {
  Ocean rgb(67,12,168,_ARG1_)
}
p {
  bac Ocean(0.50)
}

The define name doesn't need any special signature to be a macro. Just in places where arguments should be expanded use ARG1, ARG2, ARG3, etc. That's all.

Includes

Including other files from the COD file merges everything, resulting in a single CSS output. That means a single HTTP request comparing to native CSS @import rule.

@cod-include {
  file1.cod
  dir1/dir2/file2.css
}

Every line represents a file path. Spaces at the beginning and the end are removed, but inside the line are preserved.

@cod-include {
  directory/file with spaces.cod
}

Eventually file path can be quoted.

@cod-include {
  "dir/file.cod"
}

Included files are expanded in the @cod-include place in the final CSS. COD doesn't have a problem when you make an include loop. For example A includes B, B includes C and C includes A. For every file our preprocessor computes a hash code and only unique files are included. So when you have two identical files but with different names, only first one will be included.

File paths are searched relative to the parent file. That means relative to the file which includes the current file. If such file doesn't exist, command line argument -I is checked for additional directories.

cod -I includedir,path/to/includes file1.cod

Arithmetics & RGBA

In the current version COD supports following operators: +, -, *, /, (). To use them, whole expression cannot contain the spaces but has to be surrounded by them or new lines:

word 10+2 20-3word

will be translated to:

word 12 20-3word

As you can see only the middle part is a correct expression.

If any arguments contains the dot result will be a real number. Otherwise it will be an integer:

21/5.0 21/5

will produce:

4.2 4

If at least one of the arguments contains COD unit (px, p, em, e, ...) result will also have that unit

20px+10 30+10%

gives:

30px 40%

Unfortunately in the current version COD units cannot be converted from each other, so COD compiler will use first founded unit. The expression:

2+3px+4in

give rather useless value of

9px

Hexadecimal RGBA

One more handy feature. COD has a fast way to write rgba() colors. Instead of normal 6 position color notation:

#430CA8

add two more hex digits for alpha channel

#430CA8CC

That gives us 8 bit resolution (256 possible alpha levels). Generated CSS code will be:

rgba(67,12,168,0.8)

The result alpha value is rounded to 3 digits after the dot, so:

#430CA8FD
#430CA8FE
#430CA8FF

will produce:

rgba(67,12,168,0.992)
rgba(67,12,168,0.996)
rgba(67,12,168,1)