type-director 0.8

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 7f3c69ad4cffb5ad9de8771730d4896f8d70bea8
+  data.tar.gz: 157eda8173d909e5d61baf484ea462a47adb1d1c
+SHA512:
+  metadata.gz: 26eae284ce0b33847e048e2b8e194c243e88632e8ce1924c7e409796a5c6ce57bfe45beebad8d3329f2f66b787174c7bc737874549b7086f6e2c7cbbadb287e3
+  data.tar.gz: 463a852223ec99cfe9921f983b8c0deb23a780e8a1ab460c5371a3bf9f694a20ddcfa078d364b54d38edabfa1059688686e8f8a39852dce922c2ec9683b7672f

data/README.md

@@ -0,0 +1,207 @@
+
+# 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. 
+
+
+
+## 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.
+
+
+
+## Install 
+
+* Terminal: `gem install type-director`
+* Compass config.rb: `require 'type-director'`
+* SCSS: `@import 'type-director';`
+
+Or create a new project with a sample config and type specimen:
+
+* Terminal: `compass create project-name -r type-director --using type-director`
+
+
+## Usage
+
+### Declare your fonts
+
+Fonts are defined via SASS maps in the following format:
+
+```scss
+// Default font
+
+$font-georgia: (
+	"family": unquote("Georgia, serif"),
+	"font-size-adjustment": 1.00,
+	"line-height-adjustment": 1.00
+);
+
+// Additional fonts
+
+$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
+);
+```
+
+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.
+
+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`.
+
+
+
+### Build font scales
+
+From a few constraints, `td-build-typography` builds a modular scale for each specified media query.
+
+```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
+		)
+	),
+
+	// Other than the base, how many 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.
+
+If you need a bit of typographic guidance, [Responsive Typography: The Basics](https://ia.net/know-how/responsive-typography-the-basics "Responsive Typography: The Basics") by Information Architects is an excellent read.
+
+
+
+### 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: 
+* 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);
+}
+```
+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.
+
+```scss
+.h4 { 
+	@include td-set-responsive-font-size($font-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.
+
+
+
+### 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:
+
+```scss
+.h4 { 
+	@include td-set-font-size($font-verdana, 1, "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.
+
+
+## Advanced Usage
+
+### Rounding 
+
+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
+		),
+
+		// ...
+));
+```
+
+### Solid and tight line-height
+
+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"));
+}
+```
+
+Other times you may want to set text to be solid (meaning no "leading"). In terms of CSS, this setting the line-height to be equal to the font-size. To do this, use the `"line-height": "solid"` option.
+
+```scss
+.btn { 
+	@include td-set-responsive-font-size($font-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:
+
+```scss
+$font-verdana: (
+	"family": unquote("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));
+}
+```
+

data/lib/type-director.rb

@@ -0,0 +1,30 @@
+# All gems that are required for this extension to work should go here.
+# These are the requires you would normally put in your config.rb file
+# By default, you should always included Compass. Do not include your
+#  extension.
+require 'compass'
+require 'sassy-math'
+
+# This tells Compass what your Compass extension is called, 
+# and where to find its files. Replace 'extension' with the 
+# name of your extension. Spaces allowed.
+extension_path = File.expand_path(File.join(File.dirname(__FILE__), ".."))
+Compass::Frameworks.register('type-director', :path => extension_path)
+
+# Version and date of version for your Compass extension.
+# Replace Extension with the name of your extension. Letters, 
+# numbers, and underscores only. Version is a number. If a 
+# 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"
+  DATE = "2016-08-14"
+end
+
+# This is where any custom SassScript should be placed. The functions will be  
+#  available on require of your extension without the need for users to import
+#  any partials. Uncomment below.
+
+# module Sass::Script::Functions
+# 
+# end

data/stylesheets/_type-director.scss

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

data/stylesheets/type-director/_build-font-scale.scss

@@ -0,0 +1,57 @@
+ 
+// Create a modular font scale. 
+// Returns a nested list of font-size and line-height values.
+
+@function td-build-font-scale($opts: ()) {
+
+	// Extend default opts
+	$opts: map-merge((
+		"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 font-size scale
+	$font-size-scale: td-build-scale((
+		"base-value": map-get($opts, "base-font-size"),
+		"max-value": map-get($opts, "max-font-size"),
+		"numb-smaller-values": map-get($opts, "numb-smaller-sizes"),
+		"numb-larger-values": map-get($opts, "numb-larger-sizes")
+	));
+
+	// Create line-height scale
+	$line-height-scale: td-build-scale((
+		"base-value": map-get($opts, "base-line-height"),
+		"max-value": map-get($opts, "max-line-height"),
+		"numb-smaller-values": map-get($opts, "numb-smaller-sizes"),
+		"numb-larger-values": map-get($opts, "numb-larger-sizes")
+	));
+
+	$sizes: ();
+	
+	// Pair each size with the correponding font-size 
+	// and line-height, then add the size to the scale.
+	@for $i from -(map-get($opts, "numb-smaller-sizes")) to map-get($opts, "numb-larger-sizes") + 1 {
+		
+		// Calculate array position in order to lookup sizes in lists.
+		$arr-position: $i + map-get($opts, "numb-smaller-sizes") + 1;
+
+		// Key for size
+		$name-of-size: $i;
+
+		// Values for size
+		$values: (
+			"font-size": nth($font-size-scale, $arr-position),
+			"line-height": nth($line-height-scale, $arr-position)
+		);
+
+		// Add to size array.
+		$sizes: map-merge($sizes, ($name-of-size: $values));
+	}
+
+	$font-scale: map-merge($opts, ("sizes": $sizes));
+	@return $font-scale;
+}

data/stylesheets/type-director/_build-scale.scss

@@ -0,0 +1,41 @@
+
+// Create a modular scale. Returns a list of values.
+
+@function td-build-scale($opts: ()) {
+
+	// Extend default opts
+	$opts: map-merge((
+		"base-value": 16px,
+		"max-value": 28px,
+		"numb-smaller-values": 1,
+		"numb-larger-values": 4
+	), $opts);
+
+	$base-value: map-get($opts, "base-value");
+	$max-value: map-get($opts, "max-value");
+	$numb-larger-values: map-get($opts, "numb-larger-values");
+	$numb-smaller-values: map-get($opts, "numb-smaller-values");
+
+	// Build the scale.
+	$scale: ();
+
+	// The ratio we'll use to calculate the missing sizes.
+	$scaling-ratio: nth-root($max-value / $base-value, $numb-larger-values); 
+
+	// Calculate and add smaller values to the scale.
+	@for $i from -$numb-smaller-values through -1 {
+		$size: $base-value * power($scaling-ratio, $i);
+		$scale: append($scale, $size);
+	}
+
+	// Add the base value to the scale.
+	$scale: append($scale, $base-value);
+
+	// Calculate and add larger values to the scale.
+	@for $i from 1 through ($numb-larger-values) {
+		$size: $base-value * power($scaling-ratio, $i);
+		$scale: append($scale, $size);
+	}
+
+	@return $scale;
+}

data/stylesheets/type-director/_build-typography.scss

@@ -0,0 +1,46 @@
+
+// Augments a breakpoint map by building a "scale" property
+// containing the specified sizes to each breakpoint.
+
+@function td-build-typography($opts: ()) {
+
+	// Extend default opts
+	$opts: map-merge((
+		"scales": (
+			"default": (
+				"base-font-size": 16px,
+				"base-line-height": 1.5,
+				"max-font-size": 28px,
+				"max-line-height": 1.35
+			),
+			"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
+			)
+		),
+		"numb-smaller-sizes": 1,
+		"numb-larger-sizes": 4
+	), $opts);
+
+	// The object we'll return.
+	$typography: ();
+
+	// Create a scale for each breakpoint.
+	@each $font-scale-name, $font-scale-opts in map-get($opts, "scales") {
+
+		// Merge global opts with scale-specific opts
+		$font-scale-opts: map-merge($font-scale-opts, (
+			"numb-smaller-sizes": map-get($opts, "numb-smaller-sizes"),
+			"numb-larger-sizes": map-get($opts, "numb-larger-sizes")
+		));
+
+		// Create a font scale.
+		$font-scale: td-build-font-scale($font-scale-opts);
+		$typography: map-merge($typography, ($font-scale-name: $font-scale));
+	}
+
+	@return $typography;
+}

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

@@ -0,0 +1,6 @@
+@function map-deep-get($map, $keys...) {
+  @each $key in $keys {
+    $map: map-get($map, $key);
+  }
+  @return $map;
+}

data/stylesheets/type-director/_round.scss

@@ -0,0 +1,8 @@
+ 
+// Round a value to any precision
+
+@function td-round($value: 1.0, $precision: 1.0) {
+	$scale: 1 / $precision;
+	$result: round($value * $scale) / $scale;
+	@return $result;
+}

data/stylesheets/type-director/_set-font-size.scss

@@ -0,0 +1,136 @@
+/******************************************************
+* MIXINS
+******************************************************/
+
+// Apply styles for a specific font, breakpoint, and size.
+@mixin td-apply-font-styles($font, $size, $scale-name, $opts: ()) {
+
+	// Extend default opts
+	$opts: map-merge((
+		"uppercase": false,
+		"line-height": "normal"
+	), $opts);
+
+	// FONT SIZE
+	// Get and apply adjustments.
+
+	$unadjusted-font-size: map-deep-get($typography, $scale-name, "sizes", $size, "font-size"); 
+	$font-size-adjustment: map-get($font, "font-size-adjustment") or 1.00;
+	$uppercase-adjustment: map-get($font, "uppercase-adjustment") or 1.00;
+
+	@if map-get($opts, "uppercase") {
+		$font-size-adjustment: $font-size-adjustment * $uppercase-adjustment;
+	}
+
+	$font-size: $unadjusted-font-size * $font-size-adjustment;
+
+	// Round font-size.
+	$font-size-precision: map-deep-get($typography, $scale-name, "font-size-precision") or null;
+	@if ($font-size-precision) {
+        $font-size: td-round($font-size, $font-size-precision);
+    } 
+	
+
+
+	// LINE HEIGHT
+	// Get and apply adjustments.
+
+	$line-height-setting: map-get($opts, "line-height");
+	$unadjusted-line-height: null;
+	$line-height: null;
+
+	// Use line-height associated with scale and size.
+	$normal-line-height: map-deep-get($typography, $scale-name, "sizes", $size, "line-height");
+
+	// No space between lines. 1.0 if unitless, otherwise equal to font-size.
+	$solid-line-height: if(unitless($normal-line-height), 1.0, $font-size);
+	
+	// Halfway between default and solid line-height.
+	$tight-line-height: (($normal-line-height - $solid-line-height) / 2) + $solid-line-height;
+	
+	// If line-height is set to solid, use 1.0 or font-size.
+	@if $line-height-setting == "solid" { 
+		$line-height: $solid-line-height;
+
+	} @else {
+
+		// Line-height setting determines corresponding basis.
+		@if $line-height-setting == "tight" {
+    		$unadjusted-line-height: $tight-line-height;
+		} @else {
+			$unadjusted-line-height: $normal-line-height;
+		}
+
+		// Apply adjustments.
+		$line-height-adjustment: map-get($font, "line-height-adjustment") or 1.00;
+
+		// If using relative line heights, the font-size-adjustment will 
+		// affect the line-height. This removes the unwanted effect.
+		@if unitless($unadjusted-line-height) { 
+			$line-height-adjustment: $line-height-adjustment * (1 / $font-size-adjustment);
+		}
+
+		$line-height: $unadjusted-line-height * $line-height-adjustment;
+	}
+
+	// Round line-height.
+	$line-height-precision: map-deep-get($typography, $scale-name, "line-height-precision") or null;
+	@if ($line-height-precision) {
+		$line-height: td-round($line-height, $line-height-precision);
+	}
+
+	font-size: $font-size; 
+	line-height: $line-height;
+}
+
+// Apply non-responsive styling. Only the size used for
+// the specified media query will be applied.
+@mixin td-set-font-size($font, $size, $scale-name, $opts: ()) {
+	
+	// Extend default opts
+	$opts: map-merge((
+		"uppercase": false,
+		"line-height": "normal"
+	), $opts);
+
+	font-family: map-get($font, "family");
+
+	@if map-get($opts, "uppercase") {
+		text-transform: uppercase;
+	}
+
+	@include td-apply-font-styles($font, $size, $scale-name, $opts);
+}
+
+// Apply responsive styling. Corresponding sizes for
+// each media query will be applied.
+@mixin td-set-responsive-font-size($font, $size: 0, $opts: ()) {
+	
+	// Extend default opts
+	$opts: map-merge((
+		"uppercase": false,
+		"line-height": "normal"
+	), $opts);
+
+	font-family: map-get($font, "family");
+
+	@if map-get($opts, "uppercase") {
+		text-transform: uppercase;
+	}
+
+	@each $scale-name, $scale-value in $typography {
+
+		// For the default styles, don't include a media query.
+		@if $scale-name == "default" {
+			@include td-apply-font-styles($font, $size, $scale-name, $opts);
+		}
+
+		// For other breakpoints, set style with a media query.
+		@else {
+			$media-query: map-deep-get($typography, $scale-name, "media-query");
+			@media #{$media-query} {
+				@include td-apply-font-styles($font, $size, $scale-name, $opts);
+			} 
+		}
+	}
+}