Calcite Web has a helpful set of mixins for composing type. We recommend you use these mixins wherever possible when writing your own components as it will keep the visual proportions and styles in line with the rest of the framework.

By default, using the Calcite Web sass files will build css for the complete framework. This build can be customized, or entirely turned off for sass-only applications.

Setting the $generate-css variable to false in your sass files will prevent any css from being generated, while exposing all the underlying sass styles of the framework. Setting specific variables like $include-alerts to false will preclude only that components css from being built.

Additionally, font imports are controlled this way. By default, Calcite Web requests Avenir Next from a cdn. You can import calcite-web-no-fonts.scss if you don't want the fonts.

// Sass Output
$include-colors:                 true    !default;
$generate-css:                   true    !default;

// Language Helpers
$include-right-to-left:          $generate-css    !default;

// Grid Output
$include-reset:                  $generate-css    !default;
$include-utils:                  $generate-css    !default;

$include-grid:                   $generate-css    !default;
  $fold-grid:                    $generate-css    !default;
  $block-grid:                   $generate-css    !default;

// Grid Utilities Output
$include-leader-trailer:         $generate-css    !default;
$include-gutter:                 $generate-css    !default;
$include-left-right:             $generate-css    !default;
$include-show-hide:              $generate-css    !default;
$include-sticky:                 $generate-css    !default;

// Type Output
$include-type:                   $generate-css    !default;
  $include-primary-family:       true             !default;
  $include-code-family:          $generate-css    !default;
  $include-i18n:                 $generate-css    !default;
  $include-type-defaults:        $generate-css    !default;
  $include-type-helpers:         $generate-css    !default;

// Icons
$include-icons:                  $generate-css    !default;
  $include-calcite-icons:        $generate-css    !default;
  $include-social-icons:         $generate-css    !default;
  $include-icon-font:            $generate-css    !default;

// Components
$include-alerts:                 $generate-css    !default;
$include-badges:                 $generate-css    !default;
$include-labels:                 $generate-css    !default;
$include-tables:                 $generate-css    !default;
$include-panel:                  $generate-css    !default;
$include-button:                 $generate-css    !default;
$include-dropdowns:              $generate-css    !default;
$include-breadcrumbs:            $generate-css    !default;
$include-tooltip:                $generate-css    !default;
$include-forms:                  $generate-css    !default;
$include-input-groups:           $generate-css    !default;
$include-loader:                 $generate-css    !default;
$include-skip-to-content:        $generate-css    !default;
$include-logo:                   $generate-css    !default;
$include-card:                   $generate-css    !default;
$include-animation:              $generate-css    !default;

// Patterns
$include-footer:                 $generate-css    !default;
$include-sticky-footer:          $generate-css    !default;
$include-pagination:             $generate-css    !default;
$include-side-nav:               $generate-css    !default;
$include-sub-nav:                $generate-css    !default;
$include-third-nav:              $generate-css    !default;
$include-top-nav:                $generate-css    !default;
$include-user-nav:               $generate-css    !default;
$include-app-switcher:           $generate-css    !default;

// Javascript
$include-tabs:                   $generate-css    !default;
$include-modal:                  $generate-css    !default;
$include-accordion:              $generate-css    !default;
$include-drawers:                $generate-css    !default;
$include-sticky:                 $generate-css    !default;
$include-filter-dropdown:        $generate-css    !default;

Example

// custom-build.scss
$generate-css: false;
$include-type: true;
$include-grid: true;
$fold-grid:  true;
$block-grid: true;
$include-leader-trailer: true;
$include-gutter: true;
$include-left-right: true;
$include-show-hide: true;
$include-sticky: true;

@import 'calcite-web'

The above sass will import the framework, import the type styles, and build css that provides access to the type helpers and grid system. Notice that the variable declarations are before the import.

Calcite Web comes with several variables. These variables represent project-standard configurations of different aspects. For example, $baseline can be used in your Sass to set a property to the default typographic baseline of Calcite Web.

These variables can also be configured in your own project to change the library for project-specific applications.

Below are all of the variables and a brief description of what they represent.

Breakpoints

Calcite Web comes with several variables representing the default screen sizes.

// Breakpoints
$small:  480px  !default;
$medium: 860px  !default;
$large:  1280px !default;

In static classes, these breakpoints are often expressed as phone-, tablet-, desktop-.

UI Variables

Controls specific aspects and behaviors across the UI.

$transition: 150ms linear;
$box-shadow: 0 0 16px 0 rgba(0,0,0,0.05) !default;
$drawer-width: 280px !default;
$easing-function: cubic-bezier(0.215, 0.440, 0.420, 0.880) !default;
$namespace-tables: true !default;

$transition is a speed and easing function used throughout the framework for motion effects.

$box-shadow ensures consistent box shadow effects for adding depths to elements.

$drawer-width controls the width of the hidden left and right drawers.

$easing-function is a default timing function used by moving elements like modals. If you'd like to change how modals move in, you can tweak this variable (or use a browser-supplied funciton like linear)

$namespace-tables scopes <table> styles to the .table class. To mimic the behavior of previous versions (where we automatically style raw table elements), set this to false.

Calcite Web has a helpful set of mixins for composing type. We recommend you use these mixins wherever possible when writing your own components as it will keep the visual proportions and styles in line with the rest of the framework.

Font Family

You can set the font family and weight via the following Sass mixins:

@include avenir-light();   // font-weight: 300
@include avenir-regular(); // font-weight: 400
@include avenir-italic();  // font-style: italic
@include avenir-bold();    // font-weight: 700
@include code-face();      // font-family: $code-family

When changing between styles of Avenir Next, you can also simply set the font-weight and font-style properties in CSS and the correct font will also be rendered. The corresponding CSS property values have been noted as comments in the list above.

Font Size

The Calcite Web type system uses a modular typographic scale to ensure a consistent tonal range within all text elements. This modular scale is created from the body size of the type, and a second, smaller size. These two type sizes anchor the scale, and using a precise ratio can be expanded to an entire set of sizes for all typographic needs.

The font-size($n) mixin takes an integer, positive or negative, and sets all type within the element to the size defined by traversing that number of steps up or down the typographic scale.

'0' represents the normal text size while '-1' is a type size smaller, and '1' is a type size larger. So if you'd like to have a very large pull-quote or something of that nature, you could use @include font-size(6). This means that the text you've styled will be six steps up the typographic scale from the normal body size.

The font-size($n) mixin relies on the modular-scale($n) mixin to define the scale, and apply it to typographic elements.

Text Alignment

The text-right and text-left mixins are useful to set text alignment. These mixins will automatically reverse in right to left languages.

@include text-right();
@include text-left();

Modular Scale

The modular-scale($n) behaves the same as the font-size($n) mixin, but returns a raw rem value rather than css styles specific to type elements. This means that the modular-scale($n) mixin can be used to define heights, widths, padding, margins, or any other property of an element so that it adheres to the modular scale defined by the typography. Setting the max width of an article to a large multiple of the text size is a way to define a comfortable reading measure related to the proportional decisions of the content.

Tracking

Tracking is the space between letters in a word. The tracking($n) mixin accepts an integer, and applies letterspacing to the element as fractions of 1/1000 of an em. @include tracking(500) will apply 1/2 em letterspacing. @include tracking(166) will apply a hairline em letterspacing.

Leading

Leading is the space between lines in a text block. The leading($n) mixin accepts an integer, and sets the line height of the element to the integer times the standard baseline unit.

Word Spacing

Word spacing is - well - the space between words. The word-spacing($n) mixin accepts an integer, and applies letterspacing to the element as fractions of 1/1000 of an em. If you're familiar with word-spacing in design programs like Adobe InDesign, the word-spacing mixin will immidiately feel fairly natural.

While you can pass any integer to the mixin, below is a list of values you can pass to the word-spacing mixin to achieve well known typographic defaults:

Calcite web has several mixins to help add space to your designs. Read on to learn how you can use mixins apply margin and padding to each side of an element.

Leader and trailer

To add space above and below content, you can use the leader and trailer mixins. These mixins utilize the $baseline unit, and will scale with your base type size and baseline.

@include leader(3);         // add three units of margin above element
@include leader-half();
@include leader-quarter();
@include trailer(2);        // add two units of margin below element
@include trailer-half();
@include trailer-quarter();

Padding leader and trailer

If you'd prefer this space be added using padding instead of margin, use the padding-leader mixins:

// pass the amount of space you'd like to the mixin:
@include padding-leader(2);
@include padding-trailer(6);

// for smaller amounts, use the following with no argument passed in
@include padding-leader-half();
@include padding-leader-quarter();
@include padding-trailer-half();
@include padding-trailer-quarter();

Gutter

To add space on either the right or left side, use the gutter mixins:

// add space in increments of 1 $baseline
@include gutter-left($n);
@include margin-gutter-left($n);
@include gutter-right($n);
@include margin-gutter-right($n);

// common fractional gutters (call without arguments)
@include gutter-left-quarter();
@include margin-gutter-left-quarter();
@include gutter-right-quarter();
@include margin-gutter-right-quarter();
@include gutter-left-third();
@include margin-gutter-left-third();
@include gutter-right-third();
@include margin-gutter-right-third();
@include gutter-left-half();
@include margin-gutter-left-half();
@include gutter-right-half();
@include margin-gutter-right-half();

Utility Mixins

Utility mixins are used to construct complicated behaviors for components and patterns, provide baseline functionality for doc elements, and take care of browser prefixing.

Most utility mixins are borrowed from Bourbon. If mixins share a name, then they share the same code base.

Use the utility mixins inside the selector you wish to apply the styles to, passing the arguments in if required. For example, to apply a clearfix to an element with the class .my-div, the use the following Sass:

.my-div {
  @include clearfix();
}

If the mixin accepts arguments, pass them into the parenthesis:

.my-div {
  @include box-sizing(border-box);
}

Quick Reference

Animation

The animation mixin allows you to declare cross-browser animations. The mixin accepts

box:hover {
  @include animation(scale 1.0s ease-in, slide 2.0s ease);
}

Or, use individual animation mixins:

box:hover {
  @include animation-name(scale, slide);
  @include animation-duration(2s);
  @include animation-timing-function(ease);
  @include animation-iteration-count(infinite);
}

Appearance

The appearance CSS property is used to display an element using a platform-native styling based on the operating system's theme. For example, to remove browser specific styling for a ui element, use:

@include appearance(none);

Border

For adding borders that flip in right to left languages, use the border- mixins:

// set all in one argument
@include border-right(1px solid $blue);
@include border-left(none);

// set just the color
@include border-color-right($blue);
@include border-color-left($off-white);

Box-Sizing

Set the box-sizing property for all browsers (with browser prefixes):

@include box-sizing(border-box);

Valid values are content-box, border-box, and inherit.

Box-Shadow

Set the box-shadow property for all browsers (with browser prefixes):

@include box-shadow(border-box);

Calc

Shorthand for setting a property to use a calc value. Pass the property you'd like to set, then the value you'd like to use:

@include calc(width, '100px - 10%');

Clearfix

Applies the framework-standard clear for floated elements:

@include clearfix();

Keyframes

For creating animations, you can use the keyframes mixin. This mixin accepts an animation name. Then inside the mixin, write your animation as a content block:

@include keyframes(ANIMATION_NAME){
  0%   { background-color: #ffccf2; }
  100% { background-color: #ccffff; }
};

Now you can use the animation mixin as a named animation like this:

.animation-class {
  @include animation( @include animation(ANIMATION_NAME 200ms ease-in);)
}

Placeholder

Wraps the wide array of input placeholder selectors across browsers.

@include placeholder('color', $dark-blue);

Position

Set right and left properties (automatically flips in right-to-left languages).

@include position-right(4px);
@include position-left(0);

Prefixer

This is one of the most flexible mixins in the library. Use it to add browser prefixes to a property:

@include prefixer(margin-end, 5%, webkit moz spec);

In this way you can prefix any property. Adding the spec as the last argument will also output the property without a prefix.

Respond To

The respond-to mixin adds media queries for use in responsive design. The mixin accepts three arguments: maximum size, minimum size, and type (screen, print, etc). You can pass just the first out of convenience. This mixin works well with the breakpoint variables:

.my-div {
  @include respond-to($small){
    padding: 1rem;
  }
}

This will compile to the following css:

@media screen and (max-width: 480px) {
  .my-div {
    padding: 1rem;
  }
}

You can assemble more complicated media queries by using both min and max:

@include respond-to($large, $medium) { ... }

This will add styles that only appear between the $medium and $large screen sizes.

Transform

The CSS transform property lets you modify the coordinate space of the CSS visual formatting model. Using it, elements can be translated, rotated, scaled, and skewed according to the values set. transform, transform-origin, and transform-style all add the necessary browser prefixes for interacting with their respective transform properties.

@include transform(translateY(50px));
@include transform(scale(0.9) rotate(-3deg));
@include transform-origin(center top);
@include transform-style(preserve-3d);

Transition

This mixin provides a shorthand syntax and supports multiple transitions.

@include transition(all 2.0s ease-in-out);
@include transition(opacity 1.0s ease-in 0s, width 2.0s ease-in 2s);

Or you can use the individual transition properties:

@include transition-property(transform);
@include transition-duration(1.0s);
@include transition-timing-function(ease-in);
@include transition-delay(0.5s);

Transition Prefixed

To transition vendor-prefixed properties, e.g. -webkit-transform and -moz-transform, there is an additional convinience transition-prefixed() mixin:

@include transition-prefixed(transform3d(0,0,0) 200ms linear);

This will generate vendor prefixed properties and values.

Visibility

The visibility mixins change the visibility property. This is useful for removing and adding elements at certain breakpoints or with certain class names. No arguments are passed. Invisible sets visibility: hidden on the object, leaving in the in document flow, but removing it from view. hide() will completely remove the item with display:none.

@include hide();
@include invisible();
@include visible();