type-director 0.8 → 0.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7f3c69ad4cffb5ad9de8771730d4896f8d70bea8
-  data.tar.gz: 157eda8173d909e5d61baf484ea462a47adb1d1c
+  metadata.gz: 1a07ea61bcc2bb553dd26cdd142224b67198eca5
+  data.tar.gz: 257a8e2ee3726c18ad8e2d02d95415300a958c7f
 SHA512:
-  metadata.gz: 26eae284ce0b33847e048e2b8e194c243e88632e8ce1924c7e409796a5c6ce57bfe45beebad8d3329f2f66b787174c7bc737874549b7086f6e2c7cbbadb287e3
-  data.tar.gz: 463a852223ec99cfe9921f983b8c0deb23a780e8a1ab460c5371a3bf9f694a20ddcfa078d364b54d38edabfa1059688686e8f8a39852dce922c2ec9683b7672f
+  metadata.gz: 608d93c0744c122b5eb73e660eb38ea5680f615258b566fec5d97bd113152956e150567aa3fc5ec297b34e8b6e409bca39978912ed7e7734db1422c3c3256efb
+  data.tar.gz: 516936a7ce8c135002f2e687e08ff0b40b13c9121cc70c1740745af1b69e564f626950c74635c07d91fcf946346b8710c8d041b7260c65f35af3423eea715463

data/README.md

@@ -1,15 +1,15 @@
 
 # Type Director
 
-Type Director is a SASS framework for defining and applying typographic styles. Its goal is to generate a complex, nuanced typographic system from only a few key variables. 
+Type Director is a SASS framework that generates a responsive, modular, nuanced typographic system from only a few key variables.
 
 
 
 ## Features
 
 1. Modular. Typographic measurements are based on proportional lists of values. 
-2. Responsive. Typography adjusts to the constraints of each breakpoint.
-3. Font rebalancing. Different fonts set to the same size often don't appear to be. Fonts are normalized, so every font appears to be exactly the size you intend.
+2. Responsive. Typography adjusts to the unique constraints of each breakpoint.
+3. Nuanced. Various properties allow detail-oriented typographers to align additional fonts or uppercase styles to a modular scale.
 
 
 
@@ -26,78 +26,87 @@ Or create a new project with a sample config and type specimen:
 
 ## Usage
 
-### Declare your fonts
+### Declare your typefaces
 
-Fonts are defined via SASS maps in the following format:
+Typefaces associate a font-family with various typeface-specific adjustments. Define them via SASS maps in the following format:
 
 ```scss
-// Default font
+$typefaces: (
 
-$font-georgia: (
-	"family": unquote("Georgia, serif"),
-	"font-size-adjustment": 1.00,
-	"line-height-adjustment": 1.00
-);
+	// Default typeface
+	"georgia": (
+		"family": (Georgia, serif),
+		"font-size-adjustment": 1.00,
+		"line-height-adjustment": 1.00
+	),
 
-// Additional fonts
+	// Additional typefaces
+	"verdana": (
+		"family": (Verdana, sans-serif),
+		"font-size-adjustment": 0.89,
+		"line-height-adjustment": 0.94
+	),
 
-$font-verdana: (
-	"family": unquote("Verdana, sans-serif"),
-	"font-size-adjustment": 0.89,
-	"line-height-adjustment": 0.93
-);
- 
-$font-feather: (
-	"family": unquote("'Feather'"),
-	"font-size-adjustment": 0.95,
-	"line-height-adjustment": 1.00
-);
+	"feather": (
+		"family": ("Feather"),
+		"font-size-adjustment": 1.00,
+		"line-height-adjustment": 1.00
+	)
+)
 ```
 
-Oftentimes two fonts set to the same size do not appear to be. This is because the heights of their lowercase letters are not equal. By using the `font-size-adjustment` property, additional fonts can be normalized to the default font. This will ensure they align to the modular scale.
+Oftentimes two typfaces set to the same font-size do not appear to be. This is because the heights of their lowercase letters are not equal. By using the `font-size-adjustment` property, additional typefaces can be normalized to the default typeface. This will ensure they align to the modular scale.
 
 For example, Verdana appears 11% larger than Georgia. To normalize it with Georgia, we can set a `font-size-adjustment: 0.89`. This will cause Verdana to be 11% smaller than Georgia when set to the same size.
 
-Similarly, you can also apply an adjustment to line-height on a font-by-font basis by specifying a `line-height-adjustment`.
+Similarly, you can also apply an adjustment to line-height on a typeface-by-typeface basis by specifying a `line-height-adjustment`.
 
 
 
-### Build font scales
+### Declare your environments
 
-From a few constraints, `td-build-typography` builds a modular scale for each specified media query.
+Environments associate media queries with a modular type scale. Define them via SASS maps in the following format:
 
 ```scss
-$typography: td-build-typography((	
-
-	// Define your font scales and their constraints.
-	"scales": (
-
-		// Phone sizes 
-		"default": (
-			"base-font-size": 16px,
-			"base-line-height": 1.5,
-			"max-font-size": 28px,
-			"max-line-height": 1.35
-		),
-
-		// Tablet sizes and larger 
-		"tablet": (
-			"media-query": "screen and (min-width: 768px)",
-			"base-font-size": 18px,
-			"base-line-height": 1.6,
-			"max-font-size": 42px,
-			"max-line-height": 1.25
-		)
+$environments: (
+
+	// Phone sizes 
+	"phone": (
+		"base-font-size": 16px,
+		"base-line-height": 1.5,
+		"max-font-size": 28px,
+		"max-line-height": 1.35
 	),
 
-	// Other than the base, how many sizes do you need?
+	// Tablet sizes and larger 
+	"tablet": (
+		"media-query": "screen and (min-width: 768px)",
+		"base-font-size": 18px,
+		"base-line-height": 1.6,
+		"max-font-size": 42px,
+		"max-line-height": 1.25
+	)
+);
+```
+For each environment, you'll need to specify font-size and line-height for both a base size and a max size. A type scale for each environment will be interpolated from these constraints.
+
+A `media-query` property should also be set for each environment, except for the environment you'd like to be default.
+
+
+
+### Build typography
+
+```scss
+$typography: td-typography(
+
+	"typefaces": $typefaces,
+	"environments": $environments,
+
+	// Other than the base, how many type sizes do you need?
 	"numb-smaller-sizes": 1,
 	"numb-larger-sizes": 4
-));
+);
 ```
-For each scale, you'll need to specify font-size and line-height for both a base size and a max size. Additional font-sizes and line-heights will be interpolated from these constraints.
-
-A `media-query` property should also be set for each, exluding the "default" scale. Feel free to name the other scales whatever you like.
 
 That's it! Note that `$typography` is a key variable. This map will be used by the following mixins to lookup and apply sizes.
 
@@ -107,38 +116,40 @@ If you need a bit of typographic guidance, [Responsive Typography: The Basics](h
 
 ### Apply responsize sizing
 
-Use `@include td-set-responsive-font-size($font, $size)` to apply a responsive size. The sizes available to you are based on your parameters: 
+Use `@include td-responsive-type-size($typface-name, $size)` to apply a responsive size. The type sizes available to you are based on your parameters: 
 * 0 is your base size.
 * 1, 2, 3... are your increasingly larger sizes.
 * -1, -2, -3... are your increasingly smaller sizes.
 
 ```scss
 .lead {
-	@include td-set-responsive-font-size($font-georgia, 1);
+	@include td-responsive-type-size("georgia", 1);
 }
 ```
-We just applied responsive styling to the lead paragraph style. It will use media queries to apply `$font-georgia` at size `1` from the corresponding scale: 18.4px by default, and then resizing to 22.2px for tablets and larger.
+We just applied responsive styling to the lead paragraph style. It will use media queries to apply Georgia at size `1` from the corresponding scale: 18.4px for phone, and then resizing to 22.2px for tablets and larger.
 
 ```scss
 .h4 { 
-	@include td-set-responsive-font-size($font-verdana, 1);
+	@include td-responsive-type-size("verdana", 1);
 }
 ```
-We used the same size for the `.h4` heading, but with `$font-verdana`. This will result in a font-size of 16.4px by default and 19.8px for tablets and larger. Mathematically different, but visually equal.
+We used the same size for the `.h4` heading, but with Verdana. This will result in a font-size of 16.4px for phones and 19.8px for tablets and larger. Mathematically different than Georgia at size `1`, but visually equal.
 
 
 
 ### Apply static sizing
 
-You might occassionally want finer-grained control of your type styles. For these cases, use the `td-set-font-size()` mixin which accepts an additional `$breakpoint` parameter:
+You might occassionally want finer-grained control of your type styles. For these cases, use the `td-type-size()` mixin which accepts an additional `$environment-name` parameter:
 
 ```scss
 .h4 { 
-	@include td-set-font-size($font-verdana, 1, "tablet");
+	@include td-font-size("verdana", 1, "phone");
+	@include td-font-size("verdana", 2, "tablet");
 }
 ```
 
-Here we just styled our h4 to have the size 1 for only the tablet breakpoint. With `td-set-responsive-font-size()` the corresponding sizes for each other breakpoint would have also been applied.
+Here we just applied size 1 for phones and size 2 for tablets. If we had used `td-set-responsive-font-size()` the same size would have been applied for each environment. 
+
 
 
 ## Advanced Usage
@@ -148,32 +159,30 @@ Here we just styled our h4 to have the size 1 for only the tablet breakpoint. Wi
 Rounding to any precision is supported. 
 
 ```scss
-$typography: td-build-typography((	
-
-	// Define your font scales and their constraints.
-	"scales": (
-
-		// Phone sizes 
-		"default": (
-			"base-font-size": 16px,
-			"base-line-height": 1.5,
-			"max-font-size": 28px,
-			"max-line-height": 1.35,
-			"font-size-precision": 0.1,
-			"line-height-precision": 0.01
-		),
-
-		// ...
-));
+$environments: (
+
+	"phone": (
+		"base-font-size": 16px,
+		"base-line-height": 1.5,
+		"max-font-size": 28px,
+		"max-line-height": 1.35,
+		"font-size-precision": 0.1,
+		"line-height-precision": 0.01
+	),
+
+	// ...
+);
 ```
 
-### Solid and tight line-height
+
+
+### Solid and tight line-heights
 
 Oftentimes you may need to set very narrow lines of text, causing your line-height to look too loose. For a tighter line-height, use the `"line-height": "tight"` option.
 
 ```scss
 .caption-tight { 
-	@include td-set-responsive-font-size($font-verdana, -1, $opts: ("line-height": "tight"));
+	@include td-responsive-type-size("verdana", -1, $opts: ("line-height": "tight"));
 }
 ```
 
@@ -181,27 +190,45 @@ Other times you may want to set text to be solid (meaning no "leading"). In term
 
 ```scss
 .btn { 
-	@include td-set-responsive-font-size($font-verdana, 1, $opts: ("line-height": "solid"));
+	@include td-responsive-type-size("verdana", 1, $opts: ("line-height": "solid"));
 }
 ```
 
+
+
 ### Uppercase styles
 
-If you'd like to set something in all caps and have it align to your font scales, include an `uppercase-adjustment` when defining fonts:
+If you'd like to set something in all caps and have it align to your type scales, include an `uppercase-adjustment` when defining fonts:
 
 ```scss
-$font-verdana: (
-	"family": unquote("Verdana, sans-serif"),
-	"font-size-adjustment": 0.89,
-	"line-height-adjustment": 0.94,
-	"uppercase-adjustment": 0.85
-);
+$typefaces: (
+
+	"verdana": (
+		"family": (Verdana, sans-serif),
+		"font-size-adjustment": 0.89,
+		"line-height-adjustment": 0.94,
+		"uppercase-adjustment": 0.85
+	),
+
+	// ...
+)
 ```
 
 Apply an uppercase style like so:
 ```scss
 .h4 { 
-	@include td-set-responsive-font-size($font-verdana, 1, $opts: ("uppercase": true));
+	@include td-responsive-type-size("verdana", 1, $opts: ("uppercase": true));
 }
 ```
 
+
+
+### Overrides
+
+You can use `td-override-type-size($environment-name, $size, $font-size, $line-heigt) to override a type size after typography has been built.
+
+```scss
+$typography: td-override-type-size("tablet", -1, 12px, 1.8);
+```
+
+

data/lib/type-director.rb

@@ -17,7 +17,7 @@ Compass::Frameworks.register('type-director', :path => extension_path)
 # version contains alphas, it will be created as a 
 # prerelease version. Date is in the form of YYYY-MM-DD
 module TypeDirector
-  VERSION = "0.8"
+  VERSION = "0.9"
   DATE = "2016-08-14"
 end
 

data/stylesheets/_type-director.scss

@@ -1,10 +1,12 @@
-@import "type-director/map-deep-get";
-@import "type-director/build-scale";
-@import "type-director/build-font-scale";
-@import "type-director/build-typography";
+@import "type-director/map-get-deep";
+@import "type-director/map-set-deep";
+@import "type-director/scale";
+@import "type-director/type-scale";
+@import "type-director/environment";
+@import "type-director/typography";
 
-$typography: td-build-typography() !default; 
+$typography: td-typography() !default; 
  
 @import "type-director/round";
-@import "type-director/set-font-size";
+@import "type-director/type-size";
 

data/stylesheets/type-director/_environment.scss

@@ -0,0 +1,29 @@
+ 
+// Returns an environment profile, which associates a 
+// media query with a type-scale and other parameters.
+
+@function td-environment($opts: ()) {
+
+	// Extend default opts with passed opts.
+	$opts: map-merge((
+		"media-query": null,
+		"font-size-precision": null,
+		"line-height-precision": null,
+		"base-font-size": 16px,
+		"base-line-height": 1.5,
+		"max-font-size": 28px,
+		"max-line-height": 1.35,
+		"numb-smaller-sizes": 1,
+		"numb-larger-sizes": 4
+	), $opts);
+
+	// Create environment.
+	$environment: (
+		"media-query": map-get($opts, "media-query"),
+		"font-size-precision": map-get($opts, "font-size-precision"),
+		"line-height-precision": map-get($opts, "line-height-precision"),
+		"sizes": td-type-scale($opts)
+	);
+
+	@return $environment;
+}

data/stylesheets/type-director/_map-get-deep.scss

@@ -0,0 +1,12 @@
+/// Map deep get
+/// @author Hugo Giraudel
+/// @access public
+/// @param {Map} $map - Map
+/// @param {Arglist} $keys - Key chain
+/// @return {*} - Desired value
+@function map-get-deep($map, $keys...) {
+    @each $key in $keys {
+        $map: map-get($map, $key);
+    }
+    @return $map;
+}

data/stylesheets/type-director/_map-set-deep.scss

@@ -0,0 +1,48 @@
+/// Deep set function to set a value in nested maps
+/// @author Hugo Giraudel
+/// @access public
+/// @param {Map} $map - Map
+/// @param {List} $keys -  Key chaine
+/// @param {*} $value - Value to assign
+/// @return {Map}
+@function map-set-deep($map, $keys, $value) {
+  $maps: ($map,);
+  $result: null;
+  
+  // If the last key is a map already
+  // Warn the user we will be overriding it with $value
+  @if type-of(nth($keys, -1)) == "map" {
+    @warn "The last key you specified is a map; it will be overrided with `#{$value}`.";
+  }
+  
+  // If $keys is a single key
+  // Just merge and return
+  @if length($keys) == 1 {
+    @return map-merge($map, ($keys: $value));
+  }
+  
+  // Loop from the first to the second to last key from $keys
+  // Store the associated map to this key in the $maps list
+  // If the key doesn't exist, throw an error
+  @for $i from 1 through length($keys) - 1 {
+    $current-key: nth($keys, $i);
+    $current-map: nth($maps, -1);
+    $current-get: map-get($current-map, $current-key);
+    @if $current-get == null {
+      @error "Key `#{$key}` doesn't exist at current level in map.";
+    }
+    $maps: append($maps, $current-get);
+  }
+  
+  // Loop from the last map to the first one
+  // Merge it with the previous one
+  @for $i from length($maps) through 1 {
+    $current-map: nth($maps, $i);
+    $current-key: nth($keys, $i);
+    $current-val: if($i == length($maps), $value, $result);
+    $result: map-merge($current-map, ($current-key: $current-val));
+  }
+  
+  // Return result
+  @return $result;
+}

data/stylesheets/type-director/_override-type-size.scss

@@ -0,0 +1,4 @@
+@function td-override-type-size($environment-name, $size, $font-size, $line-height) {
+  	map-set-deep($typography, "environments", $environment-name, "sizes", $size, "font-size", $font-size);
+  	map-set-deep($typography, "environments", $environment-name, "sizes", $size, "line-height", $line-height);
+}