awesome / css-ratiocinator

because your CSS is garbage

The CSS Ratiocinator automatically refactors your CSS and generates a new stylesheet for your site. It works by examining your site's live DOM in the browser and reverse engineering a new, more elegant definition that captures styles down to the pixel.

It addresses the problem of old CSS whose styles accumulate and contradict each other. After a certain point all CSS seems to grow only by internal antagonism. The Ratiocinator wipes the slate clean and provides a harmonious new beginning.

Usage

The easiest way is to use the web interface csstrashman.com.

Alternatively, this program runs from the command line using the PhantomJS headless browser.

1. Install PhantomJS
2. Clone this repo
3. In the cloned directory, run phantomjs ratiocinate.js [URL]
4. The new CSS will appear.
5. (optionally) Feed output through sass-convert

Finally, it runs in the browser as a bookmarklet. Execute the following to split the browser window with the original page on the left and the Ratiocinated version on the right.

javascript:(function%20()%20%7Bvar%20script%20=%20document.createElement(%22script%22);script.src%20=%20%22https://raw.github.com/begriffs/css-ratiocinator/master/extras/bookmarklet.js%22;document.getElementsByTagName(%22head%22)[0].appendChild(script);%7D());

Faq

Does this thing clobber or remove my styles?

No. If your page renders differently after using Ratiocinator-generated style then that's a bug. This software may move styles around during the assessment stage of its algorithm but the end result respects the original styles you have created. Note that it may achieve these styles using a different combination of selectors and inheritance than your original CSS did.

Can it work on a whole site (multiple pages)?

In principle yes, but not yet. The strategy will be to ajax the pages together into a single page with multiple body tags. This long assembled page will provide enough data to the Ratiocinator to create a new style that respects everything your site does.

How is this different from other CSS tidying programs?

The Ratiocinator does not read your CSS files at all, it ignores them completely. It relies on the live DOM to infer what your styles want to accomplish. The thoroughness of the results you get are based on the quality and completeness of the example DOM that you provide the program.

Does it capture styles for the "sad path?"

It captures styles for whatever you show it, so if you have styles for errors or form validation problems or various element states then you'll need to include the markup to demonstrate them. The most effective input is a living style guide for your site. You do use a style guide, don't you?

Mechanism

The Ratiocinator proceeds in two phases: assessment and consolidation. During assessment it determines which nodes will need which styles, accounting for browser defaults and cascade rules. The browser provides a full list of computed style for every node, and our first step is to prune redundancies from cascaded style in a depth-first process called "lifting."

The last step in assessment is stripping default styles. The final style needn't specify CSS defaults, so we remove them prior to the consolidation phase.

Next comes consolidation, where we find shared pieces of style throughout the cleaned DOM tree and extract them to CSS declarations.

In the diagram above, the Ratiocinator will choose to output a declaration for the styles in red before those in blue. Although there are more blue items than red in element aside.foo, there are more red elements overall. The red has greater "volume." Hence the Ratiocinator will extract styles for all elements with class foo first and then for aside elements second.

Contributing

It is currently very easy to contribute — all I want is your complaints. Find something that the Ratiocinator does wrong and tell me. The best complaints are very specific, preferably made into a new test and submitted via a pull request. Luckily that's easy too:

1. Find some styles that the Ratiocinator is botching.
2. Think of the smallest example that will illustrate the problem.
3. Add a new test by copying test/template.html and filling in the blanks.
4. Save your new test in the test/ folder.
5. Run phantomjs test.js and make sure it fails.
6. Submit pull request.

There are two known open bugs. Any contributions toward solving them are also welcome.

1. Widths, heights, margins, etc are locked at particular pixel values (Issue #8)
2. Generated CSS doesn't yet include states like :hover or :visited (Issue #7)

License

The CSS Ratiocinator is Copyright © 2012 Joe Nelson. It is free software, and may be redistributed under the terms specified in the LICENSE file.