Q
Version: 1.1.alpha.0
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
  2. Browser Support – Provides configuration options for the Compass Browser Support Matrix.
  3. compass/typography/units

Configurable Variables help

16px

The default font size for all text in pixels

24px

The distance between text baselines (vertical rhythm) in pixels.

"em"

The length unit in which to output rhythm values. Supported values: px, em, rem. Percent units can't be used since they make calculating padding and margins impractical, and percentage borders are not valid or supported in css.

true

Whether to output fallback values in px when using rem as the rhythm-unit.

1px

Default values for rhythm borders properties. Supports style alone eg. solid or list of style and color eg. solid #aaa;

solid

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.

Constants

convert-length($base-line-height - $base-font-size, $rhythm-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 rhythm($lines: 1, $font-size: $base-font-size, $offset: 0)
  $rhythm: convert-length($lines * $base-line-height - $offset, $rhythm-unit, $font-size)
  @if unit($rhythm) == px
    $rhythm: floor($rhythm)
  @return $rhythm

@function rhythm($lines: 1, $font-size: $base-font-size, $offset: 0) {
  $rhythm: convert-length($lines * $base-line-height - $offset, $rhythm-unit, $font-size);
  @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 are cramped include some extra lead.
  @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 are cramped include some extra lead.
  @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)
  $relative-size: 100% * $font-size / $browser-default-font-size
  @if support-legacy-browser(ie, "6") and not $relative-font-sizing
    // 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, even if we are using absolute sizes elsewhere.
    * html
      font-size: $relative-size
  html
    font-size: if($relative-font-sizing, $relative-size, $font-size)
    // Webkit has a bug that prevents line-height being set in rem on ;
    // To work around this and simplify output, we can set initial line-height
    // in ems for all relative rhythm units, even when $rhythm-unit is `rem`.
    @if $relative-font-sizing
      line-height: convert-length($base-line-height, em)
    @else
      line-height: round($base-line-height)

@mixin establish-baseline($font-size: $base-font-size) {
  $relative-size: 100% * $font-size / $browser-default-font-size;
  @if support-legacy-browser(ie, "6") and not $relative-font-sizing {
    // 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, even if we are using absolute sizes elsewhere.
    * html {
      font-size: $relative-size;
    }
  }
  html {
    font-size: if($relative-font-sizing, $relative-size, $font-size);
    // Webkit has a bug that prevents line-height being set in rem on ;
    // To work around this and simplify output, we can set initial line-height
    // in ems for all relative rhythm units, even when $rhythm-unit is `rem`.
    @if $relative-font-sizing {
      line-height: convert-length($base-line-height, em);
    }
    @else {
      line-height: round($base-line-height);
    }
  }
}

Establishes a font baseline for the given font-size.

view source 

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

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

Resets the baseline to 1 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 adjust-leading-to(1) instead.

view source 

=debug-vertical-alignment($img: false)
  @if $img
    background: image-url($img)
  @else
    +baseline-grid-background(if($round-to-nearest-half-line, rhythm(1 / 2), rhythm(1)))

@mixin debug-vertical-alignment($img: false) {
  @if $img {
    background: image-url($img);
  }
  @else {
    @include baseline-grid-background(if($round-to-nearest-half-line, rhythm(1 / 2), rhythm(1)));
  }
}

Show a background image that can be used to debug your alignments. As this is a development feature, this mixin never outputs pixel fallbacks for rem output. 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: auto, $from-size: $base-font-size)
  $to-size: convert-length($to-size, px, $from-size)
  @if $lines == auto
    $lines: lines-for-font-size($to-size)
  +output-rhythm(font-size, convert-length($to-size, $rhythm-unit, $from-size))
  +adjust-leading-to($lines, $to-size)

@mixin adjust-font-size-to($to-size, $lines: auto, $from-size: $base-font-size) {
  $to-size: convert-length($to-size, px, $from-size);
  @if $lines == auto {
    $lines: lines-for-font-size($to-size);
  }
  @include output-rhythm(font-size, convert-length($to-size, $rhythm-unit, $from-size));
  @include adjust-leading-to($lines, $to-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)
  +output-rhythm(line-height, rhythm($lines, $font-size))

@mixin adjust-leading-to($lines, $font-size: $base-font-size) {
  @include output-rhythm(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)
  +output-rhythm(#{$property}-top, rhythm($lines, $font-size))

@mixin leader($lines: 1, $font-size: $base-font-size, $property: margin) {
  @include output-rhythm(#{$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)
  +output-rhythm(padding-top, rhythm($lines, $font-size))

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

Apply leading whitespace as padding.

view source 

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

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

Apply leading whitespace as margin.

view source 

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

@mixin trailer($lines: 1, $font-size: $base-font-size, $property: margin) {
  @include output-rhythm(#{$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)
  +output-rhythm(padding-bottom, rhythm($lines, $font-size))

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

Apply trailing whitespace as padding.

view source 

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

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

Apply trailing whitespace as margin.

view source 

=rhythm($leader: 1, $padding-leader: 0, $padding-trailer: $padding-leader, $trailer: $leader, $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: 1, $padding-leader: 0, $padding-trailer: $padding-leader, $trailer: $leader, $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 

=rhythm-margins($leader: 1, $trailer: $leader, $font-size: $base-font-size)
  +leader($leader, $font-size)
  +trailer($trailer, $font-size)

@mixin rhythm-margins($leader: 1, $trailer: $leader, $font-size: $base-font-size) {
  @include leader($leader, $font-size);
  @include trailer($trailer, $font-size);
}

Shorthand mixin to apply whitespace for top and bottom margins.

view source 

=rhythm-padding($padding-leader: 1, $padding-trailer: $padding-leader, $font-size: $base-font-size)
  +padding-leader($padding-leader, $font-size)
  +padding-trailer($padding-trailer, $font-size)

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

Shorthand mixin to apply whitespace for top and bottom padding.

view source 

=apply-side-rhythm-border($side, $width: $default-rhythm-border-width, $lines: 1, $font-size: $base-font-size, $border-style: $default-rhythm-border-style)
  // If applying borders to all sides, use shorthand properties
  $border-prop: if($side == all, border, border-#{$side})
  +output-rhythm(#{$border-prop}-width, convert-length($width, $rhythm-unit, $font-size))
  #{$border-prop}-style: nth($border-style, 1)
  @if type-of($border-style) == list and length($border-style) > 1
    #{$border-prop}-color: nth($border-style, 2)
  $padding-prop: if($side == all, padding, padding-#{$side})
  +output-rhythm(#{$padding-prop}, rhythm($lines, $font-size, $offset: $width))

@mixin apply-side-rhythm-border($side, $width: $default-rhythm-border-width, $lines: 1, $font-size: $base-font-size, $border-style: $default-rhythm-border-style) {
  // If applying borders to all sides, use shorthand properties
  $border-prop: if($side == all, border, border-#{$side});
  @include output-rhythm(#{$border-prop}-width, convert-length($width, $rhythm-unit, $font-size));
  #{$border-prop}-style: nth($border-style, 1);
  @if type-of($border-style) == list and length($border-style) > 1 {
    #{$border-prop}-color: nth($border-style, 2);
  }
  $padding-prop: if($side == all, padding, padding-#{$side});
  @include output-rhythm(#{$padding-prop}, 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 

=leading-border($width: $default-rhythm-border-width, $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: $default-rhythm-border-width, $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. $border-style and $width are deprecated and will be removed in a future version of Compass.

view source 

=trailing-border($width: $default-rhythm-border-width, $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: $default-rhythm-border-width, $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: $default-rhythm-border-width, $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: $default-rhythm-border-width, $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: $default-rhythm-border-width, $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: $default-rhythm-border-width, $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.

view source 

=rhythm-borders($width: $default-rhythm-border-width, $lines: 1, $font-size: $base-font-size, $border-style: $default-rhythm-border-style)
  +apply-side-rhythm-border(all, $width, $lines, $font-size, $border-style)

@mixin rhythm-borders($width: $default-rhythm-border-width, $lines: 1, $font-size: $base-font-size, $border-style: $default-rhythm-border-style) {
  @include apply-side-rhythm-border(all, $width, $lines, $font-size, $border-style);
}

Apply borders and whitespace equally to all sides.