Usage

Dialtone is available in both Dialpad and UberConference. Listed below are general examples of how to use Dialtone. Specific information on the styles and components available can be found in the left-hand navigation.

Writing CSS

At Dialpad we've adopted the BEM (Block Element Modifier) methodology for writing CSS. This is a simple, common naming convention that helps make our CSS easier to read and understand.

If you aren't familiar with the approach, here's a quick synposis of the approach (definitions taken from BEM's introduction page):

  • Block: A parent entity that is meaningful on its own. For example: .d-input, .d-table, or .d-tooltip.
  • Element: A child that is meaningful only in relation to its parent. For example: .d-input__label, .d-table__cell, or .d-tooltip__icon.
  • Modifier: A modifying flag on a Block or Element. This changes appearance or behavior. For example: .d-input--lg, .d-table--inverted, or .d-tooltip--top-left.

Using Dialtone in Less

The preferred method of incorporating Dialtone into Dialpad and UberConference is by using it within a semantic CSS class, written in Less. Less is a powerful CSS pre-processor much like SCSS or SASS. It allows you to create and modify variables, utilize mixins, create functions, and incorporate styles within other classes easily.

Given that we prefer semantic classes as compared to utility or atomic classes, this means that Dialtone only provides classes and styles for items which reflect design decisions. For example, Dialtone provides set spacing sizes (e.g. .d-m16 == margin: 16px;), but it does not provide common CSS properties in single-purpose classes (e.g. .d-float--left == float: left;).

Here's an example of how you include Dialtone in your Less:

/* Import Dialtone definitions. Ensure the relative path is correct. */
@import (reference) "../../css/dialtone.less";

/* Dialtone documentation navigation bar */
.dialtone-navbar {
position: fixed;
.d-top-bottom1();
.d-left1();
.d-width100();
.d-border-right-radius--lg();
background-color: @ash;
color: @slate;
overflow-y: scroll;
overflow-x: hidden;
}

This compiles to:

.dialtone-navbar {
position: fixed;
top: 0.1rem;
bottom: 0.1rem;
left: 0.1rem;
width: 100%;
border-top-right-radius: 1.2rem;
border-bottom-right-radius: 1.2rem;
background-color: #F1F2F4;
color: #4C4E56;
overflow-y: scroll;
overflow-x: hidden;
}

Using Dialtone in Dialpad

Vue

Using Dialtone in Vue requires setting your style lang to less, importing Dialtone with the correct relative path to your component and then composing semantic classes with Dialtone styles, like shown above.

<style lang="less">
/* Import Dialtone definitions. Ensure the relative path is correct. */
@import "../../css/dialtone.less";

.vue-select-menu-option {
display: block;
padding: @spacing8;
color: @slate;
font-size: var(--fs12);
text-align: left;
cursor: pointer;
}

.vue-select-menu-option.highlight {
.d-background-color--ash();
}

.vue-select-menu-option.selected {
.d-background-color--blue-lighter();
}
</style>

Backbone

Using Dialtone in Backbone should be rare, since most frontend changes are now being implemented using Vue. Regardless, if you find yourself needing to use Dialtone in Backbone, there are a few steps:

  1. Create a .less file for your feature, if one does not yet exist.
  2. Import this .less file into the relevant base less file e.g. single.less, web.less etc.
  3. Import Dialtone into your .less file and compose your styles like shown in the example above.

box-sizing: border-box; Consideration

All Dialtone components are implemented with box-sizing: border-box; applied. To understand why we prefer border-box over content-box, please visit this Stack Overflow Teams question.

In Vue, we apply border-box globally at the VueView level, ensuring all child elements use this style. As such, Dialtone styles will work correctly in Vue with respect to element sizing.

In Backbone we are not using border-box by default. Because Dialtone expects this, anytime we wish to use Dialtone styles in Backbone we must ensure to apply the border-box style to all affected elements.