---
url: 'https://dialtone.dialpad.com/components/index.html'
description: >-
  Reusable components solving common UI needs, designed and built to be
  assembled in countless combinations.
---
# Components

---

---
url: 'https://dialtone.dialpad.com/design/index.html'
description: The visual foundation that supports and unites Dialpad products.
---
# Design Language

---

---
url: 'https://dialtone.dialpad.com/design/colors/index.html'
description: >-
  A systematic and accessible color palette that supports both functional needs
  and personalized experiences within our products.
---
# Colors

---

---
url: 'https://dialtone.dialpad.com/design/colors/chart-colors/index.html'
description: Chart color guidance to communicate data clearly.
---
# Chart Colors
## Overview

Data visualization is crucial for clear communication, but inconsistent color usage can hinder comprehension and create visual noise.
**Chart Color Tokens** provide a unified, robust, and accessible system for coloring data visualizations  across all Dialpad products.

These tokens are designed to:

* **Ensure Visual Consistency:** Guarantee a cohesive look and feel for data insights.
* **Enhance Accessibility:** Provide high-contrast, color-blind friendly palettes out-of-the-box.
* **Streamline Workflow:** Offer a single source of truth for both designers and developers, reducing guesswork and speeding up development.
* **Improve Maintainability:** Simplify global color updates and future-proof our data experiences.

## Types

Chart Colors are available for one of four types: [Single Color](#single-color), [Semantic](#semantic), [Categorical](#categorical), and [Sequential](#sequential).

### Single Color

Use for data visualizations that only require comparing one or two data points, or a single data point against a series of adjacent neutral data. Use `chart.color.accent` as the default. To bring a data point to focus, use `chart.color.accent` for the focused data point and `chart.color.neutral` for the rest.

**When to Use:**

* Basic data points.
* Indicating selected chart series or segments.
* Dimming or disabling inactive chart elements.

### Semantic

Apply colors that associate meaning to the data points, such as status, severity, or sentiment.

**When to Use:**

* Performance Dashboards: Showing status (on-track, at-risk, complete).
* Alerts/Notifications: Highlighting critical data points.
* Sentiment Analysis: Representing positive, neutral, or negative sentiment.
* Brand Alignment: Emphasizing data related directly to Dialpad's core identity.

### Categorical

Apply unique colors to distinguish two or more unrelated data where color carries no meaning. Use in the predetermined numerical order, e.g. `01`, `02`, etc. This ensures applied data can be visually distinguished from its adjacent data.

**When to Use:**

* Multi-series bar charts, pie charts, or line charts comparing different groups.
* Visualizing discrete variables (e.g., customer segments, operating systems).

### Sequential

To represent data using progressive shades or tints of a single color, emphasizing their relative depth within a single data series.

**When to Use:**

* Single-series charts where visual depth or intensity within one category is key.
* Heatmaps or density visualizations for a single metric.
* Situations requiring a strong visual connection to the Dialpad brand.

#### Sequential Range

Using sequential range tokens enable the ability to dynamically create varying number of color steps for a single data series with `start` and `end` tokens.

#### Sequential Default

The default range are a fixed number of 10 available colors for a single data series. If you need to create fewer or more colors, use the sequential range tokens.

## Usage

### Developers

Apply to chart elements (bars, lines, fills) via CSS Variables (e.g. `var(--dp-color-chart-color-accent)`) or corresponding CSS Utilities, e.g. `d-bgc-chart-neutral`, `d-bc-chart-warning`, etc.

### Designers

* **Applying Colors:** Apply color directly to chart elements (bars, lines, fills) via Figma Styles linked to tokens. Unlike other Dialtone colors, Chart Colors are not scoped to foreground, surface, border, etc.
* **Understanding Hover/Selected:** Remember that hover and selected states for specific chart series (single color, semantic, categorical, and sequential) have predetermined contrasting colors, ensuring consistent interaction feedback.
* **Prototyping:** Use these tokens in your Figma prototypes to demonstrate interactive states and theme switching.

## Do and Don'ts

### Use chart colors only for data

### Apply Categorical colors in numeric order

### Limit chart colors

### Use multiple colors only with purpose

### Use space to separate data

## Accessibility Guidelines

Ensuring accessible data visualizations is a core tenet of Dialtone. When using these tokens:

* **Contrast Ratios:** All token color combinations are designed to meet WCAG AA contrast standards (minimum 3:1 for graphics/UI components).
* **Color-Blindness Compatibility:** Palettes have been vetted for common forms of color blindness (e.g., using tools like Viz Palette).
* **Redundancy is Key:** Never rely solely on color to convey critical information. Always provide supplementary visual cues such as:
  * Labels/Text: Directly annotating data points with values.
  * Icons/Patterns: Using distinct icons or patterns for categories.
  * Shapes/Stroke Styles: Varying shapes, line styles (dashed, dotted), or stroke widths.
* **Theming Impact:** Token values are specifically defined for both light and dark modes to ensure optimal contrast and readability in any theme.

## Known Issues & Troubleshooting

While this system aims for robustness, be aware of potential challenges during implementation and adoption:

* **Charting Library Overrides:** Some charting libraries might aggressively override inline styles or custom properties, requiring careful mapping or deeper customization.
* **Complex Color Logic:** For very custom data-driven color calculations beyond simple references (e.g., dynamic gradients based on data range), you might still need to implement logic in code that consumes these Chart Color design tokens.
* **Transitioning Existing Charts:** Migrating older charts not using design tokens will require dedicated refactoring effort.

---

---
url: 'https://dialtone.dialpad.com/design/colors/palette/index.html'
description: 'A functional, personal, and accessible color palette.'
---
# Color Palette
## Foreground

Colors for text and icons

## Foreground Status

Foreground colors distinguishing important information with a status role.

## Surface

Background colors for application UI surfaces. Surface colors are container blocks — such as pages, modals, tables, headers, and cards — containing foreground content or elements.

## Borders

Define the edge of key content area, components, or surfaces.

## Theme Shell

CSS variables for themeable parts of the UI, primarily targeting the top bar and left bar.

## Base Palette

Base colors are the literal value of all available colors. Use these only if all abstracted Text, Status text, Surface, or Border colors do not fit your need — consult a Product Designer.

Each of the colors listed above references these. For example, in Light mode
`var(--dt-color-foreground-primary)` is an alias to `var(--dt-color-black-900)`, and
`var(--dt-color-foreground-critical)` is an alias to
`var(--dt-color-red-300)`, and will have a different value in Dark mode.

### Light Theme

### Dark Theme

---

---
url: 'https://dialtone.dialpad.com/design/colors/themes/index.html'
description: Theme options that allow user customization of Dialpad products.
---
# Themes
## Overview

Dialtone's theming system is a flexible foundation for creating consistent visual experiences. It lets you adapt the user interface to different contexts, preferences, and product variations. Our approach uses semantic color tokens to easily switch between themes and modes.

Theming is limited to the application's navigation regions, consisting of the top and left.

### Mode

A mode defines a visual style that applies across all themes. It determines the overall luminosity and contrast of the interface. For example, light mode has a light background and dark text, while dark mode has a dark background and light text.

### Theme

A theme represents the core color scheme. It applies a unique set of colors to themeable regions, and it works in conjunction with a mode. For example, the default "Dialpad" theme accent may be purple, while a "Sunflower" theme's is a deep yellow.

### Theme List

## Theming with Shell Tokens

The shell tokens are a specialized set of tokens for theming the topbar and sidebar. They are designed to be easily customized while maintaining a coherent color scheme.

### Shell Base Tokens

These are the core reference colors for the shell. They are directly linked to the base tokens and determine the overall color palette of the topbar and sidebar. These base tokens are the only ones that should be modified when creating a custom theme.

### Shell Modifier Tokens

These tokens, such as `shell-action...`, `shell-status...` `shell-mention...`, inherit their values from the shell base tokens. For example, they use modifiers to create variations or color states (e.g., `hover`, `active`, `disabled`).

This structure allows for a cascading effect: changing a shell base token automatically updates all related shell modifier tokens, making it simple to create and manage custom themes for the application's shell.

## Accessibility

When creating a custom theme, it is important to ensure that the colors used are accessible. This means that the colors should be easy to read and contrast well with the background.

## Related

* If you need full list of all the shell tokens, [Check out our list of colors](../palette/index.md).
* [See our entire token catalog with full descriptions and values of all tokens.](../../../tokens/index.md).

---

---
url: 'https://dialtone.dialpad.com/design/colors/usage/index.html'
description: >-
  A systematic and accessible color palette that supports both functional needs
  and personalized experiences within our products.
---
# Usage
## Overview

Dialtone's color system offers a consistent visual foundation with a brand purple, versatile grayscale, and semantic status colors. Subtle gradients are used for promotional accents.

What we prioritize is semantic clarity, ensuring each color serves a distinct purpose within the UI for clear communication and consistency...

## Use Semantic Color Tokens

Dialtone uses **semantic tokens** for color, representing a color's *purpose* in the UI. See our [See our design token list](https://dialtone.dialpad.com/tokens/) for descriptions guiding their application.

It's crucial to understand that while these semantic tokens are built upon our underlying **base color palette**, the work of selecting the appropriate base color for each specific UI context has already been meticulously done for you.

## Color roles

Color roles describe the purpose of how color is used. Each uses neutrals for general UI and status colors for impact.

We categorize color application by semantic roles such as: **text, surfaces, borders, and themes**. Each uses neutrals for general UI and status colors for impact.

### Foreground Colors

Foreground colors are the visual language of our content, applied across all content considered to be "in the foreground", i.e. text and icons. You can utilize foreground tokens which can be found within the [tokens documentation here](https://dialtone.dialpad.com/tokens/).

### Surfaces

Surface colors define the background of UI elements, from pages and modals to tables and cards. Neutrals provide the primary backdrop, while status colors add emphasis and context.

### Borders

Borders delineate content areas and components, using neutrals for subtle definition and status colors for heightened emphasis. Inverted colors ensure clarity on darker surfaces.

### Charts

View our [Chart Colors](../chart-colors/index.md) documentation for more information.

## Best Practices

### Preserve Color Semantics

Use feedback colors consistently to maintain clear communication and avoid confusion.

### Semantics Over Base Values

Embrace semantic tokens to separate color values from their contextual meaning, enhancing maintainability and clarity.

### Prioritize Contrast

We primarily employ the APCA for precise contrast evaluation, ensuring readability for all users.

**Refer to Accessibility Guidelines for detailed information.**

### Uniformity

Maintain color consistency across similar components to build intuitive user patterns.

## Modes

Dialtone is designed to seamlessly support both light and dark themes. We supply colors through semantic tokens that automatically adapt their underlying values depending on the active mode, ensuring consistent meaning and optimal contrast in any environment.

## Related

* If you need full list of our color palette, [Check out our list of colors](../palette/index.md).
* [See our entire token catalog with full descriptions and values of all tokens.](../../../tokens/index.md).

---

---
url: 'https://dialtone.dialpad.com/design/icons/index.html'
description: 'An icon style for visually communicating commands, status, and more.'
---
# Icons
## Usage

### In Figma

Find a list of available icons in [DT Core: Icons](https://www.figma.com/file/zz40wi0uW9MvaJ5RuhcRZR/DT8-Icon-Library), or search the icons in the search library within your Figma file.

### In Vue

For detailed instructions on using the icons, check the [Icon component](/components/icon.md).

```js
import { DtIconCreditCard } from '@dialpad/dialtone-icons/vue3';
<dt-icon-credit-card size="500" aria-label="Description" />
```

### Choosing the Right Icon

Some icons are linked to specific actions, like the Settings gear  or the Edit pencil . For actions without a dedicated icon, avoid reusing icons that are already associated with other actions, this helps prevent confusion and ensures clear understanding. Instead, select an existing icon from the Icon Catalog without a specific action meaning or consider [creating a new one](#crafting-an-icon) that clearly represents the intended action.

### Sizing

The icon size is defined based on the context and text size next to it. These are the only available size options and no overrides should be needed to properly size the icons.

## Crafting an Icon

Our icons are designed for easy recognition and understanding. They are a visual support, helping people navigate the experience more effectively.

### On Figma

Go to the [Icon Builder page](https://www.figma.com/file/zz40wi0uW9MvaJ5RuhcRZR/DT8-Icon-Library?type=design\&node-id=12057-3505\&mode=design\&t=CNADHg9I1bsKDPiB-4) in Figma and follow the instructions. Remember to work on a branch and send a review when the icons are ready.

* Use simple lines and shapes. Avoid creating overly literal, complex icons.
* Utilize the icon grid while maintaining the style of each icon.
* The icon's content should remain within the 2px padding (on size 500/24px); no part of the icon should extend beyond this area.
* Both exterior and interior corners should be 2px (on size 500/24px).
* The stroke style should be `solid`, end points `round`, and join `round`.

### Exporting

\<dt-notice
kind="info"
class="d-wmx100p d-my24"
hide-close
title="Claude Code"

>

The /icon skill automates SVG validation, normalization, and build verification. Run /icon add \<name> or /icon update \<name>.


1. [Create a new branch](https://github.com/dialpad/dialtone/tree/staging/packages/dialtone-css/.github/CONTRIBUTING.md#making-a-pull-request) in [dialtone](https://github.com/dialpad/dialtone/tree/staging) repo starting with "dlt-xxxx-" in the name.
2. Export the SVG from the **12px (size 100)** Figma component. For standard icons (all categories except `brand-full-color`), prepare the SVG before placing it:
   * Run **Edit > Outline Stroke** in Figma to ensure the icon is fill-based (no strokes).
   * Normalize fill colors to `fill="black"`. Figma often exports `fill="#1C1C1C"` or other near-black hex values that the build pipeline won't convert to `currentColor`.
   * Remove no-op `<clipPath>` wrappers — Figma adds these when "Clip content" is enabled, but they are unnecessary when the clip rect matches the viewBox.
   * Consider combining multiple `<path>` elements into a single `<path>` where they share all attributes (fill, fill-rule, opacity, etc.). Do not combine paths that differ in any attribute beyond `d`.
   * Icons in `brand-full-color` may use solid brand hex colors, gradients, and other attributes — preserve these as-is.
3. Place the exported SVG file(s) in the appropriate folder category inside `./src/svg/`, file names should be in kebab-case.
4. Run `nx run dialtone-icons:build`
5. Add keywords related to the icon(s) in the `packages/dialtone-icons/src/keywords-icons.json` file.
6. [Commit](https://github.com/dialpad/dialtone/tree/staging/.github/COMMIT_CONVENTION.md) and push your branch to [dialtone](https://github.com/dialpad/dialtone/tree/staging), and open a pull request.

---

---
url: 'https://dialtone.dialpad.com/design/size/index.html'
description: A system to maintain consistent size and scale.
---
# Size
## Choosing Size vs. Space

### Size

Size design tokens define intrinsic **dimensions** of UI components. Example CSS properties they correspond to: `width`, `height`, `border-radius`, `border-width`, positioning properties, i.e. `top`, `left`, etc.

### Space

[Space](/design/space/index.md) design tokens focus on controlling **spatial relationships**; that is, the space between and around elements. Example CSS properties they correspond to: `padding`, `margin`, `gap`

## Usage

### Setting a Specific Size

When assigning a size to an element, utilize [Size Tokens](#tokens) for the value.

👍
`width: var(--dt-size-400)`

👎
`width: var(--dt-space-400)`

```html
<style>
.box {
  min-width: var(--dt-size-720);
}
</style>
<div class="box">Box</div>
```

### Widths and Heights

For optimal layout flexibility and responsiveness, generally avoid using fixed `widths` or `heights` when defining element sizes. Instead, use percentages values or set `min-width` or `min-height`. This allows the elements to adjust naturally to different screen sizes.

### Variable Sizing

The size of some components is determined by their content. Most expand vertically, while a select few expand horizontally.

### Responsiveness

Adapting to different devices, sizes should be fluid across breakpoints. While most Dialtone components are responsive, their fluidity depends on the layout they live within.

### Accessibility

To ensure clickable and interactive areas are easily accessible, we recommend a minimum area of `var(--dt-size-300)`, except for links within text. In Dialtone we've applied these to components such as buttons, toggles, checkboxes, radio buttons, dropdowns, and inputs.

## Tokens

Here are some frequently used tokens. For a complete list, visit the [Size Tokens](/tokens/index.md#size) section.

## Key Takeaways

* Use predefined tokens, they help maintain consistency and make it easier to update designs.
* Keep sizes and spacing consistent: This ensures a polished look across all devices.

---

---
url: 'https://dialtone.dialpad.com/design/space/index.html'
description: 'Define paddings, gaps, and margins around elements.'
---
# Space
## Choosing Space vs. Size

### Space

Spacing design tokens focus on controlling **spatial relationships**; that is, the space between and around elements. Example CSS properties they correspond to: `padding`, `margin`, `gap`

### Size

[Size](/design/size/index.md) design tokens define intrinsic **dimensions** of UI components. Example CSS properties they correspond to: `width`, `height`, `border-radius`, `border-width`, positioning properties, i.e. `top`, `left`, etc.

## Usage

Use spacing units, when [stacking elements](#stacking) or when adding [padding](#padding) or margin.

When setting the scale of an element, use [Size](/design/size/index.md) units.

### Setting a Specific Spacing

When setting the gap between elements, utilize [Space Tokens](#tokens) for the gap value.

👍 `gap: var(--dt-space-400)`

👎 `gap: var(--dt-size-400)`

```html
<style>
.wrapper {
  gap: var(--dt-size-400);
}
</style>
<div class="wrapper">
  <div>
    Element A
  </div>
  <div>
    Element B
  </div>
</div>
```

### Stacking

When adding space between elements, both vertically and horizontally, we can use either `space-between` or `gap` to define the space that separates each element. The value is set as a variable in Figma and as a token in code.

* For gaps inside a box/container, such as between headings, text, and buttons, use values like `var(--dt-space-0)` to `var(--dt-space-550)`
* For spaces between different boxes/containers on a page, choose values from `var(--dt-space-600)` to `var(--dt-space-700)`

### Padding

When adding space around an element, use `padding` to create breathing room.

Avoid using `margin`, which adds space outside the element and can affect the layout, in that case, follow the [stacking](#stacking) approach.

## Visual Guides

### Grouping

### Guiding the Eye

## Tokens

Here are some frequently used tokens, don't use values outside the recommended range for specific types of spacing. For a complete list, visit the [Spacing Tokens](/tokens/index.md#space) section.

## Key Takeaways

* Use predefined tokens, they help maintain consistency and make it easier to update designs.
* Consider the overall composition and whitespace to create well-proportioned layouts.
* Ensure consistent spacing across various screen sizes and breakpoints.
* Keep spacing consistent: This ensures a polished look across all devices.

**🌟 Design Tip:** Optimize your workflow in Figma by setting the nudge amount to 4px or 8px. It's a small change that can make a big difference in ease of use!

---

---
url: 'https://dialtone.dialpad.com/design/typography/index.html'
description: 'Clear, legible, and easy-to-read text.'
---
# Typography
## Font Properties

### Font Family

Dialtone's product UI font stack defers to the user's default system font, ensuring a seamless native experience.

### Font Weight

Four weights for clear hierarchy and visual contrast among different elements.

### Font Size

Dictates the scale of text, enhancing readability and defining information hierarchy across content.

### Line Height

Adjusts vertical spacing between lines of text, optimizing legibility and text flow.

## Styles

### Usage

All product UI text can be characterized as one of **Headline**, **Body**, **Label**, **Helper**, or **Code**. These styles are effectively **composition** CSS Utilities, combining multiple properties like `font-size`, `font-family`, `font-weight`, and `line-height`.

```html
<el class="d-{category}--{size}-{strength}-{density}">...</el>
```

### Examples

```html
<dt-stack gap="400">
  <dt-stack>
    <h2 class="d-headline--lg">Ai that works for you</h2>
    <div class="d-body--md-compact">Support customers, drive sales, and collaborate with your team—all in one, beautiful Ai-powered app.</div>
  </dt-stack>
  <dt-stack direction="row" gap="500" align="start">
    <dt-stack>
      <h3 class="d-headline--md-compact">Ai Contact Center</h3>
      <p class="d-body--sm">The world’s most advanced customer engagement platform</p>
    </dt-stack>
    <dt-stack>
      <h3 class="d-headline--md-compact">Ai Voice</h3>
      <p class="d-body--sm">Say hello to the world’s smartest business phone</p>
    </dt-stack>
    <dt-stack>
      <h3 class="d-headline--md-compact">Ai Meetings</h3>
      <p class="d-body--sm">Ai-powered video meetings with built-in transcriptions</p>
    </dt-stack>
  </dt-stack>
</dt-stack>
```

### Headlines

Titles and headings to establish hierarchy and set the tone of contextual groupings.

### Body

Default text style for longer-form prose content, designed for comfort and clarity in reading varying lengths.

### Label

Shorter-length copy like form fields, buttons, and other UI-labeling elements, ensuring clear navigation and interaction.

### Helper

Complementary information or guidance, such as tooltips and hints, to aid user understanding without overwhelming.

### Code

Code snippets, technical commands, or data values rendered as a monospaced font.

## API

Each typography style is expressed through a shorthand `font` property, and its value's design token contains all font styles, e.g. `font-size`, `line-height`, `font-family`, etc,

---

---
url: 'https://dialtone.dialpad.com/guides/accessibility/index.html'
description: Guidance on building products for everyone.
---
# Accessibility and inclusive design
We are committed to usable experiences and products for everyone. Because “everyone” is a lot of people reflecting a variety of backgrounds, abilities, and circumstances, we believe in applying thoughtful and inclusive design and development practices.

## Fundamentals

Dialpad strives to maintain  **WCAG 2.1 AA** compliance in our digital products.

Everyone benefits when things are designed accessibly. Simply put: building products for accessibility is simply building products for better usability. Considering  **1 in 4** US adults -- that’s 61 million people! -- live with a permanent disability and many more will have temporary or situational throughout their lifetime, accessibility isn’t for just some people. It benefits everyone.

As we consider the entire spectrum of possibilities, the benefits to the people we are designing for goes up dramatically. Accessible design is usable design, for more people in more circumstances.

### Principles

Building inclusive product experiences can be boiled down to the  **P.O.U.R.** principles:

1. Perceivable.
2. Operable.
3. Understandable.
4. Robust.

#### Perceivable

The interface and its content are designed and implemented in such a way that it works across a variety of users agents and assistive technologies.

* The handling of media content like video, audio and imagery.
* The handling of text alternatives through things like captioning and sign language.
* The handling of color and contrast.
* The control of text size and audio controls.
* The handling content interactions i.e. hover and focus states.

#### Operable

Users are able to interact with and navigate the interface and its content.

* Keyboard operability.
* Time allowance.
* Seizures and other involuntary physical reactions.
* Navigation through things like focus order, page titles, links, headings and labels.
* Input methods like touch targets sizing, alternative input methods.

#### Understandable

The interface and its content use plain language that’s easy to comprehend. Even if users can perceive and navigate content, what if they can’t actually understand the information?

* Predictable and consistent navigation.
* Use of language such as abbreviations, jargon, reading levels.
* Predictable and consistent actionable components.
* Feedback and error handling.
* Help, such as contextual help and error prevention.

#### Robust

The interface and its content is designed and implemented in such a way that it works across a variety of users agents and assistive technologies.

* Parsing and generally ‘clean’ code like proper heading hierarchy, no duplicate attributes, complete start and end tags for elements.
* Name, role and value.
* Status messages, sending messaging to the user without interrupting their workflow by giving focus to an element. e.g. “added to cart” while shopping online should act as a message and not a redirection of activity and focus for the user.

### Types of Assistive Technology

“Assistive technology” is a generic term that describes tools used by people with disabilities to accomplish tasks. Here are some examples:

* **Screen readers:** Software used by blind or visually impaired people to read the content of the computer screen. Examples include JAWS for Windows, NVDA, or Voiceover for Mac.
* **Screen magnification software:** Allows users to control the size of text and/or graphics on the screen. Unlike using a zoom feature, these applications allow the user to have the ability to see the enlarged text in relation to the rest of the screen. This is done by emulating a handheld magnifier over the screen.
* **Text readers:** Software used by people with various forms of learning disabilities that affect their ability to read text. This software will read text with a synthesized voice and may have a highlighter to emphasize the word being spoken. These applications do not read things such as menus or types of elements - they only read the text.
* **Speech input software:** Provides people with difficulty in typing an alternate way to type text and also control the computer. Users can give the system some limited commands to perform mouse actions. Users can tell the system to click a link or a button or use a menu item. Examples would be Dragon Naturally Speaking for Windows or Mac. Please note both Windows and Mac have some speech recognition utilities, but they cannot be used to browse the web.
* **Alternative input devices:** Some users may not be able to use a mouse or keyboard to work on a computer. These people can use various forms of devices, such as:
  * **Head pointers:** A stick or object mounted directly on the user’s head that can be used to push keys on the keyboard. This device is used by individuals who have no use of their hands.
  * **Motion tracking or eye tracking:** This can include devices that watch a target or even the eyes of the user to interpret where the user wants to place the mouse pointer and moves it for the user.
  * **Single switch entry devices:** These kinds of devices can be used with other alternative input devices or by themselves. These are typically used with on-screen keyboards. The on-screen keyboard has a cursor move across the keys, and when the key the user wants is in focus, the user will click the switch. This can also work on a webpage: the cursor can move through the webpage, and if the user wants to click on a link or button when that link or button is in focus, the user can activate the switch.

#### Additional Resources

* [Apple - Voiceover/keyboard shortcuts for OS X](https://www.apple.com/voiceover/info/guide/_1131.html)
* [Deque - Accessibility Testing Tools](https://www.deque.com/axe/)
* [Deque University - Web Accessibility Training and Courses](https://dequeuniversity.com/)
* [MDN - Developer Guides](https://developer.mozilla.org/en-US/docs/Web/Guide)
* [Microsoft - Narrator keyboard commands for Windows](https://support.microsoft.com/en-us/windows/appendix-b-narrator-keyboard-commands-and-touch-gestures-8bdab3f4-b3e9-4554-7f28-8b15bd37410a)
* [Pa11y](https://pa11y.org/)
* [Web Content Accessibility Guidelines (WCAG) 2.1](https://www.w3.org/TR/WCAG21/)
* [WebAim - Constructing a POUR Website](https://webaim.org/articles/pour/)
* [CDC - Disability Impacts All of Us Infographic](https://www.cdc.gov/ncbddd/disabilityandhealth/infographic-disability-impacts-all.html)
* [Berkeley - Types of assistive technology](https://webaccess.berkeley.edu/resources/assistive-technology)
* [UXcellence - Designing for Accessibility: An Introduction](https://uxcellence.com/2018/accessible-design-intro)

## Accessibility Principles by Role

How your role can address accessibility and inclusive design.

### Product Management

Product managers can set the tone early in a project's lifecycle, ensuring the team knows their responsibilities and accountability to building accessible products.

1. Be aware of **each role's** high-level accessibility principles.
2. Ensure each role on your team is aware of these principles and keep them in mind from the start: [Content](#content), [Design](#design), and [Engineering](#engineering).
3. Build **accessibility into project workflows** every step of the way, rather than as a retrofit exercise.
4. Learn **Accessibility basics** to understand what makes your team empowered to deliver accessible products and services.
5. Understand the **diversity of users** to better consider how anyone can get the most out of your product.
6. Consult an **accessibility subject matter expert** to review.

### Content

Writing accessibly ensures your content is easier for everyone to read.

1. **Plain Language.** Can you quickly understand the main points of the content?
2. **Scannability.** Can you scan the page without significantly pausing through long passages?
3. **Images.** Do your images have descriptive alt text?
4. **Links.** Do link sufficiently describe its destination?
5. **Information Architecture.** Are the application’s parts organized such that any can navigate easily?

### Design

Accessibility is usability for everyone, regardless of ability, situation, or circumstance. Treat accessibility as a core principle of Product Design.

1. Adopt a mentality of **Inclusive Design**.
2. Is there sufficient **contrast** between foreground and background content?
3. Is textual information **easy to read and parse**?
4. Are **navigation shortcuts** available for keyboard and screen readers to reach key regions?
5. Familiarize yourself with **assistive technologies**. These include screen readers, screen magnification, ergonomic keyboards, or even zoom capabilities in browsers.
6. Do your designs imply a **logical tab order** for those using a keyboard to navigate throughout.
7. Are all interactive elements reachable through the tab key, and reflect a **perceivable focus indicator**?
8. Do your designs reflect a **perceivable focus indicator** for interactive parts?
9. When a view changes significantly, is it clear to the user **where focus has moved to** (independent of a perceived focus order)?
10. Can any user **understand and fill out** forms? Are they as simple as possible and require only what’s needed for task completion?
11. Is imagery easily distinguished as **meaningful content or decorative**?
12. Is **content understandable** for content associated with images and icons?
13. Are **data visualizations** easy to grasp?
14. Are **touch targets** large enough and easy to reach?
15. Can a **screen reader access** all functionality and content?

### Engineering

Pretty much everything above plus…

1. Do **heading elements** (e.g. `<h1>` through `<h6>`) accurately reflect a logical hierarchy of content and features?
2. Are **semantic HTML elements** being used appropriately, and extended where appropriate with ARIA attributes and roles?
3. Does your **automated accessibility testing** tools provide accurate results?

## Best Practices

### Color Contrast Ratio

Dialpad strives to maintain  **WCAG 2.1 AA** compliance in our digital products, including color contrast. [WCAG guidelines](https://www.w3.org/TR/WCAG21/#contrast-minimum) require a minimum of 4:51 ratio for all content in regular-weight fonts.

For easy reference, our color references are displayed alongside a contrast rating. Note that these are calculated using either a white or black background, and contrast between type and background should always be verified when using different background colors.

To check color contrast combination, try one of these tools:

* Colorable
* WebAim
* Figma plugin: Stark

### Semantics

One of the simplest things we can do to make more accessible sites is to build with semantic HTML. Creating semantic HTML, or “semantic markup” is the practice of using the appropriate HTML element to convey information about the meaning and context of each element. For example, for a paragraph or bulleted list, you would use `p`  or `ul` tags, respectively. In places where there is no HTML element which has a matching semantic meaning for what you are creating, you will want to employ the use of an inline `span`, or division element `div`.

Semantic markup also maintains the separation between the semantics and the visual presentation. For example, it’s common to choose which heading element to use based on its style, but that would be incorrect. The proper way would be [choosing the semantic heading level](#headings) and then applying CSS to style it, thus not using your mark-up as a means to style.

Inversely, there may be times when you want a `button`, `select`, etc. element, but also want it to have just slightly different behavior or non-native styling. In these cases, we generally choose to use a `div` or less semantic implementation. Be so careful when you decide to do this. We forget how much native functionality is built in a `button`, `link`, `select`, etc. and re-creating that exact implementation so a screen reader user or keyboard-only user can still interact with the element appropriately can be complex and time consuming.

As an example, to recreate a `button` with a `div`, you would need to add in multiple ARIA attributes, manage focus, and then also add additional JavaScript to allow you to click it, or use the spacebar and enter key to activate it. You can learn more by watching [“Just Use a Button,”](https://www.youtube.com/watch?v=CZGqnp06DnI) as explained by Rob Dodson from the Google Chrome Team.

#### Structural Semantics and Landmarks

The following HTML elements should be used to identify common elements of our products.

```html
<header>
<nav>
<main>
<article>, <aside>
<form>
<footer>
```

* [MDN - Developer Guides - Good Semantics](https://developer.mozilla.org/en-US/docs/Learn/Accessibility/HTML#good_semantics)
* [W3C - HTML Sectioning Elements: ARIA Landmarks Example](https://www.w3.org/TR/wai-aria-practices/examples/landmarks/HTML5.html)

### Headings

There are two easy rules that only apply to heading elements that we should adhere to for the best accessibility practices:

The first: use one `h1` per page. The `h1` is typically the page title and use of more than one `h1` can confuse browsers and assistive technology.

The second: when employing multiple heading levels, do not skip heading levels in a section. For example, if you’re writing an article, you could do:

```html
<h1>
<h2>
<h3>
<h2>
<h3>
<h4>
```

But you should never do:

```html
<h1>
<h2>
<h4> // This is problematic since you skipped the <h3> in the same section
<h2>
<h3>
<h4>
```

Headings taken out of context, such as accumulated together in a list for a screen reader, should logically represent the page content for users who choose this option as a way to browse.

### Lists

Do not underestimate the power of list elements. When there are more than two or three similar items next to one another on the page, consider putting them in either an order list `ol` or unordered list `ul` for screen readers.

By using a list element, a screen reader user knows how many items they can expect to go through, and where they are in the list. A screen reader will announce, “1 of 3 list items,” which is helpful context that allows a user to orient themselves and have a better expectation of what will come next.

### Tab Order

Like the name suggests, tab order is the order in which elements receive focus when a user is navigating with a keyboard. The tab order should match the visual order, so users are able to logically navigate through content. This is important. The default keyboard navigation order must be logical and intuitive, which generally means that it follows the page’s visual flow: left to right, top to bottom -- header first, then main navigation, then page navigation (if applicable), and finally the footer.

Ideally, the visual tab flow will match the flow of the code. There are cases when something must be coded in an illogical order. In these cases, we can use `tabindex` to override the default order. By applying a `tabindex` value to each element in the flow, we can control the element order.

For example:

```html
<a href=”#” tabindex=”2”>First Element</a>
<a href=”#” tabindex=”1”>Second Element</a>
```

Because “Second Element” has a lower tabindex, keyboard users will focus it before “First Element.”

Though it sounds convenient, `tabindex` should be used only in cases where there is no other option.

By default, users can only navigate to links, buttons, and form controls with a keyboard. These natively-accessible elements should be used whenever possible, although there are times when HTML falls short and custom “widgets” are necessary. Complex menus, sliders, dialogs, tab panels, etc. must all be built to support keyboard accessibility.

`Tabindex=”0”` can be used to add non-interactive elements into the tab flow. This is useful when coding custom elements that are not natively focused.

### Visible Focus

It is often difficult for keyboard users to tell where they are on the page. We must take care to ensure that it is easy to tell which item on the page currently has keyboard focus. All browsers by default display a visible outline around the element that currently has focus. Some browsers (i.e. Chrome and Safari) show an easy-to-see blue outline as their visible focus. However, other browsers show a thin, dotted line, which can be very difficult to see.

Dialtone provides visible focus on all components. However, we cannot anticipate the various contexts in which each component will be inserted. Be sure to remember that focus indication can occur on different colored backgrounds and a minimum contrast ratio of 3:1 is required.

### Skip Navigation Links

A site or product’s main content is not usually the first thing on the page. Keyboard users generally must navigate a long list of navigation links, dropdowns, logos, search inputs, and other elements before ever arriving at the main content. This is particularly difficult for users with some forms of motor disabilities. Without some sort of system, for bypassing the long list of links at the top, some users are at a huge disadvantage. Consider users with no arm movement, who use computers by tapping their heads on a switch or that use a stick in their mouth to press keyboard keys. Requiring users to perform any action perhaps 100s of times before reaching the main content is simply unacceptable.

The “skip navigation” idea was invented to give keyboard users the same capability as sighted mouse users to go directly to the main content. The idea is simple: provide a link at the top of the page which jumps the users down to an anchor or target at the beginning of the main content.

Often developers hide the skip navigation link so it is available for screen reader users only. Ensure that the link is visible, or becomes visible when the keyboard user tabs to it.

* [WebAim - “Skip Navigation Links”](https://webaim.org/techniques/skipnav/)

### Form Best Practices

Forms can be difficult, high-friction points for sighted and able users, which means if not done correctly, they can be simply unusable for users reliant on keyboard navigation or assistive technology. Users should be able to fill in forms, press buttons, use range sliders, select options, and operate controls with ease. Forms that use JavaScript to manipulate form data, set focus, change form elements, or submit forms can often create interactions that only work with a mouse. Ensure your forms can be understood and operated with the keyboard alone.

Labeling is also important. Input labels describe the function of a form control (i.e. checkbox, radio button, etc.) and generally appear adjacent to it. While sighted users make the connection visually, users reliant on a screen reader or other assistive technology may not. The `label` element programmatically associates a text label to its form control, creating a connection that doesn’t rely on vision.

Groups of form controls, such as checkboxes and radio buttons, sometimes require a higher-level label. This information can be associated with the group of form controls using `fieldset` and `legend`. The `fieldset` defines the group and the `legend` contains the description. Screen readers announce the `legend` when users navigate into the group.

List-based inputs, such as `select`, comboboxes, or custom dropdown menus can be tricky for keyboard navigation. Users should be able to navigate through the options using their arrows, not their tab key.

* [WebAim - “Creating Accessible Forms.”](https://webaim.org/techniques/forms/controls)

### Focus vs Focus-visible

User agents can choose their own heuristics for when to match `:focus-visible`; however, the following (non-normative) suggestions can be used as a starting point:

* If a user has expressed a preference (such as via a system preference or a browser setting) to always see a visible focus indicator, the user agent should honor this by having `:focus-visible` always match on the active element, regardless of any other factors. (Another option may be for the user agent to show its own focus indicator regardless of author styles.)
* Any element which supports keyboard input (such as an input element, or any other element which may trigger a virtual keyboard to be shown on focus if a physical keyboard is not present) should always match `:focus-visible` when focused.
* If the user interacts with the page via the keyboard, the currently focused element should match `:focus-visible` (i.e. keyboard usage may change whether this pseudo-class matches even if it doesn’t affect `:focus`).
* If the user interacts with the page via a pointing device, such that the focus is moved to a new element which does not support user input, the newly focused element should not match `:focus-visible`.
* If the active element matches `:focus-visible`, and a script causes focus to move elsewhere, the newly focused element should match `:focus-visible`.
* Conversely, if the active element does not match `:focus-visible`, and a script causes focus to move elsewhere, the newly focused element should not match `:focus-visible`.

User agents should also use `:focus-visible` to specify the default focus style, so that authors using `:focus-visible` will not also need to disable the default `:focus style`.

In general, a rule of thumb is that: if an element is going to need the keyboard (ex. inputs) that element should use **focus**, otherwise, it should use **focus-visible**. Here is a list of elements that use focus vs focus-visible:

#### Focus

* Input
* Select menu

#### Focus Visible

* Button
* Link
* Checkbox
* Radio
* Dropdown menu
* List item
* Tab

References

* [The Focus-Indicated Pseudo-class: :focus-visible.](https://www.w3.org/TR/selectors-4/#the-focus-visible-pseudo)
* [Understanding Success Criterion 2.4.7: Focus Visible.](https://www.w3.org/WAI/WCAG21/Understanding/focus-visible.html)

## Tooling

### Browser Extension

#### Chrome and Firefox

[WebAim - WAVE Browser Extensions](https://wave.webaim.org/extension/)

### Checklists

#### Android Accessibility Checklist

* [Deque - Summary and Checklist: Android Native Application Accessibility](https://dequeuniversity.com/assets/pdf/module-android/module-android-checklist.pdf)

#### iOS Accessibility Checklist

* [Deque - Summary and Checklist: iOS Application Accessibility](https://dequeuniversity.com/assets/pdf/module-ios/module-ios-checklist.pdf)

#### Web Accessibility Checklist

* [Deque - Web Accessibility Checklist](https://dequeuniversity.com/checklists/web/)

### Figma Plugins

#### Adee Comprehensive Accessibility Tool

* [Figma Plugins - Adee Comprehensive Accessibility Tool](https://www.figma.com/community/plugin/931280467863251825/Adee-Comprehensive-Accessibility-Tool)

#### Stark

* [Figma Plugins - Stark](https://www.figma.com/community/plugin/732603254453395948/Stark)

### Screen Readers

To learn more about the various combinations of operating systems and screen reader software, read [WebAim’s 2021 Screen Reader User Survey.](https://webaim.org/projects/screenreadersurvey9/)

#### VoiceOver for Apple Computers

* [Apple - Appendix A: Commands and Gestures](https://www.apple.com/voiceover/info/guide/_1131.html)

#### Narrator Shortcuts for Windows

* [Microsoft - Appendix B: Narrator keyboard commands and touch gestures](https://support.microsoft.com/en-us/windows/windows-keyboard-shortcuts-for-accessibility-021bcb62-45c8-e4ef-1e4f-41b8c1fc87fd)

#### NVDA for Windows

This is free software that can be installed on any Windows machine.

* [Microsoft - NVDA (NonVisual Desktop Access)](https://www.microsoft.com/en-us/p/nvda-nonvisual-desktop-access/9nvl6z0tm57d?activetab=pivot:overviewtab)
* [WebAim - Using NVDA to Evaluate Web Accessibility](https://webaim.org/articles/nvda/)

#### JAWS for Windows

This software is not free and costs from $95/year for home use.

* [Freedom Scientific - JAWS](https://www.freedomscientific.com/products/software/jaws/)
* [WebAim - Using JAWS to Evaluate Web Accessibility](https://webaim.org/articles/jaws/)

#### VoiceOver on iOS

* [Apple - Turn on and practice VoiceOver on iPhone](https://support.apple.com/en-us/HT210076)

#### Talkback for Android

* [Google - Turn TalkBack on or off](https://support.google.com/accessibility/android/answer/6007100?hl%3Den)

---

---
url: 'https://dialtone.dialpad.com/guides/contributing/index.html'
description: Help Dialtone be even better.
---
# Contributing
## Component Contribution

### Design

TBD

### Code

To make code changes in our Design System please first read the
[CONTRIBUTING.md](https://github.com/dialpad/dialtone/blob/staging/.github/CONTRIBUTING.md#contributing)
in our Dialtone repository.

## Adding Icons and Illustrations

If you need to add an icon into Dialtone, here’s how you would go about doing that.

### For System Icons

1. Create a new branch starting with "feat/" in the name.

2. Place the exported SVG file(s) in the appropriate folder category inside `packages/dialtone-icons/src/svg/icons/`

3. If you need to add keywords related to the icon.

   * Add the icon name to `packages/dialtone-icons/src/keywords-icons.json` into the correct category.
   * Add the keywords array as the value. e.g.

   ```json
   {
      "arrows": {
        "arrow-left": ["arrow", "left", "direction"],
        ...
      }
   }
   ```

4. Commit and push your branch.

5. Open a pull request.

6. Once approved it can be merged into staging and will go out in the next release.

### For System Illustrations

1. Create a new branch starting with "feat/" in the name.

2. Place the exported SVG file(s) in the appropriate folder category inside `packages/dialtone-icons/src/svg/illustrations/`

3. If you need to add keywords related to the illustration.

   * Add the illustration name to `packages/dialtone-icons/src/keywords-illustrations.json` into the correct category.
   * Add the keywords array as the value. e.g.

   ```json
   {
      "spot-illustrations": {
        "blank-space": ["blank", "space"],
        ...
      }
   }
   ```

4. Commit and push your branch.

5. Open a pull request.

6. Once approved it can be merged into staging and will go out in the next release.

---

---
url: 'https://dialtone.dialpad.com/guides/getting-started/index.html'
description: A quick start guide to add Dialtone to your project.
---
# Getting Started
## 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](https://www.npmjs.com/).

```bash
npm install @dialpad/dialtone-css
```

Add the following line in your Less file:

```less
@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:

```less
@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](https://css-tricks.com/lets-define-exactly-atomic-css/) 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!

```html
<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](/utilities/spacing/padding.md) `.d-p8` to add 8px of padding on all sides.
* Our [background color utility class](/utilities/backgrounds/color.md) `.d-bgc-contrast`.
* Our [font color utility class](/utilities/typography/font-color.md) `.d-fc-primary-inverted` to change the font color to the inverted primary text color.
* Our [border radius](/utilities/borders/radius.md) `.d-bar8` for rounded corners.
* Our [text style](/design/typography/index.md) `.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](https://dialtone.dialpad.com/vue/).
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.

```html
<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)](http://getbem.com/). 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](http://getbem.com/introduction/):

* **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

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

### CSS

```less
.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:

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.

### Polyfills

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

1. 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](https://github.com/WICG/focus-visible#installation) installation instructions.
2. Postcss focus-visible plugin adds a .focus-visible class for every :focus-visible class found in your css, follow the [postcss-focus-visible](https://www.npmjs.com/package/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](https://stackoverflow.com/c/dialpad/questions/121).

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](/guides/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:**

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

Create `.mcp.json` in your project root:

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

Restart your AI assistant to connect. [Read the full MCP Server guide](/guides/mcp-server/) 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](https://github.com/dialpad/dialtone/blob/master/.github/CONTRIBUTING.md)**.

### Install Node & npm

To run Dialtone locally, you must have Node installed. The required version is specified in `.nvmrc` at the repo root — use [nvm](https://github.com/nvm-sh/nvm) to install and switch to it automatically:

```bash
nvm install
nvm use
```

Once Node is installed, enable [Corepack](https://nodejs.org/api/corepack.html) so that the correct pnpm version is used automatically:

```bash
corepack enable
```

Corepack reads the `packageManager` field in `package.json` and uses the pinned pnpm version without any manual version switching.

### Clone Project

Download the project:

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

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

Then `cd` into the Dialtone directory:

```bash
cd ./path/to/dialtone
```

### Install Dependencies

Dialtone uses [Gulp](https://gulpjs.com/) to automate its various workflows.
Run the following command to install Gulp and all other project dependencies:

```bash
pnpm install
```

### Building Dialtone

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

```bash
nx run dialtone-documentation:start
```

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

---

---
url: 'https://dialtone.dialpad.com/guides/mcp-server/index.html'
description: >-
  Search Dialtone's design system with AI assistants using the Model Context
  Protocol
---
## What It Does

The Dialtone MCP Server provides AI assistants with real-time search access to:

* **3,315 CSS utility classes** - Find classes like `d-p8`, `d-d-flex`, `d-w100p`
* **5,691 design tokens** - Find tokens like `--dt-color-foreground-primary`, `--dt-space-400`
* **87 Vue components** - Discover `DtButton`, `DtModal` with full API documentation
* **594 icons** - Find icons like `bell-ring`, `arrow-up`, `calendar-plus`
* **Public documentation** - `search_documentation`: Search usage prose, recipes, accessibility rules, migration guides, and design principles. Use for "how-to" and "why" questions that go beyond component/token/icon lookups.

### Smart Features

* **Filters deprecated items** - Automatically removes outdated classes and components
* **Recommends alternatives** - Suggests better patterns when discouraged classes are found
* **AI-optimized results** - Smart scoring provides the most relevant matches first
* **Design system aware** - Understands Dialtone's conventions and patterns

## Installation

There are three ways to install the Dialtone MCP Server. **Project-scoped installation takes priority** over user-scoped when both exist.

### Project-Scoped (Recommended for Teams)

Best for team collaboration - everyone uses the same version via version control.

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

Create or update `.mcp.json` in your project root:

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

Commit `.mcp.json` to version control. Restart Claude Code to connect.

Project-scoped configuration overrides user-scoped. The `dialtone-mcp-server` command resolves from `node_modules/.bin/` first.

### User-Scoped (Personal Use)

Available across all your projects. Choose one method:

#### Option A: Install in dedicated directory

```bash
# Install in a dedicated directory
mkdir -p ~/.mcp-servers
cd ~/.mcp-servers
npm install @dialpad/dialtone-mcp-server

# Add to Claude Code
claude mcp add dialtone --scope user dialtone-mcp-server
```

#### Option B: Install globally

```bash
npm install -g @dialpad/dialtone-mcp-server
claude mcp add dialtone --scope user dialtone-mcp-server
```

#### Option C: Use npx (no installation)

```bash
claude mcp add dialtone --scope user -- npx -y @dialpad/dialtone-mcp-server
```

This stores configuration in `~/.claude/mcp.json`.

### HTTP Transport (Coming Soon)

Remote server deployment for enterprise use.

```bash
claude mcp add dialtone-http --transport http --scope user https://mcp.dialtone.dialpad.com
```

When the server starts, you'll see the current version. If outdated, follow the instructions shown to update.

## Search Tools

### Utility Classes

**Tool:** `search_utility_classes`

Find CSS utility classes to style HTML elements. Use when your query mentions CSS properties (padding, margin, display, flex) or values (8px, 100%, center, auto).

**Example queries:**

```text
"padding 8px"       → d-p8, d-pt8, d-pr8, d-pb8, d-pl8, d-px8, d-py8
"display flex"      → d-d-flex, d-d-inline-flex
"width 100%"        → d-w100p
"margin top auto"   → d-mt-auto
"text align center" → d-ta-center
```

**Parameters:**

* `query` (required): CSS property and/or value
* `limit` (optional): Maximum results (1-50, default 15)

### Design Tokens

**Tool:** `search_tokens`

Find design tokens (CSS variables) from Dialtone's design system. Use when your query mentions token categories (color, space, font, size) or semantic names (primary, success, foreground, background).

**Example queries:**

```text
"color foreground primary" → --dt-color-foreground-primary
"space 400"                → --dt-space-400, --dt-space-400-negative
"font family"              → --dt-font-family-body, --dt-font-family-expressive
"font weight bold"         → --dt-font-weight-bold
```

**Parameters:**

* `query` (required): Token category, name, or value
* `limit` (optional): Maximum results (1-50, default 15)

### Components

**Tool:** `search_components`

Find Vue components from Dialtone's component library with props, events, and slots. Use when your query mentions UI elements (button, modal, input, dropdown) or component names.

**Example queries:**

```text
"button"   → DtButton, DtButtonGroup, DtBanner (29 results)
"modal"    → DtModal, DtBanner, DtDropdown (6 results)
"checkbox" → DtCheckbox, DtCheckboxGroup, DtRadio
```

**Returns:**

* Component name
* Description
* Props (name, type, default, description)
* Events (name, description)
* Slots (name, description)
* Import path

**Parameters:**

* `query` (required): Component name or UI element
* `limit` (optional): Maximum results (1-30, default 10)

### Icons

**Tool:** `search_icons`

Find icons from Dialtone's icon library and learn how to use icon components. Icons are imported from `@dialpad/dialtone-icons/vue3`, not `@dialpad/dialtone-vue`.

**Example queries:**

```text
"notification" → bell, bell-ring, bell-off, bell-plus
"arrow up"     → arrow-up, arrow-up-down, arrow-up-left
"profile"      → user
"calendar"     → calendar, calendar-plus, calendar-event
```

**Returns:**

* Icon name
* Categories
* Keywords
* Tree-shakable import path
* Usage example

**Parameters:**

* `query` (required): Icon name, category, or keyword
* `limit` (optional): Maximum results (1-50, default 20)

## Usage Examples

### Finding Styling Classes

When working on a component and need specific styling:

```text
User: "What class adds padding 8px to all sides?"
Claude: [Uses search_utility_classes tool]
Result: d-p8 (padding: var(--dt-space-400) which equals 8px)
```

### Discovering Components

When building UI and unsure what components exist:

```text
User: "What button components are available in Dialtone?"
Claude: [Uses search_components tool]
Result: DtButton, DtButtonGroup, DtIconButton with complete
        prop documentation, events, and usage examples
```

### Looking Up Tokens

When implementing designs and need exact token values:

```text
User: "What's the primary foreground color token?"
Claude: [Uses search_tokens tool]
Result: --dt-color-foreground-primary
        Value: #1C1C1C (in light theme)
        Available in: dp-light, dp-dark themes
```

### Finding Icons

When adding icons to your interface:

```text
User: "Show me all notification-related icons"
Claude: [Uses search_icons tool]
Result: bell, bell-ring, bell-off, bell-plus, bell-minus
        Import: import { IconBell } from '@dialpad/dialtone-icons/vue3'
```

## Configuration

### Updating the Server

The server checks for updates automatically on startup. If a new version is available, you'll see:

```text
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⚠️  Dialtone MCP Server Update Available
   Current: v1.2.0
   Latest:  v1.2.1

   To update:
   1. npm install -D @dialpad/dialtone-mcp-server@latest
   2. Restart this conversation
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

**To update:**

**Project-scoped:**

```bash
npm install -D @dialpad/dialtone-mcp-server@latest
```

**User-scoped (local directory):**

```bash
cd ~/.mcp-servers
npm update @dialpad/dialtone-mcp-server
```

**User-scoped (global):**

```bash
npm update -g @dialpad/dialtone-mcp-server
```

**User-scoped (npx):**
No action needed - npx always uses the latest version.

After updating, restart your Claude Code conversation to load the new version.

### Managing Connections

**List configured servers:**

```bash
claude mcp list
```

**View specific server:**

```bash
claude mcp get dialtone
```

**Remove server:**

```bash
claude mcp remove dialtone
```

## Compatible Platforms

The Dialtone MCP Server works with any MCP-compatible AI assistant:

* ✅ **Claude Code CLI** - Primary integration
* ✅ **Claude Desktop** - Via configuration file
* ✅ **VS Code** - With GitHub Copilot
* ✅ **Cursor** - Native MCP support
* ✅ **Windsurf** - Native MCP support
* ✅ **Cline** - MCP integration
* ✅ **Continue** - MCP support
* ✅ **Any MCP-compatible client**

### Platform-Specific Setup

**Claude Desktop:**

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%/Claude/claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "dialtone": {
      "command": "npx",
      "args": ["-y", "@dialpad/dialtone-mcp-server"]
    }
  }
}
```

Restart Claude Desktop and look for the 🔌 icon to confirm connection.

## Troubleshooting

### Server Not Connecting

**For project-scoped installation:**

1. Verify `.mcp.json` exists in your project root with correct format

2. Check package is installed:

   ```bash
   npm list @dialpad/dialtone-mcp-server
   ```

3. Verify bin command exists:

   ```bash
   ls node_modules/.bin/dialtone-mcp-server
   ```

4. Restart Claude Code completely

**For user-scoped installation:**

1. List configured servers:

   ```bash
   claude mcp list
   ```

2. Check if dialtone is listed and enabled

3. Test the server:

   ```bash
   claude mcp get dialtone
   ```

4. Check configuration:

   ```bash
   cat ~/.claude/mcp.json
   ```

Project-scoped configuration overrides user-scoped. If you have both, the project-level `.mcp.json` takes precedence.

### Version Shows Old After Updating

The server loads once at conversation start. You must restart your conversation after updating to see the new version.

### No Search Results

* **Use keywords, not questions** - Try "button" instead of "What button components exist?"
* **Try broader terms first** - Search "padding" before "padding left 16px"
* **Check example queries** - Review the examples in each tool section above
* **Verify installation** - Ensure the server is running: `claude mcp list`

### Build Issues

If you're developing or testing locally:

1. Ensure workspace dependencies are built first
2. Run from monorepo root: `pnpm install`
3. Build the server: `pnpm nx run dialtone-mcp-server:build`
4. Check for TypeScript errors in the console

## Resources

* **Dialtone Documentation** - [dialtone.dialpad.com](https://dialtone.dialpad.com)
* **npm Package** - [@dialpad/dialtone-mcp-server](https://www.npmjs.com/package/@dialpad/dialtone-mcp-server)
* **GitHub Repository** - [github.com/dialpad/dialtone](https://github.com/dialpad/dialtone)
* **MCP Protocol** - [modelcontextprotocol.io](https://modelcontextprotocol.io)
* **Report Issues** - [GitHub Issues](https://github.com/dialpad/dialtone/issues)

## Next Steps

Now that you have the MCP server installed, explore these resources:

* [Getting Started with Dialtone](/guides/getting-started/) - Learn Dialtone basics
* [Utility Classes](/utilities/) - Browse all utility classes
* [Design Tokens](/tokens/) - Explore design tokens
* [Components](/components/) - Discover Vue components
* [Icons](/design/icons/) - View the icon library

***

The MCP server is perfect for discovering Dialtone patterns while coding. Instead of searching documentation manually, simply ask your AI assistant about components, tokens, or utilities, and it will search for you in real-time.

---

---
url: 'https://dialtone.dialpad.com/tokens/index.html'
description: Multi-platform values that make up Dialtone's design language
---
# Design Tokens
Design tokens are all the defined values that are part of the design system, such as color, spacing, typography, and more. Design tokens are published in many different forms so they can be consumed on all platforms (CSS, LESS, Android, iOS, etc).

See the [dialtone tokens README](https://github.com/dialpad/dialtone/tree/staging/packages/dialtone-tokens#readme) for usage info.

---

---
url: 'https://dialtone.dialpad.com/utilities/index.html'
description: A utility-first CSS framework for building user interfaces.
---
# CSS Utilities
## Introduction

Utilities – also known as “trumps,” “helper classes,” or “alterations” – are high-specificity selectors for making very targeted alterations to existing elements or components.

Each utility 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!

Most utilities come with responsive options, enabling alterations at targeted screen size ranges. For example, “small padding on smaller screens, larger padding on bigger screens.”

While an atomic CSS approach comes with many advantages, we recognize 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.

## Example

### Border Top

`d-bt` applies a border (`b`) to the top (`t`) side. 1px is the default width, and the color is inherited from the foreground color (`currentColor`).

```html
<div class="d-bt">Box</div>
```

### Border Top Width

`d-btw4` applies a 4px (`4`) width (`w`) to the top (`t`).

```html
<div class="d-bt d-btw4">Box</div>
```

### Border Color

`d-bc-critical` applies a [critical](/design/colors/index.md#borders) border (`b`) color (`c`).

```html
<div class="d-bt d-btw4 d-bc-critical">Box</div>
```

## Tutorial

A basic example styling a container by combining Dialtone's CSS utilities. Follow each step with this [Codepen template.](https://codepen.io/pen?template=dyKvvZB)

### 1. Begin with an Unstyled Container

```html
<div>Box</div>
```

### 2. Apply an Inverted Background Color

Apply a [**Primary Inverted** Surface Color](/utilities/backgrounds/color/index.md#classes).

```html
<div class="d-bgc-primary-inverted">Box</div>
```

### 3. Apply Color to the Foreground Text

Since this will be primary content on a dark surface, let's use `d-fc-primary-inverted` from the [font color utilities](/utilities/typography/color/index.md).

```html
<div class="d-bgc-primary-inverted d-fc-primary-inverted">Box</div>
```

### 4. Apply Some Padding

Let's use `d-p8` padding for all four sides, from the list of [padding utility classes](/utilities/spacing/padding/index.md).

```html
<div class="d-bgc-primary-inverted d-fc-primary-inverted d-p8">Box</div>
```

### 5. List a Bunch of Boxes

Let's repeat them in a [Stack](/components/stack.md) component. Note that I've moved the surface and foreground colors to the parent container so they may inherit.

```html
<dt-stack class="d-bgc-primary-inverted d-fc-primary-inverted">
  <div class="d-p8">Box 1</div>
  <div class="d-p8">Box the 2nd</div>
  <div class="d-p8">Box third</div>
  <div class="d-p8">Box IV</div>
</dt-stack>
```

### 6. Render Them Horizontally

Let's add the `direction` prop to make them flow horizontally.

```html
<dt-stack direction="row" class="d-bgc-primary-inverted d-fc-primary-inverted">
  <div class="d-p8">Box 1</div>
  <div class="d-p8">Box the 2nd</div>
  <div class="d-p8">Box third</div>
  <div class="d-p8">Box IV</div>
</dt-stack>
```

### 7. Add Borders to Segment Each

Add a border between each item with `d-divide-x`. Its default color is `currentColor`.

```html
<dt-stack direction="row" class="d-bgc-primary-inverted d-fc-primary-inverted d-divide-x">
  <div class="d-p8">Box 1</div>
  <div class="d-p8">Box the 2nd</div>
  <div class="d-p8">Box third</div>
  <div class="d-p8">Box IV</div>
</dt-stack>
```

### 8. And Change the Border Color

Since the border color inherits the color of the parent's foreground (implicitly `currentColor`), let's soften it with a bold inverted border color `d-divide-moderate-inverted`.

```html
<dt-stack direction="row" class="d-bgc-primary-inverted d-fc-primary-inverted d-divide-x d-divide-moderate-inverted">
  <div class="d-p8">Box 1</div>
  <div class="d-p8">Box the 2nd</div>
  <div class="d-p8">Box third</div>
  <div class="d-p8">Box IV</div>
</dt-stack>
```

### 9. How about some icons

Add some [icons](/design/icons/index.md).

```html
<dt-stack direction="row" class="d-bgc-primary-inverted d-fc-primary-inverted d-divide-x d-divide-moderate-inverted">
  <dt-stack direction="row" gap="400" class="d-p8">
    <dt-icon name="alert-triangle" size="200" />
    Box 1
  </dt-stack>
  <dt-stack direction="row" gap="400" class="d-p8">
    <dt-icon name="info" size="200" />
    Box the 2nd
  </dt-stack>
  <dt-stack direction="row" gap="400" class="d-p8">
    <dt-icon name="alert-circle" size="200" />
    Box third
  </dt-stack>
  <dt-stack direction="row" gap="400" class="d-p8">
    <dt-icon name="check-circle" size="200" />
    Box IV
  </dt-stack>
</dt-stack>
```

### 10. Let's use some real color

Apply a [semantic surface color](/utilities/backgrounds/color.md) to convey some meaning to them, e.g. `d-bgc-critical-strong`.

```html
<dt-stack direction="row" gap="400" class="d-fc-primary-inverted">
  <dt-stack direction="row" gap="400" class="d-bgc-critical-strong d-p8">
    <dt-icon name="alert-triangle" size="200" />
    Critical
  </dt-stack>
  <dt-stack direction="row" gap="400" class="d-bgc-info-strong d-p8">
    <dt-icon name="alert-circle" size="200" />
    Info
  </dt-stack>
  <dt-stack direction="row" gap="400" class="d-bgc-success-strong d-p8">
    <dt-icon name="check-circle" size="200" />
    Success
  </dt-stack>
</dt-stack>
```

### 11. Apply an appropriate text style

Choose a [text style](/design/typography/). Text styles combine multiple text properties, i.e. `font size`, `font-family`, `font-weight`, etc.

```html
<dt-stack direction="row" gap="400" class="d-fc-primary-inverted">
  <dt-stack direction="row" gap="400" class="d-label--sm d-bgc-critical-strong d-p8">
    <dt-icon name="alert-triangle" size="200" />
    Critical
  </dt-stack>
  <dt-stack direction="row" gap="400" class="d-label--sm d-bgc-info-strong d-p8">
    <dt-icon name="alert-circle" size="200" />
    Info
  </dt-stack>
  <dt-stack direction="row" gap="400" class="d-label--sm d-bgc-success-strong d-p8">
    <dt-icon name="check-circle" size="200" />
    Success
  </dt-stack>
</dt-stack>
```

### 12. Tweak the spacing

Refine the spacing by adusting the [Stack](/components/stack.md) `gap` prop and padding utilities for horizontal and vertical padding.

```html
<dt-stack direction="row" gap="400" class="d-fc-primary-inverted">
  <dt-stack direction="row" gap="300" class="d-label--sm d-bgc-critical-strong d-py4 d-px8">
    <dt-icon name="alert-triangle" size="200" />
    Critical
  </dt-stack>
  <dt-stack direction="row" gap="300" class="d-label--sm d-bgc-info-strong d-py4 d-px8">
    <dt-icon name="alert-circle" size="200" />
    Info
  </dt-stack>
  <dt-stack direction="row" gap="300" class="d-label--sm d-bgc-success-strong d-py4 d-px8">
    <dt-icon name="check-circle" size="200" />
    Success
  </dt-stack>
</dt-stack>
```

### 13. Round it out!

Add `d-bar4` to each item for subtle rounded corners.

```html
<dt-stack direction="row" gap="400" class="d-fc-primary-inverted">
  <dt-stack direction="row" gap="300" class="d-bar4 d-label--sm d-bgc-critical-strong d-py4 d-px8">
    <dt-icon name="alert-triangle" size="200" />
    Critical
  </dt-stack>
  <dt-stack direction="row" gap="300" class="d-bar4 d-label--sm d-bgc-info-strong d-py4 d-px8">
    <dt-icon name="alert-circle" size="200" />
    Info
  </dt-stack>
  <dt-stack direction="row" gap="300" class="d-bar4 d-label--sm d-bgc-success-strong d-py4 d-px8">
    <dt-icon name="check-circle" size="200" />
    Success
  </dt-stack>
</dt-stack>
```

### Keep Exploring!

View the final result in this [Codepen template](https://codepen.io/pen?template=XWYMMRY). Continue to explore using the variety of CSS utilities listed here.