github-migration/compass
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge pull request #771 from JohnAlbin/docs-vertical-rhythm

Browse Source 
Improve documentation of veritcal_rhythm partial.
This commit is contained in:
Chris Eppstein 2012-03-12 10:23:54 -07:00
commit a700e5d521
1 changed files with 37 additions and 32 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

69
frameworks/compass/stylesheets/compass/typography/_vertical_rhythm.scss
View File

@ -1,18 +1,18 @@
@import "compass/layout/grid-background"; @import "compass/layout/grid-background";
// The base font size // The base font size.
$base-font-size: 16px !default; $base-font-size: 16px !default;
// The base line height is the basic unit of line hightness. // The base line height determines the basic unit of vertical rhythm.
$base-line-height: 24px !default; $base-line-height: 24px !default;
// set the default border style for rhythm borders // Set the default border style for rhythm borders.
$default-rhythm-border-style: solid !default; $default-rhythm-border-style: solid !default;
// The IE font ratio is a fact of life. Deal with it. // The IE font ratio is a fact of life. Deal with it.
$ie-font-ratio: 16px / 100%; $ie-font-ratio: 16px / 100%;
// Set to false if you want to use absolute pixes in sizing your typography. // Set to false if you want to use absolute pixels in sizing your typography.
$relative-font-sizing: true !default; $relative-font-sizing: true !default;
// Allows the `adjust-font-size-to` mixin and the `lines-for-font-size` function // Allows the `adjust-font-size-to` mixin and the `lines-for-font-size` function
@ -25,26 +25,26 @@ $round-to-nearest-half-line: false !default;
$min-line-padding: 2px !default; $min-line-padding: 2px !default;
// $base-font-size but in your output unit of choice. // $base-font-size but in your output unit of choice.
// Defaults to 1em when `$relative-font-sizing` // Defaults to 1em when `$relative-font-sizing` is true.
$font-unit: if($relative-font-sizing, 1em, $base-font-size) !default; $font-unit: if($relative-font-sizing, 1em, $base-font-size) !default;
// The basic unit of font rhythm // The basic unit of font rhythm.
$base-rhythm-unit: $base-line-height / $base-font-size * $font-unit; $base-rhythm-unit: $base-line-height / $base-font-size * $font-unit;
// The leader is the amount of whitespace in a line. // The leader is the amount of whitespace in a line.
// It might be useful in your calculations // It might be useful in your calculations.
$base-leader: ($base-line-height - $base-font-size) * $font-unit / $base-font-size; $base-leader: ($base-line-height - $base-font-size) * $font-unit / $base-font-size;
// The half-leader is the amount of whitespace above and below a line. // The half-leader is the amount of whitespace above and below a line.
// It might be useful in your calculations // It might be useful in your calculations.
$base-half-leader: $base-leader / 2; $base-half-leader: $base-leader / 2;
// True if a number has a relative unit // True if a number has a relative unit.
@function relative-unit($number) { @function relative-unit($number) {
@return unit($number) == "%" or unit($number) == "em" or unit($number) == "rem" @return unit($number) == "%" or unit($number) == "em" or unit($number) == "rem"
} }
// True if a number has an absolute unit // True if a number has an absolute unit.
@function absolute-unit($number) { @function absolute-unit($number) {
@return not (relative-unit($number) or unitless($number)); @return not (relative-unit($number) or unitless($number));
} }
@ -53,7 +53,7 @@ $base-half-leader: $base-leader / 2;
@warn "$relative-font-sizing is true but $font-unit is set to #{$font-unit} which is not a relative unit."; @warn "$relative-font-sizing is true but $font-unit is set to #{$font-unit} which is not a relative unit.";
} }
// Establishes a font baseline for the given font-size in pixels // Establishes a font baseline for the given font-size.
@mixin establish-baseline($font-size: $base-font-size) { @mixin establish-baseline($font-size: $base-font-size) {
body { body {
font-size: $font-size / $ie-font-ratio; font-size: $font-size / $ie-font-ratio;
@ -70,7 +70,7 @@ $base-half-leader: $base-leader / 2;
} }
// Show a background image that can be used to debug your alignments. // Show a background image that can be used to debug your alignments.
// include the $img argument if you would rather use your own image than the // Include the $img argument if you would rather use your own image than the
// Compass default gradient image. // Compass default gradient image.
@mixin debug-vertical-alignment($img: false) { @mixin debug-vertical-alignment($img: false) {
@if $img { @if $img {
@ -80,11 +80,11 @@ $base-half-leader: $base-leader / 2;
} }
} }
// Adjust a block to have a different font size and leading to maintain the rhythm. // Adjust a block to have a different font size and line height to maintain the
// $lines is a number that is how many times the baseline rhythm this // rhythm. $lines specifies how many multiples of the baseline rhythm each line
// font size should use up. Does not have to be an integer, but it defaults // of this font should use up. It does not have to be an integer, but it
// to the smallest integer that is large enough to fit the font. // defaults to the smallest integer that is large enough to fit the font.
// Use $from_size to adjust from a non-base font-size. // Use $from-size to adjust from a font-size other than the base font-size.
@mixin adjust-font-size-to($to-size, $lines: lines-for-font-size($to-size), $from-size: $base-font-size) { @mixin adjust-font-size-to($to-size, $lines: lines-for-font-size($to-size), $from-size: $base-font-size) {
@if not $relative-font-sizing and $from-size != $base-font-size { @if not $relative-font-sizing and $from-size != $base-font-size {
@warn "$relative-font-sizing is false but a relative font size was passed to adjust-font-size-to"; @warn "$relative-font-sizing is false but a relative font size was passed to adjust-font-size-to";
@ -93,6 +93,10 @@ $base-half-leader: $base-leader / 2;
@include adjust-leading-to($lines, if($relative-font-sizing, $to-size, $base-font-size)); @include adjust-leading-to($lines, if($relative-font-sizing, $to-size, $base-font-size));
} }
// Adjust a block to have different line height to maintain the rhythm.
// $lines specifies how many multiples of the baseline rhythm each line of this
// font should use up. It does not have to be an integer, but it defaults to the
// smallest integer that is large enough to fit the font.
@mixin adjust-leading-to($lines, $font-size: $base-font-size) { @mixin adjust-leading-to($lines, $font-size: $base-font-size) {
@if not $relative-font-sizing and $font-size != $base-font-size { @if not $relative-font-sizing and $font-size != $base-font-size {
@warn "$relative-font-sizing is false but a relative font size was passed to adjust-leading-to"; @warn "$relative-font-sizing is false but a relative font size was passed to adjust-leading-to";
@ -100,7 +104,7 @@ $base-half-leader: $base-leader / 2;
line-height: $font-unit * $lines * $base-line-height / $font-size; line-height: $font-unit * $lines * $base-line-height / $font-size;
} }
// Calculate rhythm units // Calculate rhythm units.
@function rhythm( @function rhythm(
$lines: 1, $lines: 1,
$font-size: $base-font-size $font-size: $base-font-size
@ -112,6 +116,7 @@ $base-half-leader: $base-leader / 2;
@return $rhythm; @return $rhythm;
} }
// Calculate the minimum multiple of rhythm units needed to contain the font-size.
@function lines-for-font-size($font-size) { @function lines-for-font-size($font-size) {
$lines: if($round-to-nearest-half-line, $lines: if($round-to-nearest-half-line,
ceil(2 * $font-size / $base-line-height) / 2, ceil(2 * $font-size / $base-line-height) / 2,
@ -122,7 +127,7 @@ $base-half-leader: $base-leader / 2;
@return $lines; @return $lines;
} }
// Apply leading whitespace // Apply leading whitespace. The $property can be margin or padding.
@mixin leader($lines: 1, $font-size: $base-font-size, $property: margin) { @mixin leader($lines: 1, $font-size: $base-font-size, $property: margin) {
$leader: rhythm($lines, $font-size); $leader: rhythm($lines, $font-size);
@if unit($leader) == px { @if unit($leader) == px {
@ -131,17 +136,17 @@ $base-half-leader: $base-leader / 2;
#{$property}-top: $leader; #{$property}-top: $leader;
} }
// Apply leading whitespace as padding // Apply leading whitespace as padding.
@mixin padding-leader($lines: 1, $font-size: $base-font-size) { @mixin padding-leader($lines: 1, $font-size: $base-font-size) {
@include leader($lines, $font-size, padding); @include leader($lines, $font-size, padding);
} }
// Apply leading whitespace as margin // Apply leading whitespace as margin.
@mixin margin-leader($lines: 1, $font-size: $base-font-size) { @mixin margin-leader($lines: 1, $font-size: $base-font-size) {
@include leader($lines, $font-size, margin); @include leader($lines, $font-size, margin);
} }
// Apply trailing whitespace // Apply trailing whitespace. The $property can be margin or padding.
@mixin trailer($lines: 1, $font-size: $base-font-size, $property: margin) { @mixin trailer($lines: 1, $font-size: $base-font-size, $property: margin) {
$leader: rhythm($lines, $font-size); $leader: rhythm($lines, $font-size);
@if unit($leader) == px { @if unit($leader) == px {
@ -150,18 +155,17 @@ $base-half-leader: $base-leader / 2;
#{$property}-bottom: $leader; #{$property}-bottom: $leader;
} }
// Apply trailing whitespace as padding // Apply trailing whitespace as padding.
@mixin padding-trailer($lines: 1, $font-size: $base-font-size) { @mixin padding-trailer($lines: 1, $font-size: $base-font-size) {
@include trailer($lines, $font-size, padding); @include trailer($lines, $font-size, padding);
} }
// Apply trailing whitespace as margin // Apply trailing whitespace as margin.
@mixin margin-trailer($lines: 1, $font-size: $base-font-size) { @mixin margin-trailer($lines: 1, $font-size: $base-font-size) {
@include trailer($lines, $font-size, margin); @include trailer($lines, $font-size, margin);
} }
// Whitespace application shortcut // Shorthand mixin to apply whitespace for top and bottom margins and padding.
// Apply top margin/padding + bottom padding/margin
@mixin rhythm($leader: 0, $padding-leader: 0, $padding-trailer: 0, $trailer: 0, $font-size: $base-font-size) { @mixin rhythm($leader: 0, $padding-leader: 0, $padding-trailer: 0, $trailer: 0, $font-size: $base-font-size) {
@include leader($leader, $font-size); @include leader($leader, $font-size);
@include padding-leader($padding-leader, $font-size); @include padding-leader($padding-leader, $font-size);
@ -169,8 +173,8 @@ $base-half-leader: $base-leader / 2;
@include trailer($trailer, $font-size); @include trailer($trailer, $font-size);
} }
// Apply a border width to any side without destroying the vertical rhythm. // Apply a border and whitespace to any side without destroying the vertical
// The available space ($lines) must be greater than the width of your border. // rhythm. The whitespace must be greater than the width of the border.
@mixin apply-side-rhythm-border($side, $width: 1px, $lines: 1, $font-size: $base-font-size, $border-style: $default-rhythm-border-style) { @mixin apply-side-rhythm-border($side, $width: 1px, $lines: 1, $font-size: $base-font-size, $border-style: $default-rhythm-border-style) {
@if not $relative-font-sizing and $font-size != $base-font-size { @if not $relative-font-sizing and $font-size != $base-font-size {
@warn "$relative-font-sizing is false but a relative font size was passed to apply-side-rhythm-border"; @warn "$relative-font-sizing is false but a relative font size was passed to apply-side-rhythm-border";
@ -182,7 +186,7 @@ $base-half-leader: $base-leader / 2;
padding-#{$side}: $font-unit / $font-size * ($lines * $base-line-height - $width); padding-#{$side}: $font-unit / $font-size * ($lines * $base-line-height - $width);
} }
// Aplly rhythm borders equally to all sides // Apply borders and whitespace equally to all sides.
@mixin rhythm-borders($width: 1px, $lines: 1, $font-size: $base-font-size, $border-style: $default-rhythm-border-style) { @mixin rhythm-borders($width: 1px, $lines: 1, $font-size: $base-font-size, $border-style: $default-rhythm-border-style) {
@if not $relative-font-sizing and $font-size != $base-font-size { @if not $relative-font-sizing and $font-size != $base-font-size {
@warn "$relative-font-sizing is false but a relative font size was passed to rhythm-borders"; @warn "$relative-font-sizing is false but a relative font size was passed to rhythm-borders";
@ -193,22 +197,23 @@ $base-half-leader: $base-leader / 2;
padding: $font-unit / $font-size * ($lines * $base-line-height - $width); padding: $font-unit / $font-size * ($lines * $base-line-height - $width);
} }
// Apply a leading rhythm border // Apply a leading border.
@mixin leading-border($width: 1px, $lines: 1, $font-size: $base-font-size, $border-style: $default-rhythm-border-style) { @mixin leading-border($width: 1px, $lines: 1, $font-size: $base-font-size, $border-style: $default-rhythm-border-style) {
@include apply-side-rhythm-border(top, $width, $lines, $font-size, $border-style); @include apply-side-rhythm-border(top, $width, $lines, $font-size, $border-style);
} }
// Apply a trailing rhythm border // Apply a trailing border.
@mixin trailing-border($width: 1px, $lines: 1, $font-size: $base-font-size, $border-style: $default-rhythm-border-style) { @mixin trailing-border($width: 1px, $lines: 1, $font-size: $base-font-size, $border-style: $default-rhythm-border-style) {
@include apply-side-rhythm-border(bottom, $width, $lines, $font-size, $border-style); @include apply-side-rhythm-border(bottom, $width, $lines, $font-size, $border-style);
} }
// Apply both leading and trailing rhythm borders // Apply both leading and trailing borders.
@mixin horizontal-borders($width: 1px, $lines: 1, $font-size: $base-font-size, $border-style: $default-rhythm-border-style) { @mixin horizontal-borders($width: 1px, $lines: 1, $font-size: $base-font-size, $border-style: $default-rhythm-border-style) {
@include leading-border($width, $lines, $font-size, $border-style); @include leading-border($width, $lines, $font-size, $border-style);
@include trailing-border($width, $lines, $font-size, $border-style); @include trailing-border($width, $lines, $font-size, $border-style);
} }
// Alias for `horizontal-borders` mixin.
@mixin h-borders($width: 1px, $lines: 1, $font-size: $base-font-size, $border-style: $default-rhythm-border-style) { @mixin h-borders($width: 1px, $lines: 1, $font-size: $base-font-size, $border-style: $default-rhythm-border-style) {
@include horizontal-borders($width, $lines, $font-size, $border-style); @include horizontal-borders($width, $lines, $font-size, $border-style);
} }