typey 1.0.0.alpha.5 → 1.0.0.beta.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 05f582671fc72dca0711c61757f16b4d90dd3fa5
-  data.tar.gz: 1c65a7f0073d6c7c30375c4c7cbbf49ab18387a0
+  metadata.gz: aca87ffaf531d2f1e51eb2be6c9da355dfb02a44
+  data.tar.gz: 4bfeb8f07ef93d64305edaf294b16dfffa7aec8e
 SHA512:
-  metadata.gz: 58c36316968c1c9294632bcc62fc9d769bfbc8cc1a070f9fc9868653c33d5b80f58b447ab3dc37c0a748391715546d4e0e90884b96c5ea66ab038d7de083062f
-  data.tar.gz: cb6f5c2ff66819c0afc270afbfcb66286d38a863f367e5e42d0fa84b2839442f80b78f76c876197c0f9968285cb1d952a5fa5f16dc31002a69f3f7e815f3e7e1
+  metadata.gz: 5cd59c665668d4e34b6b4e24afbe69dbf077cfaa1126300dc2fced7ea96368c43484610917102531bac7891f6929aae7cce0b9159b289718433ff9539c647b31
+  data.tar.gz: 564260d9dab2c9647eb2e00f55a12bf680b1caba17f6700ffcc55853cf4028c41818bd622fdcc99e9ecfb8d61ad3ae953ba44050ce8ea8baeed8acdf26391641

data/README.md

@@ -1,16 +1,18 @@
 # typey
 Do typography better.
 
-*This repo contains alpha code that is likely to change at any point. Use at your own risk ;)*
+**Typey is in beta! Use it to your hearts content on _all_ your projects!**
+
 
 ### Features
 
-* Use px (for screen) and pt (for print) and then output in px, pt, rem or em.
+* Use px to define font sizes and have them output in rem or em.
 * Define font sizes inside a sass map as t-shirt sizes (m, l, xl, xxl, etc).
 * Define line-height as multiples of the base line height OR as static values.
 * Automatic px fallbacks when using rem as the base unit.
+* Easily convert px values to rem or em.
 * Define font weights inside a sass map.
-* Ready to go web safe font stacks that are easy to extend. Credit: John Albin Wilkins.
+* Ready to go web safe font stacks that are easy to extend.
 
 ### Requirements
 
@@ -32,11 +34,11 @@ Bower
 Vanilla Sass
 
 * Terminal: 'git clone git@github.com:jptaranto/typey.git
-* SCSS: `@import '../link_to_component_dir/typey/stylesheets/typey'` 
+* SCSS: `@import '../link_to_component_dir/typey/stylesheets/typey'`
 
 ### CSS units used in typey
 
-`px` 
+`px`
 
 By far the simplest unit you can use to size typography on the web. It translates very easily from mockups produced in a certain over-rated graphics suite. In typey, all base sizes are specified in `px` (or `pt`) and are automatically converted to your `$base-unit`.
 
@@ -58,7 +60,7 @@ Just like in compass Vertical Rhythm we define our base font size and line heigh
 
 ```sass
 $base-font-size:    16px;
-$base-line-height:  21px;
+$base-line-height:  24px;
 ```
 
 We also need to define the base unit that the functions and mixins will output. you can use `px`, `pt` (for print stylesheets), `rem` or `em`.
@@ -124,12 +126,20 @@ h4 {
 }
 ```
 
+Or for short hand you can use the `type-layout()` mixin.
+
+```sass
+h4 {
+  @include type-layout(xl, 2);
+}
+```
+
 When using `em` as your `$base-unit`, each function accepts a second parameter so your `em` value will be relative to it's parent or element `font-size`. The second parameter can either accept a t-shirt size or a static value for granular control.
 
 ```sass
 h4 {
   font-size: font-size(xl);
-  
+
   span {
     font-size: font-size(s, xl);
     line-height: line-height(2, 14px);
@@ -161,8 +171,8 @@ We also have a pair of mixins which (you guessed it!) automatically add fallback
 
 ```sass
 div {
-  @include margin(1 2);
-  @include padding(1 2);
+  @include margin(2 1);
+  @include padding(2 1);
 }
 ```
 
@@ -171,7 +181,7 @@ If you are using `em`, both the `margin()` and `padding()` functions/mixins acce
 ```sass
 div {
   font-size: font-size(s)
-  
+
   span {
     @include margin(1 2, s);
     @include padding(1 2, s);
@@ -197,13 +207,295 @@ $font-weight: (
 );
 ```
 
-You can then use typey's built in font-weight function to call these values in an easy and readable way.
+You can then use typey's built in `weight()` function to call these values in an easy and readable way.
 
 ```sass
 strong {
-  font-weight: font-weight(bold)
+  font-weight: weight(bold)
 }
 ```
 
+## Reference
+
+### Variables
+
+```sass
+$browser-font-size:        16px !default;
+```
+
+The browser font size default. No need to change this.
+
+
+```sass
+$base-font-size:           16px !default;
+```
+
+The base font size will be used for most calculations involving font-size.
+Allowed units: px or pt
+
+
+```sass
+$base-line-height:         21px !default;
+```
+
+The base line height will be used for most calculations involving height.
+Allowed units: Must be the same as $base-line-height
+
+
+```sass
+$base-unit:                rem !default;
+```
+
+Allowed units: px, pt, em or rem.
+
+
+```sass
+$rem-fallback:             true !default;
+```
+
+By default we will provide fallbacks when rem is the base unit.
+
+
+```sass
+$font-size: (
+  xxxl:                    60px,
+  xxl:                     46px,
+  xl:                      32px,
+  l:                       24px,
+  m:                       16px,
+  s:                       14px,
+  xs:                      12px
+) !default;
+```
+
+Default font sizes
+Once you redefine the $font-size map it will overwrite all sizes here.
+Allowed units: Must be the same as $base-line-height
+
+
+```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 or pt
+
+*@param number $base-line-height(optional)*  
+Use to set to anything other than the base value. Allowed units: px or pt
+
+
+```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/pt value.
+
+*@param number $x*  
+Multiple of line height to be used or px/pt 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 the same unit as the $font-size map.
+
+
+```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/pt 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 the same unit as the $font-size map.
+
+
+```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/pt value to be converted.
 
-*More to come soon ;)*
+*@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 the same unit as the $font-size map.
+
+
+```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/pt 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 the same unit as the $font-size map.
+
+
+```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/pt 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 the same unit as the $font-size map.
+
+
+```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/pt 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 the same unit as the $font-size map.
+
+
+```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/pt 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 the same unit as the $font-size map.
+
+### Functions
+
+```sass
+font-size($size, $context: $base-font-size)
+```
+
+*@param number|string $size*  
+A size from the $font-size map or px/pt 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 the same unit as the $font-size map.
+
+*@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/pt 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 the same unit as the $font-size map.
+
+*@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/pt 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 the same unit as the $font-size map.
+
+*@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/pt 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 the same unit as the $font-size map.
+
+*@return number*  
+The calculated height in $base-unit.
+
+
+```sass
+weight($weight)
+```
+
+*@param string $weight*  
+A weight from the $font-weight map.
+
+*@return string*  
+The selected font-weight.
+
+
+```sass
+extend-font-stack($font, $font-stack)
+```
+
+*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"
+
+*@param list $font-stack*  
+The font stack variable to extend.
+
+### Included font stacks
+
+```sass
+// Three standard do-all stacks.
+$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.
+$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;
+```

data/stylesheets/_typey.scss

@@ -3,6 +3,7 @@
 @import "typey/font-stacks";
 @import "typey/font-size";
 @import "typey/line-height";
-@import "typey/font-weight";
+@import "typey/type-layout";
+@import "typey/weight";
 @import "typey/margin";
-@import "typey/padding";
+@import "typey/padding";

data/stylesheets/typey/_defaults.scss

@@ -1,5 +1,5 @@
 // The browser font size default. No need to change this.
-$browser-font-size:        16px;
+$browser-font-size:        16px !default;
 
 // The base font size will be used for most calculations involving font-size.
 // Allowed units: px or pt
@@ -12,6 +12,9 @@ $base-line-height:         21px !default;
 // Allowed units: px, pt, em or rem.
 $base-unit:                rem !default;
 
+// By default we will provide fallbacks when rem is the base unit.
+$rem-fallback:             true !default;
+
 // Default font sizes
 // Once you redefine the $font-size map it will overwrite all sizes here.
 // Allowed units: Must be the same as $base-line-height
@@ -26,7 +29,7 @@ $font-size: (
 ) !default;
 
 // Default font weights
-// This map and accompanying function help provide granular control over 
+// This map and accompanying function help provide granular control over
 // setting and retrieving static font weights.
 $font-weight: (
   bold:                    700,
@@ -36,21 +39,21 @@ $font-weight: (
 
 // Warnings for $base-unit.
 @if $base-unit != px and $base-unit != pt and $base-unit != rem and $base-unit != em {
-  @warn "$base-unit must be one of the following unit types: px, pt, rem, em";
+  @error "$base-unit must be one of the following unit types: px, pt, rem, em";
 }
 
 // Warnings for $base-font-size and $base-line-height.
 @if unit($base-font-size) != px and unit($base-font-size) != pt {
-  @warn "$base-font-size must be one of the following unit types: px, pt";
+  @error "$base-font-size must be one of the following unit types: px, pt";
 }
 @if unit($base-line-height) != unit($base-font-size) {
-  @warn "$base-line-height must use the same unit as $base-font-size.";
+  @error "$base-line-height must use the same unit as $base-font-size.";
 }
 
 // Warnings for $font-size
 @each $key, $size in $font-size {
   @if unit($size) != unit($base-font-size) {
-    @warn "Size '#{$key}' in $font-size map does not match the $base-font-size unit.";
+    @error "Size '#{$key}' in $font-size map does not match the $base-font-size unit.";
   }
 }
 
@@ -63,17 +66,19 @@ $font-weight: (
 //   (optional) Use to set to anything other than the base value.
 //   Allowed units: px or pt
 @mixin define-type-sizing($base-font-size: $base-font-size, $base-line-height: $base-line-height) {
-  @if $base-unit == px or $base-unit == pt {
-    font-size: $base-font-size;
-    line-height: $base-line-height;
-  }
   @if $base-unit == rem {
     font-size: $base-font-size / $browser-font-size * 100%;
-    line-height: $base-line-height;
+    @if $rem-fallback == true {
+      line-height: $base-line-height;
+    }
     line-height: output-unit($base-line-height / $base-font-size);
   }
+  @if $base-unit == px or $base-unit == pt {
+    font-size: $base-font-size;
+    line-height: $base-line-height;
+  }
   @if $base-unit == em {
     font-size: $base-font-size / $browser-font-size * 100%;
     line-height: output-unit($base-line-height / $base-font-size);
-  }  
+  }
 }

data/stylesheets/typey/_font-size.scss

@@ -1,10 +1,10 @@
-// Takes a sizing from the $font-size map (m, xl, xxl, etc) and convert it to 
-// the base unit.
+// Takes a sizing from the $font-size map (m, xl, xxl, etc) and convert it to
+// the base unit. Alternatively convert a px/pt font-size into the base unit.
 //
-// @param string $size
-//   A size from the $font-size map.
+// @param number|string $size
+//   A size from the $font-size map or px/pt value to be converted
 // @param number|string $context
-//   (optional) Only used if em is the $base-unit. The value of the parent 
+//   (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 the same unit as the $font-size map.
 //
@@ -12,52 +12,45 @@
 //   The selected font-size in $base-unit.
 @function font-size($size, $context: $base-font-size) {
   @if type-of($size) == 'string' {
-    @if map-has-key($font-size, $size) {
-      $map-size: map-get($font-size, $size);
-      @if $base-unit == px or $base-unit == pt {
-        @return output-unit(strip-unit($map-size));
-      }
-      @if $base-unit == rem {
-        @return output-unit(($map-size / $base-font-size));
-      }
-      @if $base-unit == em {
-        @if type-of($context) == 'string' {
-          @if map-has-key($font-size, $context) {
-            $context-map-size: map-get($font-size, $context);
-            @return output-unit(($map-size / $context-map-size));
-          }
-          @else {
-            @warn "'#{$context}' not found in $font-size map.";
-          }
-        }
-        @if type-of($context) == 'number' {
-          @if unit($context) == unit($base-font-size) {
-            @return output-unit(($map-size / $context));
-          }
-          @else {
-            @warn "The unit used for $context does not match the $base-font-size unit.";
-          }
-        }
-      }
+    @return output-from-font-size-map($size, $context);
+  }
+  @if type-of($size) == 'number' and not unitless($size) {
+    @if unit($size) == unit($base-font-size) {
+      @return convert-unit($size, $context);
     }
     @else {
-      @warn "'#{$size}' not found in $font-size map.";
+      @error "font-size() only accepts values with the same unit as $base-font-size.";
     }
   }
+  @else {
+    @error "font-size() only accepts keys from the font map or values in px or pt.";
+  }
 }
 
-// Define font-size (with fallback).
+// Define font-size (with fallback)
 //
-// @param string $size
-//   A size from the $font-size map.
+// @param number|string $size
+//   A size from the $font-size map or px/pt value to be converted
 // @param number|string $context
-//   (optional) Only used if em is the $base-unit. The value of the elements/parents 
+//   (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 the same unit as the $font-size map.
 @mixin font-size($size, $context: $base-font-size) {
-  $map-size: map-get($font-size, $size);
   @if $base-unit == rem {
-    font-size: $map-size;
+    @if $rem-fallback == true {
+      @if type-of($size) == 'string' {
+        $map-size: map-get($font-size, $size);
+        font-size: $map-size;
+      }
+      @if type-of($size) == 'number' and not unitless($size) {
+        @if unit($size) == unit($base-font-size) {
+          font-size: $size;
+        }
+        @else {
+          @error "font-size() only accepts values with the same unit as $base-font-size.";
+        }
+      }
+    }
   }
   font-size: font-size($size, $context);
-}
+}

data/stylesheets/typey/_font-stacks.scss

@@ -1,11 +1,11 @@
 // Three standard do-all stacks.
-$serif-stack:          TimesNewRoman, "Times New Roman", Times, Baskerville, Georgia, serif;
+$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.
 $arial-stack:         Arial, "Helvetica Neue", Helvetica, sans-serif;
-$helvetica-stack:    "Helvetica Neue", Helvetica, Arial, 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;
@@ -16,10 +16,10 @@ $trebuchet-ms-stack:  "Trebuchet MS", "Lucida Grande", "Lucida Sans Unicode", "L
 //   $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 
+//   The name of the font. Use inverted commas if there are spaces in the font
 //   name. i.e "Open sans"
 // @param list $font-stack
 //   The font stack variable to extend.
 @function extend-font-stack($font, $font-stack) {
   @return join($font, $font-stack, $separator: comma);
-}
+}