{"id":13426907,"url":"https://github.com/begriffs/css-ratiocinator","last_synced_at":"2025-04-04T08:08:50.773Z","repository":{"id":3400548,"uuid":"4450203","full_name":"begriffs/css-ratiocinator","owner":"begriffs","description":"because your CSS is garbage","archived":false,"fork":false,"pushed_at":"2015-07-24T17:38:47.000Z","size":859,"stargazers_count":1036,"open_issues_count":15,"forks_count":44,"subscribers_count":36,"default_branch":"master","last_synced_at":"2025-03-28T07:08:50.691Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/begriffs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2012-05-25T21:08:34.000Z","updated_at":"2025-03-23T13:09:16.000Z","dependencies_parsed_at":"2022-09-03T08:43:33.210Z","dependency_job_id":null,"html_url":"https://github.com/begriffs/css-ratiocinator","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/begriffs%2Fcss-ratiocinator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/begriffs%2Fcss-ratiocinator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/begriffs%2Fcss-ratiocinator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/begriffs%2Fcss-ratiocinator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/begriffs","download_url":"https://codeload.github.com/begriffs/css-ratiocinator/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247142069,"owners_count":20890652,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T00:01:48.107Z","updated_at":"2025-04-04T08:08:50.757Z","avatar_url":"https://github.com/begriffs.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"![Logo](illustration/githubheader.png \"Logo\")\n\nThe CSS Ratiocinator automatically refactors your CSS and generates a\nnew stylesheet for your site. It works by examining your site's live DOM\nin the browser and reverse engineering a new, more elegant definition\nthat captures styles down to the pixel.\n\nIt addresses the problem of old CSS whose styles accumulate and\ncontradict each other. After a certain point all CSS seems to grow only\nby internal antagonism. The Ratiocinator wipes the slate clean and\nprovides a harmonious new beginning.\n\n[![Build Status](https://travis-ci.org/begriffs/css-ratiocinator.png?branch=master)](https://travis-ci.org/begriffs/css-ratiocinator)\n\n## Usage\n\nThis program runs from the command line using the\nPhantomJS headless browser.\n\n1. Install [PhantomJS](http://phantomjs.org/)\n1. Clone this repo\n1. In the cloned directory, run `phantomjs ratiocinate.js URL`\n1. The new CSS will appear.\n1. (optionally) Feed output through [sass-convert](http://blog.derekperez.com/post/816063805/move-you-existing-stylebase-over-to-sass-or-scss)\n\n## Faq\n\n\u003cdl\u003e\n  \u003cdt\u003eDoes this thing clobber or remove my styles?\u003c/dt\u003e\n  \u003cdd\u003eNo. If your page renders differently after using\n  Ratiocinator-generated style then that's a bug. This software may move\n  styles around during the assessment stage of its algorithm but the\n  end result respects the original styles you have created. Note that it\n  may achieve these styles using a different combination of selectors\n  and inheritance than your original CSS did.\u003c/dd\u003e\n\n  \u003cdt\u003eCan it work on a whole site (multiple pages)?\u003c/dt\u003e\n  \u003cdd\u003eIn principle yes, but not yet. The strategy will be to ajax the\n  pages together into a single page with multiple body tags. This long\n  assembled page will provide enough data to the Ratiocinator to create\n  a new style that respects everything your site does.\u003c/dd\u003e\n\n  \u003cdt\u003eHow is this different from other CSS tidying programs?\u003c/dt\u003e\n  \u003cdd\u003eThe Ratiocinator does not read your CSS files at all, it ignores\n  them completely. It relies on the live DOM to infer what your styles\n  want to accomplish. The thoroughness of the results you get are based\n  on the quality and completeness of the example DOM that you provide the\n  program.\u003c/dd\u003e\n\n  \u003cdt\u003eDoes it capture styles for the \"sad path?\"\u003c/dt\u003e\n  \u003cdd\u003eIt captures styles for whatever you show it, so if you have styles\n  for errors or form validation problems or various element states\n  then you'll need to include the markup to demonstrate them. The most\n  effective input is a living style guide for your site. You do use a\n  style guide, don't you?\u003c/dd\u003e\n\u003c/dl\u003e\n\n## Mechanism\n\nThe Ratiocinator proceeds in two phases: assessment and consolidation.\nDuring assessment it determines which nodes will need which styles,\naccounting for browser defaults and cascade rules. The browser provides\na full list of computed style for every node, and our first step is to\nprune redundancies from cascaded style in a depth-first process called\n\"lifting.\"\n\n![Lifting](illustration/lift.png \"Lifting\")\n\nThe last step in assessment is stripping default styles. The final\nstyle needn't specify CSS defaults, so we remove them prior to the\nconsolidation phase.\n\nNext comes consolidation, where we find shared pieces of style\nthroughout the cleaned DOM tree and extract them to CSS declarations.\n\n![Consolidating](illustration/consolidate.png \"Consolidating\")\n\nIn the diagram above, the Ratiocinator will choose to output a\ndeclaration for the styles in red before those in blue. Although there\nare more blue items than red in element `aside.foo`, there are more red\nelements overall. The red has greater \"volume.\" Hence the Ratiocinator\nwill extract styles for all elements with class `foo` first and then for\n`aside` elements second.\n\nFinally the Ratiocinator detects media query width breakpoints and\nsamples the page style between them. It analyzes the responsive\nportfolio and extracts common base-style. It outputs the base-style and\neach width-specific style with appropriate media queries.\n\n## Bugs and Edge Cases\n\nCurrently, anything Phantom considers to be an invalid property, value,\nor selector is discarded. This means that the following CSS...\n\n```css\nbody {\n  display: -webkit-box;\n  display: -moz-box;\n  display: -ms-flexbox;\n  display: -webkit-flex;\n  display: flex;\n}\n::selection{\n  background:rgba(246,55,0,0.9);\n  color:#fff;\n}\n::-moz-selection{\n  background:rgba(246,55,0,0.9);\n  color:#fff;\n}\n```\n\nIs compressed to the following CSS...\n\n```css\nbody {\n  display: -webkit-box;\n}\n```\n\nThis is an invalid compression. A solution is being worked on in\n[issue #52][issue52].\n\n## Contributing\n\nIt is currently very easy to contribute. Just find something that the\nRatiocinator does wrong and tell me. The best complaints are very\nspecific, preferably made into a new test and submitted via a pull\nrequest. Luckily that's easy too:\n\n1. Find some styles that the Ratiocinator is botching.\n1. Think of the smallest example that will illustrate the problem.\n1. Add a new test by copying `test/template.html` and filling in the blanks.\n1. Save your new test in the `test/` folder.\n1. Run `phantomjs test.js` and make sure it fails.\n1. Submit pull request to the `bug-reports` branch.\n\n## License\n\nThe CSS Ratiocinator is Copyright © 2012 Joe Nelson. It is free\nsoftware, and may be redistributed under the terms specified in the\nLICENSE file.\n\n  [issue52]: https://github.com/begriffs/css-ratiocinator/issues/52 \"Issue #52\"\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbegriffs%2Fcss-ratiocinator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbegriffs%2Fcss-ratiocinator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbegriffs%2Fcss-ratiocinator/lists"}