Getting Started

A quick start guide to add Dialtone to your project.

Adding Dialtone to Your Project

To take advantage of Dialtone's customizations, classes, and variables in your project, you will want to install Dialtone via npm.

npm install @dialpad/dialtone-css

Add the following line in your Less file:

@import "@dialpad/dialtone-css/lib/build/less/dialtone.less";

If you only need access to Dialtone's variables and customizations to build a file and don't need the whole library exported, use this line instead in your Less file:

@import (reference) "@dialpad/dialtone-css/lib/build/less/dialtone.less";

Usage

A general overview of Dialtone's utility classes, CSS components, and Vue components.

Utility-First

Dialtone's CSS library offers a framework of utility-first classes. Each class is a small, atomic style declaration that, when chained together, should mitigate most situations in which custom CSS must be written. Just write these classes right in your mark-up and you're all set!

<div class="d-body--sm d-p8 d-bgc-contrast d-fc-primary-inverted d-bar8">Box</div>

In the above example, we used:

Our padding utility class .d-p8 to add 8px of padding on all sides.
Our background color utility class .d-bgc-contrast.
Our font color utility class .d-fc-primary-inverted to change the font color to the inverted primary text color.
Our border radius .d-bar8 for rounded corners.
Our text style .d-body--sm.

Though an atomic CSS approach comes with many advantages, we know it also offers a notable disadvantage: reducing the CSS cascade. This is especially true for repeated UI elements, which can end up creating redundant mark-up. For these instances, Dialtone offers components.

Components

There are two methods to implement Dialtone components: Vue (recommended) and CSS. Vue is the preferred method as it's more robust and readily accessible out-of-the-box. Get started with Vue components. In the event Dialtone Vue doesn't suit your needs, Dialtone's CSS library offers the same set of components. These may require more work to implement and make accessible, but will work in a pinch.

<button class="d-btn d-btn--primary">Primary Button</button>

Authoring Custom Style

In the event you need to write CSS, use BEM (Block Element Modifier). 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:

Block: A parent entity that is meaningful on its own. For example: .card
Element: A child that is meaningful only in relation to its parent. For example: .card__header
Modifier: A modifying flag on a Block or Element that changes appearance or behavior. For example: .card--featured

HTML

<div class="card card--featured">
  <div class="card__header">...</div>
  <div class="card__body">...</div>
  <div class="card__footer">...</div>
</div>

CSS

.card {
  // Local CSS Custom Properties
  --card-color-background: var(--dt-color-surface-primary);

  // Default block styles
  display: flex;
  flex-direction: column;
  background-color: var(--card-color-background);
  border: var(--dt-size-border-100) solid var(--dt-color-border-default);

  // Modifier for block
  &--featured {
    --card-color-background: var(--dt-color-surface-info);
  }

  // Elements within block
  &__header {
    padding: var(--dt-space-500);
  }

  &__body {
    flex-grow: 1;
    padding: var(--dt-space-500);
  }

  &__footer {
    padding: var(--dt-space-500);
  }
}

Backbone

For internal Dialpad projects, using Dialtone in Backbone should be rare, since most front end changes are now being implemented using Vue. Regardless, if you find yourself needing to use Dialtone in Backbone, there are a few steps:

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

Polyfills

In order to make Dialtone work across our supported browsers you need to manually install focus-visible polyfill and postcss-focus-visible plugin.

Focus-visible adds a listener to every element that should be keyboard-focused only and when the element is focused, it adds the .focus-visible class to it, follow the focus-visible installation instructions.
Postcss focus-visible plugin adds a .focus-visible class for every :focus-visible class found in your css, follow the postcss-focus-visible installation instructions.

Box-Sizing

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.

AI-Assisted Development

The Dialtone MCP Server enables AI assistants like Claude Code, GitHub Copilot, and Cursor to search Dialtone in real-time while you code. Instead of manually searching documentation, your AI assistant can instantly find the right components, utility classes, design tokens, and icons for you.

Install with npm:

npm install -D @dialpad/dialtone-mcp-server

Create .mcp.json in your project root:

{
  "mcpServers": {
    "dialtone": {
      "command": "dialtone-mcp-server"
    }
  }
}

Restart your AI assistant to connect. Read the full MCP Server guide for installation options, search tools, and platform-specific setup.

Build Dialtone Locally

We're excited you want to install Dialtone locally as this most likely means you'll be contributing soon! Before you get to get started though, please make sure you've read our contributing docs.

Install Node & npm

To run Dialtone locally, you must have Node and NPM (Node Package Manager) installed. Click here to download Node. The recommended Node version is fine. NPM is included with Node. If you already have Node installed, you may move onto the next step.

Once Node finishes installing, ensure it is installed properly by typing the following command in your Terminal window:

node -v

You should see the following response:

v16.x.x

Clone Project

Download the project:

// SSH
git clone git@github.com:dialpad/dialtone.git

// HTTPS
git clone https://github.com/dialpad/dialtone.git

Then cd into the Dialtone directory:

cd ./path/to/dialtone

Install Dependencies

Dialtone uses Gulp to automate its various workflows. Run the following command to install Gulp and all other project dependencies:

pnpm install

Building Dialtone

You're now ready to build Dialtone! To build and run the development server:

nx run dialtone-documentation:start

Once finished, visit http://localhost:4000/.

Adding Dialtone to Your Project #

Usage #

Utility-First #

Components #

Authoring Custom Style #

HTML #

CSS #

Backbone #

Polyfills #

Box-Sizing #

AI-Assisted Development #

Build Dialtone Locally #

Install Node & npm #

Clone Project #

Install Dependencies #

Building Dialtone #