柔道

Judocss

The functional CSS toolkit designed for minimum effort and maximum efficiency.

Firstly, Judocss is a library that allows you to describe CSS classes as functions. For example:

  {
    "top-$n": (n) => `{ top: ${ base(n) }; }`,
  }

Describing your classes in this way makes it possible to watch your html files as you work, and generate only the classes you use.

Secondly, the default class mappings used by Judocss describe a semantic, low-level CSS framework that is both intuitive and reusable. For example;

Class | Rule --- | --- "margin-left-2px" | margin-left: 2px; "pad-3em" | padding: 3em; "visible" | visibility: visible; "fixed" | position: fixed;

This is intuitive because we already know how to write CSS, and it's reuseable because it only describes the elements of CSS that are common to all front end projects: standard CSS properties and values.

Because Judo reads those classes from your HTML, it also knows the full context in which they're used, making it possible* to reason about the most efficient way to recombine those values as compound classes, without having to worry about anything but maximising performance. This also makes for a better development experience because now we're free from having to think about the best way to name things, whilst also getting to work on markup and styles inside the same file.

Features

• Dynamic class names with variable arguments (e.g., .padding-top-$n, flex-$n, hsl-$h-$s-$l)
• Parses your HTML files and only generates the classes that you use
• Simple baseline rhythm: padding-top-2 yields { padding-top: ${2 * baseline}; }, while padding-bottom-2px yields { padding-bottom: 2px; }
• Responsive: Append breakpoint modifiers to the end of any class name to target that breakpoint (e.g., flex--small will only apply the .flex class to the element from the “small” breakpoint up)
• DRY: Append an asterisk (*) to the end of any class name to target an element’s immediate children instead of putting the same class on each of them (e.g., padding-2*, margin-1*)

Installation

• npm install judocss

Usage

Judocss is intended for livereload development; watch for changes in your html files, regenerate your css, then reloading your browser to reflect the changes you've just made.

Project configuration is described using an object like this:

var config = {}

config.serverRoot = "public/"
config.port = 3000
config.in = "./public/**/*.html"
config.out = "./public/app.css"
config.baseline = "7px"
config.breakpoint = {
  "small": "40em",
  "medium": "52em",
  "large": "64em"
}

The "out" property describes the file path where your compiled CSS should be saved. If you don't need your CSS to be saved automatically, then simply omit this property.

Invoke compilation within your own script as follows:

const judocss = require("judocss")

judocss({[...config]}, function(output){ /*...*/ })

The second argument is an optional callback function which will be passed the compiled CSS.

Standalone mode

To jump straight in to livereload development then follow this simple recipe:

• Add the following line to your projects package.json "scripts":

  "judo": "node_modules/.bin/judo"

• Copy the example configuration file to your project root by running the following command:

  cp node_modules/judocss/judo.conf.js .

• Edit the newly created config file as per your requirements

• Include the livereload script in your index.html file:

  <script src="//localhost:35729/livereload.js"></script>

• Run the dev server with the following command:

  npm run judo

Special Characters

Most unicode characters are allowed in CSS classnames, however many characters have special meanings in CSS and need to be escaped in order to avoid invoking their superpowers. As Judocss expects your CSS values to be part of the class name, then the characters %, #, and . are all expected and escaped automatically, which means that classes such as width-100%, color-#666, and font-size-2.5em are all perfectly fine. As mentioned previously, you may also add a trailing asterisk to any class name to target an elements immediate children instead of repeating the same classes for each child.

MIT license