README.md in sane-scale-0.1.2 vs README.md in sane-scale-0.5.1

- old
+ new

@@ -1,5 +1,6 @@ + # Sane Scale Sane Scale 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. @@ -16,89 +17,99 @@ * Terminal: `gem install sane-scale` * Compass config.rb: `require 'sane-scale'` * SCSS: `@import 'sane-scale';` +Or create a new project with a sample config and type specimen: +* Terminal: `compass create project-name -r sane-scale --using sane-scale` + ## Usage ### Declare your fonts -For Sane Scale, fonts are defined via SASS maps in the following format: +Fonts are defined via SASS maps in the following format: ```scss // Default font $font-georgia: ( "family": unquote("Georgia, serif"), - "normalize-ratio": 1.00 -); + "font-size-adjustment": 1.00, + "line-height-adjustment": 1.00 +); // Additional fonts $font-verdana: ( "family": unquote("Verdana, sans-serif"), - "normalize-ratio": 0.89 + "font-size-adjustment": 0.89, + "line-height-adjustment": 0.93 ); $font-feather: ( "family": unquote("'Feather'"), - "normalize-ratio": 0.95 + "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 `normalize-ratio` property, additional fonts can be normalized to the default font. This will ensure they align to the modular scale. +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. -As an example, Verdana appears 11% larger than Georgia. To normalize it with Georgia, we can set a `normalize-ratio: 0.89`. This will cause Verdana to be 11% smaller than Georgia when both are set to the same size. +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`. -### Define your breakpoints -Sane Scale uses a SASS map of breakpoints (with relevant parameters) in the following format: +### Define your constraints +Provide constraints for your font scales via a SASS map in the following format: + ```scss -$breakpoints: ( +$font-scales: ( - // Phone sizes + // Phone sizes. "default": ( "base-font-size": 18px, "base-line-height": 1.5, "max-font-size": 28px, "max-line-height": 1.35, - "rounding": false + "round-under": 0px ), - // Tablet sizes and larger + // Tablet sizes and larger. "tablet": ( "media-query": "screen and (min-width: 600px)", - "base-font-size": 20px, + "base-font-size": 16px, "base-line-height": 1.6, "max-font-size": 42px, "max-line-height": 1.25, - "rounding": false + "round-under": 0px ) ); ``` -For each breakpoint, you'll need to specify a font-size and line-height for both the base size and the max size. Additional font-sizes and line-heights will be interpolated from these constraints. +For each scale, you'll need to specify a font-size and line-height for both the base size and the 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 breakpoint. Feel free to name the other breakpoints whatever you like. +A `media-query` property should also be set for each, exluding the default scale. Feel free to name the other scales whatever you like. +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. -### Build the scale -All thats left to do is to define the sizes you need and build the scale itself: +### Build your font scales +All that's left to do is to define the sizes you need and build the scale itself: + ```scss $numb-smaller-sizes: 1; $numb-larger-sizes: 4; -$sane-scale: ss-make-responsive-font-scale($breakpoints, $numb-smaller-sizes, $numb-larger-sizes); +$typography: ss-build-typography($font-scales, $numb-smaller-sizes, $numb-larger-sizes); ``` -That's it! Note that `$sane-scale` is a key variable. This map will be used by the following mixins to lookup and apply sizes. +That's it! Note that `$typography` is a key variable. This map will be used by the following mixins to lookup and apply sizes. ### Apply responsize sizing @@ -110,18 +121,18 @@ ```scss .lead { @include ss-set-responsive-font-size($font-georgia, 1); } ``` -We just applied responsive styling to a lead paragraph style. It will use `$font-georgia` at size 1 for each breakpoint: 20.1px by default, and then resizing to 24.1px for tablets and larger. +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 ss-set-responsive-font-size($font-verdana, 1); } ``` -We used the same size for the `.h4` heading, but with `$font-verdana`. That will result in a font-size of 17.9px by default and 21.4px for tablets and larger. Mathematically different, but visually equal. +We used the same size for the `.h4` heading, but with `$font-verdana`. That 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 @@ -131,6 +142,6 @@ .h4 { @include ss-set-font-size($font-verdana, 1, "tablet"); } ``` -Here we just styled our h4 to have the size 1 for only the tablet breakpoint. With `ss-set-responsive-font-size()` the corresponding sizes for each other breakpoint would have also been applied. \ No newline at end of file +Here we just styled our h4 to have the size 1 for only the tablet breakpoint. With `ss-set-responsive-font-size()` the corresponding sizes for each other breakpoint would have also been applied.