Source on Github

Vertical Rhythm

Create a vertical rhythm for your site by setting the $base-font-size and $base-line-height variables and then including the establish-baseline mixin at the root of your document.

Manage the vertical rhythm using the other vertical-rhythm mixins to adjust font and line-height values, extra vertical whitespace, borders, etc.

This file can be imported using: @import "compass/typography/vertical_rhythm"

Imports

  1. Grid Background

Configurable Variables help

16px

The base font size.

24px

The base line height determines the basic unit of vertical rhythm.

solid

Set the default border style for rhythm borders.

true

Set to false if you want to use absolute pixels in sizing your typography.

false

Allows the adjust-font-size-to mixin and the lines-for-font-size function to round the line height to the nearest half line height instead of the nearest integral line height to avoid large spacing between lines.

2px

Ensure there is at least this many pixels of vertical padding above and below the text.

if($relative-font-sizing, 1em, $base-font-size)

$base-font-size but in your output unit of choice. Defaults to 1em when $relative-font-sizing is true.

Constants

16px

The default font size in all browsers.

$base-line-height / $base-font-size * $font-unit

The basic unit of font rhythm.

($base-line-height - $base-font-size) * $font-unit / $base-font-size

The leader is the amount of whitespace in a line. It might be useful in your calculations.

$base-leader / 2

The half-leader is the amount of whitespace above and below a line. It might be useful in your calculations.

Functions

view source 

@function relative-unit($number)
  @return unit($number) == "%" or unit($number) == "em" or unit($number) == "rem"

@function relative-unit($number) {
  @return unit($number) == "%" or unit($number) == "em" or unit($number) == "rem";
}

True if a number has a relative unit.

view source 

@function absolute-unit($number)
  @return not (relative-unit($number) or unitless($number))

@function absolute-unit($number) {
  @return not (relative-unit($number) or unitless($number));
}

True if a number has an absolute unit.

view source 

@function rhythm($lines: 1, $font-size: $base-font-size, $offset: 0)
  @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 the rhythm function"
  $rhythm: $font-unit * ($lines * $base-line-height - $offset) / $font-size
  // Round the pixels down to nearest integer.
  @if unit($rhythm) == px
    $rhythm: floor($rhythm)
  @return $rhythm

@function rhythm($lines: 1, $font-size: $base-font-size, $offset: 0) {
  @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 the rhythm function";
  }
  $rhythm: $font-unit * ($lines * $base-line-height - $offset) / $font-size;
  // Round the pixels down to nearest integer.
  @if unit($rhythm) == px {
    $rhythm: floor($rhythm);
  }
  @return $rhythm;
}

Calculate rhythm units.

view source 

@function lines-for-font-size($font-size)
  $lines: if($round-to-nearest-half-line, ceil(2 * $font-size / $base-line-height) / 2, ceil($font-size / $base-line-height))
  @if $lines * $base-line-height - $font-size 

@function lines-for-font-size($font-size) {
  $lines: if($round-to-nearest-half-line, ceil(2 * $font-size / $base-line-height) / 2, ceil($font-size / $base-line-height));
  @if $lines * $base-line-height - $font-size

Calculate the minimum multiple of rhythm units needed to contain the font-size.

Mixins

view source 

=establish-baseline($font-size: $base-font-size)
  // IE 6 refuses to resize fonts set in pixels and it weirdly resizes fonts
  // whose root is set in ems. So we set the root font size in percentages of
  // the default font size.
  * html
    font-size: 100% * $font-size / $browser-default-font-size
  html
    font-size: $font-size
    +adjust-leading-to(1, if($relative-font-sizing, $font-size, $base-font-size))

@mixin establish-baseline($font-size: $base-font-size) {
  // IE 6 refuses to resize fonts set in pixels and it weirdly resizes fonts
  // whose root is set in ems. So we set the root font size in percentages of
  // the default font size.
  * html {
    font-size: 100% * $font-size / $browser-default-font-size;
  }
  html {
    font-size: $font-size;
    @include adjust-leading-to(1, if($relative-font-sizing, $font-size, $base-font-size));
  }
}

Establishes a font baseline for the given font-size.

view source 

=reset-baseline
  +adjust-leading-to(1, if($relative-font-sizing, $base-font-size, $base-font-size))

@mixin reset-baseline {
  @include adjust-leading-to(1, if($relative-font-sizing, $base-font-size, $base-font-size));
}

Resets the line-height to 1 vertical rhythm unit. Does not work on elements whose font-size is different from $base-font-size.

@deprecated This mixin will be removed in the next release. Please use the adjust-leading-to mixin instead.

view source 

=debug-vertical-alignment($img: false)
  @if $img
    background: image-url($img)
  @else
    +baseline-grid-background($base-rhythm-unit)

@mixin debug-vertical-alignment($img: false) {
  @if $img {
    background: image-url($img);
  }
  @else {
    @include baseline-grid-background($base-rhythm-unit);
  }
}

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 Compass default gradient image.

view source 

=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
    @warn "$relative-font-sizing is false but a relative font size was passed to adjust-font-size-to"
  font-size: $font-unit * $to-size / $from-size
  +adjust-leading-to($lines, if($relative-font-sizing, $to-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 {
    @warn "$relative-font-sizing is false but a relative font size was passed to adjust-font-size-to";
  }
  font-size: $font-unit * $to-size / $from-size;
  @include adjust-leading-to($lines, if($relative-font-sizing, $to-size, $base-font-size));
}

Adjust a block to have a different font size and 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. Use $from-size to adjust from a font-size other than the base font-size.

view source 

=adjust-leading-to($lines, $font-size: $base-font-size)
  line-height: rhythm($lines, $font-size)

@mixin adjust-leading-to($lines, $font-size: $base-font-size) {
  line-height: rhythm($lines, $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.

view source 

=leader($lines: 1, $font-size: $base-font-size, $property: margin)
  #{$property}-top: rhythm($lines, $font-size)

@mixin leader($lines: 1, $font-size: $base-font-size, $property: margin) {
  #{$property}-top: rhythm($lines, $font-size);
}

Apply leading whitespace. The $property can be margin or padding.

view source 

=padding-leader($lines: 1, $font-size: $base-font-size)
  padding-top: rhythm($lines, $font-size)

@mixin padding-leader($lines: 1, $font-size: $base-font-size) {
  padding-top: rhythm($lines, $font-size);
}

Apply leading whitespace as padding.

view source 

=margin-leader($lines: 1, $font-size: $base-font-size)
  margin-top: rhythm($lines, $font-size)

@mixin margin-leader($lines: 1, $font-size: $base-font-size) {
  margin-top: rhythm($lines, $font-size);
}

Apply leading whitespace as margin.

view source 

=trailer($lines: 1, $font-size: $base-font-size, $property: margin)
  #{$property}-bottom: rhythm($lines, $font-size)

@mixin trailer($lines: 1, $font-size: $base-font-size, $property: margin) {
  #{$property}-bottom: rhythm($lines, $font-size);
}

Apply trailing whitespace. The $property can be margin or padding.

view source 

=padding-trailer($lines: 1, $font-size: $base-font-size)
  padding-bottom: rhythm($lines, $font-size)

@mixin padding-trailer($lines: 1, $font-size: $base-font-size) {
  padding-bottom: rhythm($lines, $font-size);
}

Apply trailing whitespace as padding.

view source 

=margin-trailer($lines: 1, $font-size: $base-font-size)
  margin-bottom: rhythm($lines, $font-size)

@mixin margin-trailer($lines: 1, $font-size: $base-font-size) {
  margin-bottom: rhythm($lines, $font-size);
}

Apply trailing whitespace as margin.

view source 

=rhythm($leader: 0, $padding-leader: 0, $padding-trailer: 0, $trailer: 0, $font-size: $base-font-size)
  +leader($leader, $font-size)
  +padding-leader($padding-leader, $font-size)
  +padding-trailer($padding-trailer, $font-size)
  +trailer($trailer, $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 padding-leader($padding-leader, $font-size);
  @include padding-trailer($padding-trailer, $font-size);
  @include trailer($trailer, $font-size);
}

Shorthand mixin to apply whitespace for top and bottom margins and padding.

view source 

=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
    @warn "$relative-font-sizing is false but a relative font size was passed to apply-side-rhythm-border"
  border-#{$side}:
    style: $border-style
    width: $font-unit * $width / $font-size
  padding-#{$side}: rhythm($lines, $font-size, $offset: $width)

@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 {
    @warn "$relative-font-sizing is false but a relative font size was passed to apply-side-rhythm-border";
  }
  border-#{$side}: {
    style: $border-style;
    width: $font-unit * $width / $font-size;
  };
  padding-#{$side}: rhythm($lines, $font-size, $offset: $width);
}

Apply a border and whitespace to any side without destroying the vertical rhythm. The whitespace must be greater than the width of the border.

view source 

=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
    @warn "$relative-font-sizing is false but a relative font size was passed to rhythm-borders"
  border:
    style: $border-style
    width: $font-unit * $width / $font-size
  padding: rhythm($lines, $font-size, $offset: $width)

@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 {
    @warn "$relative-font-sizing is false but a relative font size was passed to rhythm-borders";
  }
  border: {
    style: $border-style;
    width: $font-unit * $width / $font-size;
  };
  padding: rhythm($lines, $font-size, $offset: $width);
}

Apply borders and whitespace equally to all sides.

view source 

=leading-border($width: 1px, $lines: 1, $font-size: $base-font-size, $border-style: $default-rhythm-border-style)
  +apply-side-rhythm-border(top, $width, $lines, $font-size, $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);
}

Apply a leading border.

view source 

=trailing-border($width: 1px, $lines: 1, $font-size: $base-font-size, $border-style: $default-rhythm-border-style)
  +apply-side-rhythm-border(bottom, $width, $lines, $font-size, $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);
}

Apply a trailing border.

view source 

=horizontal-borders($width: 1px, $lines: 1, $font-size: $base-font-size, $border-style: $default-rhythm-border-style)
  +leading-border($width, $lines, $font-size, $border-style)
  +trailing-border($width, $lines, $font-size, $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 trailing-border($width, $lines, $font-size, $border-style);
}

Apply both leading and trailing borders.

view source 

=h-borders($width: 1px, $lines: 1, $font-size: $base-font-size, $border-style: $default-rhythm-border-style)
  +horizontal-borders($width, $lines, $font-size, $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);
}

Alias for horizontal-borders mixin.