typey 1.0.0.beta.5 → 1.0.0.beta.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f0b4078ef4f9a9b70e8ef1a26edc31a47941f512
-  data.tar.gz: 0d703fca1ea7bc85931a7ee173eaefe74e610851
+  metadata.gz: 8898792b278d464c815124ef1afbaa7ae18ea7a6
+  data.tar.gz: 222024e2a09ab32650c7220aa09427c12e54fca8
 SHA512:
-  metadata.gz: 12ddfbfc135e9826f830bba6b33f92d370ecedbaa4520a8b0ac33b51c36671e5b28305844c20a4a143aec8102b4a59dd72303de1b65f0a429ef71190fa5d5961
-  data.tar.gz: 436131cc1a02f2b9f5d95a561dd1ce1be90f22083175604bafd8161a45f6ea9c12dfe332a4185dbee2955eff77c3a36c73ba3527877b1207b3d5cb7c4379d5a5
+  metadata.gz: 9d601cc92f82925469b575f6260cf7bf872926dff1ad1e2645f8b8a4cfdc24a4edbb67c10c4f0eefc30b7171466ec9323141619d8c50f5ce25a7a22d7f89ad7f
+  data.tar.gz: 2cdd1be4ec90de348a3ec457be208fe50bcb6663ab628da9e48c4a31e70893408168f06b0ff63fc08d81a18b6f056cec6b1e5b475aba3b5a2fd7c9eff7ec78ad

data/README.md

@@ -2,131 +2,93 @@
 
 A complete framework for working with typography on the web.
 
-### Features
+## Requirements
 
-Supports outputting in rem, em and px.
+Sass 3.3.0
 
-```sass
-$base-unit: rem;
-```
+## Installation
 
-Define font sizes inside a sass map as t-shirt sizes.
+With RubyGems & Compass:
 
-```sass
-$font-size: (
-  xl:   32px,
-  l:    24px,
-  m:    16px,
-  s:    14px,
-);
+* Terminal: `gem install typey`
+* config.rb: `require 'typey'`
+* SCSS: `@import 'typey'`
 
-h1 {
-  @include font-size(xl);
-}
-```
+Bower
 
-Automatic px fallbacks when using rem as the base unit.
+* Terminal: `bower install typey`
+* SCSS: `@import '../link_to_component_dir/typey'`
 
-```css
-h1 {
-  font-size: 32px;
-  font-size: 2rem;
-}
-```
+Vanilla Sass
 
-Easily convert px values to rem or em.
+* Terminal: 'git clone git@github.com:jptaranto/typey.git
+* SCSS: `@import '../link_to_component_dir/typey/stylesheets/typey'`
 
-```sass
-button {
-  @include font-size(29px);
-}
-```
+## Getting started
 
-Automatic print media font sizing when using rem or em.
+### How do I tell typey what to do?
 
-```css
-@media print {
-  html {
-    font-size: 12pt;
-  }
-}
-```
+Firstly, all values you input to typey are expressed with `px` as the unit, and
+only `px` as the unit. This allows us to be completely consistent when dealing
+with typography in our stylesheets.
 
-Define line-height, margin and padding as multiples of the base line height OR as static values.
+Secondly, all strings in typey are expressed without quotes. Yes no quotes. This
+makes for leaner and cleaner code.
 
-```sass
-h2 {
-  @include line-height(3);
-  @incude margin(10px 0);
-}
-```
+### Decide how you want typey to output
 
-Define font weights inside a sass map.
+Now you'll need to choose the unit typey outputs your values in. You have three
+choices: `rem`, `em`, or `px`. Each has it's own pros and cons. We don't quite
+have enough space here to go over them so do your research before you jump in.
+Generally speaking, it is actually quite easy to change this value in typey later on.
 
 ```sass
-$font-weight: (
-  bold:    700,
-  normal:  400,
-  lighter: 200
-);
-
-strong {
-  font-weight: weight(bold)
-}
+$base-unit: rem;
 ```
 
-Ready to go web safe font stacks that are easy to extend.
+Just like in compass Vertical Rhythm we define our base font size and line height.
 
 ```sass
-$your-font-stack: extend-font-stack("Open sans", $sans-serif-stack);
+$base-font-size:    16px;
+$base-line-height:  20px;
 ```
 
-### Requirements
-
-Sass 3.3.0
-
-### Installation
-
-With RubyGems & Compass:
-
-* Terminal: `gem install typey`
-* config.rb: `require 'typey'`
-* SCSS: `@import 'typey'`
-
-Bower
-
-* Terminal: `bower install typey`
-* SCSS: `@import '../link_to_component_dir/typey'`
-
-Vanilla Sass
-
-* Terminal: 'git clone git@github.com:jptaranto/typey.git
-* SCSS: `@import '../link_to_component_dir/typey/stylesheets/typey'`
+Ok, so we have our base sizing, now we need to choose the approach that we are going
+to layout type with. We have two options available to us: rhythm and ratio. Rhythm
+allows us to specify line-heights as a multiple of $base-line-height, where as ratio
+allows us to specify line-heights as a multiple of our elements font-size. Rhythm is
+the default, but for beginners working with web typography the simplest approach
+is to use ratio. Each example below will tell you which method it is for.
 
-### Getting started
+```sass
+$line-height-method: rhythm;
+```
 
-Just like in compass Vertical Rhythm we define our base font size and line height first. In typey, all sizes are defined in `px` only.
+or
 
 ```sass
-$base-font-size:    16px;
-$base-line-height:  24px;
+$line-height-method: ratio;
 ```
 
-We also need to define the base unit that the functions and mixins will output. you can use `rem`, `em` or `px`.
+If you are using ratio, you should set your base ratio as so. Ignore this one
+if you are using rhythm.
 
 ```sass
-$base-unit: rem;
+$base-line-height-ratio: 1.25
 ```
 
-You can now setup your type defaults like so:
+By default typey will create print friendly stylesheets by adding a print media
+query to the `html` element with a font-size defined in `pt`. This is really only
+effective when you are using a relative unit as your `$base-unit` (rem or em). You
+can override the base print size with this variable.
 
 ```sass
-html {
-  @include define-type-sizing;
-}
+$print-font-size: 12pt;
 ```
 
-Define the `$font-size` map with t-shirt sizes (which are easier to keep track of then individual values).
+Ok on to the fun stuff. Defining font sizes! You should define as many of your
+font-sizes as possible inside the `$font-size` map with t-shirt sizes (which are
+easier to keep track of than individual values).
 
 ```sass
 $font-size: (
@@ -137,61 +99,56 @@ $font-size: (
 );
 ```
 
-To create print friendly stylesheets you must use a relative base unit (rem or em) - then all the work is taken care of for you. Optionally you can set the base print size like so:
+Now we are all set, we need to define our defaults for the `html` element. We can
+do this as easily as below:
 
 ```sass
-$print-font-size: 12pt;
+html {
+  @include define-type-sizing;
+}
 ```
 
-### Line height and font sizing examples
+## The quickest way to lay out type. Ever.
 
-The simplest way to set font size is via the `font-size` mixin.
+### Rhythm method
+
+In the example below, we are taking a heading, giving it an extra-large font-size and
+setting it's line-height to be 2x the $base-line-height.
 
 ```sass
 h1 {
-  @include font-size(xl);
+  @include type-layout(xl, 2);
 }
 ```
 
-You can specify line height as a multiple of `$base-line-height` (for a vertical rhythm approach).
+### Ratio method
 
-```sass
-h2 {
-  @include line-height(2);
-}
-```
-
-Or for those finicky designs, you can just use a static `px` value for granular control.
+As we have already set a base ratio, we don't really need to worry about setting
+the line-height as all elements will just inherit from the `html` element.
 
 ```sass
-h3 {
-  @include line-height(35px);
+h1 {
+  @include font-size(xl);
 }
 ```
 
-And for short hand, do it all with the `type-layout` mixin.
+But if we did want to override the base ratio, we can do it like so:
 
 ```sass
-h4 {
-  @include type-layout(xl, 2);
+h1 {
+  @include type-layout(xl, 1.75);
 }
 ```
 
-When using `em` as your `$base-unit`, each mixin accepts a `$context` parameter so your `em` value will be relative to it's parent or element `font-size`. The `$context` parameter can either accept a t-shirt size or a static value in px. See the reference section below for more information.
-
-```sass
-h4 {
-  @include type-layout(xl, 2);
+All ratios are outputted as `em` instead of your base unit as they will always
+be relative to their element's font-size.
 
-  span {
-    @include type-layout(s, 2, xl);
-  }
-}
-```
+## Add some margins or padding
 
-### Margin and padding examples
-
-The same mixins that we have for `line-height` also exist for `margin` and `padding`, and work exactly the same way.
+A key component of typography is the space between elements. Typey always uses
+a vertical rhythm approach for margins and padding regardless of whether you are
+using the ratio method. This way margins and padding will always be consistent
+in your stylesheets. You can specify these using the various margin and padding mixins.
 
 ```sass
 div {
@@ -199,9 +156,6 @@ div {
   @include margin-right(1);
   @include margin-bottom(2);
   @include margin-left(1);
-}
-
-form {
   @include padding-top(2);
   @include padding-right(1);
   @include padding-bottom(2);
@@ -218,340 +172,104 @@ div {
 }
 ```
 
-If you are using `em`, both the `margin()` and `padding()` functions/mixins accept a `$context` parameter.
+## Slightly tricky stuff
 
-```sass
-div {
-  @include font-size(s)
-  @include margin(1 2, s);
-  @include padding(1 2, s);
-}
-```
-
-### Extras
-
-Grab one of the web-safe font stacks included and extend it with your own fonts.
-
-```sass
-$your-font-stack: extend-font-stack("Open sans", $sans-serif-stack);
-```
-
-If you are using a web font that has multiple different weights, you can express these as numerical values, inside a sass map. Then if things change later on, it's easy as pie to change them site-wide.
+Every now and then you aren't going to want to specify a size or height as a multiple,
+ratio, or even a value from the `$font-size` map. You are going to want the ability
+to override things with actual `px` values and have them output properly in your
+base unit of choice. This is particularly useful for things like buttons or nav
+bars when you want to have an exact px height.
 
 ```sass
-$font-weight: (
-  bold:    700,
-  normal:  400,
-  lighter: 200
-);
-```
-
-You can then use typey's built in `weight()` function to call these values in an easy and readable way.
-
-```sass
-strong {
-  font-weight: weight(bold)
+button {
+  @include line-height(50px);
 }
 ```
 
-## Reference
-
-### Variables
+Or for fidely, one-off font sizes.
 
 ```sass
-$browser-font-size:        16px !default;
+.nav__dropdown-link {
+  @include font-size(22px);
+}
 ```
 
-The browser font size default. No need to change this.
-
+Or for some spacing you want to set manually.
 
 ```sass
-$base-font-size:           16px !default;
+li {
+  @include margin(5px 0);
+  @include padding(2px 0);
+}
 ```
 
-The base font size will be used for most calculations involving font-size.
-Allowed units: px
+All of typey's mixins accept a px value instead of a multiple/ratio or key from
+the font-size map.
 
+## Really quite tricky stuff (em as the $base-unit)
 
-```sass
-$base-line-height:         21px !default;
-```
-
-The base line height will be used for most calculations involving height.
-Allowed units: px
+Ok so what if you are really adventurous and want to use `em` as your base unit.
+Being relative to the element or parent's font-size, `em` can be particularly tricky when you
+have nested elements that you want to set a font-size or line-height for. To do
+this, each typey mixin has a $context argument that can be used to correctly
+set what the sizing should be relative too.
 
+In the below example we want to set the font size of a heading, and then give
+the nested span element a smaller font size. We do this by passing the font-size
+of the parent as the second argument to the mixin.
 
 ```sass
-$base-unit:                rem !default;
-```
-
-Allowed units: rem, em or px.
-
+h2 {
+  @include font-size(l);
 
-```sass
-$rem-fallback:             true !default;
+  span {
+    @include font-size(m, l);
+  }
+}
 ```
 
-By default we will provide fallbacks when rem is the base unit.
+If we are using the type-layout() mixin we can do the same thing like below:
 
 ```sass
-$auto-print-sizing:        true !default;
-```
-
-By default, when rem or em are the base unit we will output a print suitable media query with the define-type-sizing() mixin. This will take care of all print media type sizing effortlessly.
+h2 {
+  @include type-layout(l, 2);
 
-```sass
-$print-font-size:          12pt !default;
+  span {
+    @include type-layout(m, 2, l);
+  }
+}
 ```
 
-The pt font-size to be used with the print media query when $auto-print-sizing is enabled.
-Allowed units: pt
+## Extras
 
+Grab one of the web-safe font stacks included and extend it with your own fonts.
 
 ```sass
-$font-size: (
-  xxxl:                    60px,
-  xxl:                     46px,
-  xl:                      32px,
-  l:                       24px,
-  m:                       16px,
-  s:                       14px,
-  xs:                      12px
-) !default;
+$your-font-stack: extend-font-stack("Open sans", $sans-serif-stack);
 ```
 
-Default font sizes
-Once you redefine the $font-size map it will overwrite all sizes here.
-Allowed units: px
-
+If you are using a web font that has multiple different weights, you can express these as numerical values, inside a sass map. Then if things change later on, it's easy as pie to change them site-wide.
 
 ```sass
 $font-weight: (
-  bold:                    700,
-  normal:                  400,
-  lighter:                 200
-) !default;
-```
-
-Default font weights   
-This map and accompanying function help provide granular control over setting and retrieving static font weights.
-
-### Mixins
-
-```sass
-define-type-sizing($base-font-size: $base-font-size, $base-line-height: $base-line-height)
-```
-
-Outputs the base font-size property and the base line-height property. Font-size is outputted as a % of the base browser font size. A fallback for rem is provided for the line-height property.
-
-*@param number $base-font-size*  
-(optional) Use to set to anything other than the base value. Allowed units: px
-
-*@param number $base-line-height(optional)*  
-Use to set to anything other than the base value. Allowed units: px
-
-
-```sass
-type-layout($size, $x, $context: $size)
-```
-
-Outputs both line-height and font-size properties, providing fallbacks when rem is the base unit.
-
-*@param number|string $size*  
-A size from the $font-size map or a px value.
-
-*@param number $x*  
-Multiple of line height to be used or px value to be converted.
-
-*@param number|string $context*  
-(optional) Only used if em is the $base-unit. The value of the elements/parents font-size if it differs from $base-font-size. Specified as a t-shirt size or value in px.
-
-
-```sass
-font-size($size, $context: $base-font-size)
-```
-
-Outputs font-size property, providing fallbacks when rem is the base unit.
-
-*@param number|string $size*  
-A size from the $font-size map or px value to be converted
-
-*@param number|string $context*  
-(optional) Only used if em is the $base-unit. The value of the parent font-size if it differs from $base-font-size. Specified as a t-shirt size or value in px.
-
-
-```sass
-line-height($x, $context: $base-font-size)
-```
-
-Outputs line-height property, providing fallbacks when rem is the base unit.
-
-*@param number $x*
-Multiple of line height to be used or px value to be converted.
-
-*@param number|string $context*
-(optional) Only used if em is the $base-unit. The value of the elements/parentsfont-size if it differs from $base-font-size. Specified as a t-shirt size or value in px.
-
-
-```sass
-margin($x, $context: $base-font-size)
-```
-
-Outputs margin property, providing fallbacks when rem is the base unit.
-
-*@param number|list $x*  
-Multiple of line height to be used or px value to be converted.  
-Uses the same parameters as the CSS margin property:  
-i.e. top right bottom left, 1 0 2 0.
-
-*@param number|string $context*  
-(optional) Only used if em is the $base-unit. The value of the elements/parents font-size if it differs from $base-font-size. Specified as a t-shirt size or value in px.
-
-
-```sass
-padding($x, $context: $base-font-size)
-```
-
-Outputs padding property, providing fallbacks when rem is the base unit.
-
-*@param number|list $x*  
-Multiple of line height to be used or px value to be converted.  
-Uses the same parameters as the CSS margin property:  
-i.e. top right bottom left, 1 0 2 0.
-
-*@param number|string $context*  
-(optional) Only used if em is the $base-unit. The value of the elements/parents font-size if it differs from $base-font-size. Specified as a t-shirt size or value in px.
-
-
-```sass
-margin-top($x, $context: $base-font-size)
-margin-right($x, $context: $base-font-size)
-margin-bottom($x, $context: $base-font-size)
-margin-left($x, $context: $base-font-size)
-```
-
-Outputs corresponding margin property, providing fallbacks when rem is the base unit.
-
-*@param number|list $x*  
-Multiple of line height to be used or px value to be converted.  
-
-*@param number|string $context*  
-(optional) Only used if em is the $base-unit. The value of the elements/parents font-size if it differs from $base-font-size. Specified as a t-shirt size or value in px.
-
-
-```sass
-padding-top($x, $context: $base-font-size)
-padding-right($x, $context: $base-font-size)
-padding-bottom($x, $context: $base-font-size)
-padding-left($x, $context: $base-font-size)
-```
-
-Outputs corresponding padding property, providing fallbacks when rem is the base unit.
-
-*@param number|list $x*  
-Multiple of line height to be used or px value to be converted.  
-
-*@param number|string $context*  
-(optional) Only used if em is the $base-unit. The value of the elements/parents font-size if it differs from $base-font-size. Specified as a t-shirt size or value in px.
-
-### Functions
-
-```sass
-font-size($size, $context: $base-font-size)
-```
-
-*@param number|string $size*  
-A size from the $font-size map or px value to be converted
-
-*@param number|string $context*  
-(optional) Only used if em is the $base-unit. The value of the parent font-size if it differs from $base-font-size. Specified as a t-shirt size or value in px.
-
-*@return number*  
-The selected font-size in $base-unit.
-
-
-```sass
-line-height($x, $context: $base-font-size)
-```
-
-*@param number $x*  
-Multiple of line height to be used or px value to be converted.
-
-*@param number|string $context*  
-(optional) Only used if em is the $base-unit. The value of the elements/parentsfont-size if it differs from $base-font-size. Specified as a t-shirt size or value in px.
-
-*@return number*  
-The calculated height in $base-unit.
-
-
-```sass
-margin($x, $context: $base-font-size)
-```
-
-*@param number $x*  
-Multiple of line height to be used or px value to be converted.
-
-*@param number|string $context*  
-(optional) Only used if em is the $base-unit. The value of the elements/parents font-size if it differs from $base-font-size. Specified as a t-shirt size or value in px.
-
-*@return number*  
-The calculated height in $base-unit.
-
-
-```sass
-padding($x, $context: $base-font-size)
-```
-
-*@param number $x*  
-Multiple of line height to be used or px value to be converted.
-
-*@param number|string $context*  
-(optional) Only used if em is the $base-unit. The value of the elements/parents font-size if it differs from $base-font-size. Specified as a t-shirt size or value in px.
-
-*@return number*  
-The calculated height in $base-unit.
-
-
-```sass
-weight($weight)
+  bold:    700,
+  normal:  400,
+  lighter: 200
+);
 ```
 
-*@param string $weight*  
-A weight from the $font-weight map.
-
-*@return string*  
-The selected font-weight.
-
+You can then use typey's built in `weight()` function to call these values in an easy and readable way.
 
 ```sass
-extend-font-stack($font, $font-stack)
+strong {
+  font-weight: weight(bold)
+}
 ```
 
-*Example usage:*  
-$new-font-stack: extend-font-stack("Open sans", $sans-serif-stack);
-
-*@param string $font*  
-The name of the font. Use inverted commas if there are spaces in the font name. i.e "Open sans"
+## More examples
 
-*@param list $font-stack*  
-The font stack variable to extend.
+Grab a copy of the source code (make sure you get the same version you have installed) and look in the examples folder for a few more hints.
 
-### Included font stacks
-
-Three standard do-all stacks.
-
-```sass
-$serif-stack:         TimesNewRoman, "Times New Roman", Times, Baskerville, Georgia, serif;
-$sans-serif-stack:    "Helvetica Neue", Helvetica, Arial, sans-serif;
-$monospaced-stack:    "Courier New", Courier, "Lucida Sans Typewriter", "Lucida Typewriter", monospace;
-```
-
-Specific font stacks.
+## Reference
 
-```sass
-$arial-stack:         Arial, "Helvetica Neue", Helvetica, sans-serif;
-$helvetica-stack:     "Helvetica Neue", Helvetica, Arial, sans-serif;
-$baskerville-stack:   Baskerville, "Baskerville Old Face", "Hoefler Text", Garamond, "Times New Roman", serif;
-$monaco-stack:        Monaco, Consolas, "Lucida Console", monospace;
-$trebuchet-ms-stack:  "Trebuchet MS", "Lucida Grande", "Lucida Sans Unicode", "Lucida Sans", Tahoma, sans-serif;
-```
+The reference section has been removed for now in favour of the better detailed examples above. For explanation on all the individual functions and mixins inside typey you can just download the source code and ogle at the documentation contained within. Once the typey website launches it will include a complete reference section. Stay tuned.