Merge branch 'stage-v6.0.0'

README.md

@@ -12,50 +12,36 @@ This package can be used in two ways: Development and Deployment.
 
 Develop your own codebase using Xmeter’s helper tools (Less mixins to help make your life easier).
 
-To install:
-
-    $ npm install xmeter
-
-The `/src/` folder contains a set of partials, starting with 2 underscores,
-from which to pick and choose to use for your project.
-These files are used in preprocessing only—they don’t output any actual css.
-The *tools* (`/src/__tool.*.less`) group similar properties
-to create one functional styling unit.
-(Read `/docs/tools.md` for details and usage.)
-The settings file, `/src/__settings.less`, contains all global variables.
-
-If you want to use a particular tool in your stylesheet, you will have to
-`@import (reference)` the stylesheet for that tool. For example,
-if you plan to use the `.font-size-el()` mixin in your Less, you must include
-
-```less
-@import (reference) url('/node_modules/xmeter/src/__tool.fontsize.less');
+Install:
+```bash
+$ npm install xmeter
 ```
 
-at the top of your stylesheet. Then when you want to “call” the mixin, do
-
+Use the global variables:
 ```less
+@import (reference) url('/node_modules/xmeter/src/__settings.less');
 .my-selector {
-  .font-size-el(2.0; 1.5);
+  font-size: (1.5 * @g-font-size-kilo);
 }
 ```
+See `/src/__settings.less` for all the variables available.
 
-To use the Xmeter global variables, import the `__settings` stylesheet.
-
+Use the tools:
 ```less
-@import (reference) url('/node_modules/xmeter/src/__settings.less');
-
+@import (reference) url('/node_modules/xmeter/src/__tool.fontsize.less');
 .my-selector {
-  font-size: (1.5 * @g-font-size-kilo);
+  .font-size-el(2.0; 1.5);
 }
 ```
+Read about all of Xmeter’s tools (see `/docs/tools.md`).
 
 ### Deployment
 
 Use Xmeter right out of the box on your own site.
+Want to see what Xmeter can do? [Check out the style guide] (link pending).
 
 Locally:
-```
+```bash
 $ npm install xmeter
 ```
 ```html
@@ -66,26 +52,26 @@ Remotely from a CDN (not recommended, unless deploying your `/node_modules/` isn
 ```html
 <link rel="stylesheet" href="https://cdn.rawgit.com/chharvey/xmeter/‹master›/xmeter.css"/>
 ```
-where `‹master›` can be a branch or a tag.
+where `‹master›` can be any branch or tag.
 
 The stylesheet `xmeter.css` is already minified, and is accompanied by a sourcemap `xmeter.css.map`.
 
+
+## Features
+
 Xmeter’s stylesheet is a starting point that “normalizes” unclassed HTML elements.
-And now that Xmeter has a few design patterns built in, you can use them in your markup too!
+And now that Xmeter has a few [design patterns] (link pending) built in, you can use them in your markup too!
 In addition to base styles, Xmeter has classes for Objects (`src/_o-*.less`), Components (`src/_c-*.less`) and Helpers (`src/_h-*.less`),
 design patterns that aid in a consistent, easy-to-use, vertical rhythm system.
 These classes should be directly injected into elements’ HTML `[class]` attribute on your site.
 
-
-## Features
-
 ### normalize.css
 
 This stylesheet rides on top of **normalize.css** developed by
 [Nicolas Gallagher](http://necolas.github.io/normalize.css/).
 
 This package has **normalize.css** as an npm dependency.
-normalize.css is built into xmeter.css, so there is *no need* to
+normalize.css is imported into xmeter.css, so there is *no need* to
 `npm install`, `@import`, or `<link/>` it manually.
 
 ### Vertical Rhythm
@@ -98,44 +84,47 @@ vertical rhythm system. (For more information on vertical rhythm, see these arti
 [Smashing Magazine](http://www.smashingmagazine.com/2011/03/14/technical-web-typography-guidelines-and-techniques/#tt-rhythm).)
 
 Every line on the page is exactly the same height
-  (dubbed a “vertical rhythm unit” or “vru”) regardless of font size, and
-  typographical block elements (headings, paragraphs, figures, blockquotes, lists,
-  tables, etc.) are separated by integer multiples of that height.
+(dubbed a “vertical rhythm unit” or “vru”) regardless of font size, and
+typographical block elements (headings, paragraphs, figures, blockquotes, lists,
+tables, etc.) are separated by integer multiples of that height.
 
 The following convention is used to preserve vertical rhythm:
-  - Bottom margin is added to an element in order to push subsequent elements down the page.
-  - Top padding is added to an element to push *itself* down the page.
-  - Negative top margin is added to an element to pull it up the page.
+- Bottom margin is added to an element in order to push subsequent elements down the page.
+- Top padding is added to an element to push *itself* down the page.
+- Negative top margin is added to an element to pull it up the page.
 
 ### Modular Font Size & Leading
 
 Font-size of `<html>` is set to `100%` to accommodate for user agent settings.
 
 Units for font-size on modules
-  should be set in `rem`s, so that their vertical typography remains the same
-  regardless of where that module is placed (style does not depend on location).
-  (`<html>` is considered a module.)
+should be set in `rem`s, so that their vertical typography remains the same
+regardless of where that module is placed (style does not depend on location).
+(`<html>` is considered a module.) When font-size of a module changes, the line-height
+should remain unchanged, so that the module is scalable.
 
 Within a module however, font-size on an element
-  should be set in `em`s, so that its vertical typography scales with
-  its parent module’s font size.
-  In addition to font-size, line-height should be adjusted to maintain vertical rhythm.
-  For example, if font-size is doubled, the line-height should be halved so that the final
-  height of each text line is unchanged. Xmeter’s tools do this for you automatically.
+should be set in `em`s, so that its vertical typography scales with
+its parent module’s font size.
+In addition to font-size, line-height should be adjusted to maintain vertical rhythm.
+For example, if font-size is doubled (x2.0), the line-height should be halved (x0.5) so that the final
+height of each text line is unchanged. Xmeter’s tools do this for you automatically.
 
 All line-height values are unitless. Line-height for all inline (text-level) elements is 0.
-  This preserves vertical rhythm within a block.
+This preserves vertical rhythm within a block.
 
-Tools add styles to blocks (font-size, borders) without disrupting vertical rhythm
+Tools add styles to blocks (font-size, borders) without disrupting vertical rhythm.
 
 ### Base Styles
 
 Minor, albeit prettier, style changes for some text-level elements (from common browser defaults).
 
 ### Miscellaneous Tools
-  - `.sprite()` sets background image sprites
-  - `.delims()` sets quotes and other things
-  - `.border-*-radius()` sets the border-radius on one side of a box, e.g., only the left side
+- `.sprite()` sets background image sprites
+- `.delims()` sets quotes and other things
+- `.border-*-radius()` sets the border-radius on one side of a box, e.g., only the left side
+- `.transitions()` allows you to set the
+  `transition-{property,duration,timing-function,delay}` properties all at once (semicolon-separated arguments)
 
 
 ## Changelog

docs/tools.md

@@ -117,6 +117,7 @@ in the same declaration, and the effective border-style cannot be specified; it
 ```
 
 ### transitions
+This mixin differs from the `transition` css shorthand property, which does not allow you to set comma-separated properties/durations/functions/delays.
 ```less
 @import (reference) url('/node_modules/xmeter/src/__tool.transitions.less');
 .your-class {