Introducing Dialtone 10

At a glance #

• Three core design concepts set the tone: the Primitive Triad, Layout and Spacing, and the Mode Directive.
• Every Dialtone component was touched by the visual refresh, in addition to new components, and standardizing the API vocabulary.
• A redesigned doc site, improved component pages, and the Component Playground improves discoverability and usage. Visual Changes for Designers identifies intentional visual differences.
• Improved tooling, especially for coding assistants, makes current Dialtone guidance available through raw Markdown, llms.txt, Dialtone MCP Server, Dialtone CLI, and VS Code extension.
• Migration Guides available, starting with the health check. Automation handles much of the mechanical work.

Three core design concepts #

The Primitive Triad, the Layout and Spacing system, and the Mode Directive are the three most impactful design changes introduced. They improve how components are designed and implemented, how dimensions are expressed, and how color mode is scoped.

1. The Primitive Triad #

Together, these three primitives should cover most UI layout and text work:

• DtBox defines what a container is: its surface, border, spacing, size, and position.
• DtStack defines how its children are arranged.
• DtText for typography variants, tone, strength, and text behavior.

Previously, expressing that intent required complicated combinations of CSS utility classes, which made the code harder to read and maintain. These primitive components improve their discoverability and validate them during development. CSS Utilities still remain available for cases the components do not cover.

Together, the three components are a cohesive and fast composition vocabulary across design, code review, documentation, and coding-assistant guidance. For example, a card may be described as a Box containing a vertical or horizontal Stack of Text elements instead of raw html paired with inline or custom CSS decisions. Those props keep the design choices visible at their point of use, making system changes easier to trace.

<dt-box
  padding="200"
  surface="primary"
  border-width="100"
  border-color="subtle"
  border-radius="400"
  shadow="card"
  inline-size="400"
>
  <dt-stack gap="50">
    <dt-text as="h3" variant="headline-md">Card title</dt-text>
    <dt-text as="p" variant="body-sm" max-lines="3">Card body content with supporting text. Lorem ipsum dolor sit amet, consectetur adipiscing elit.</dt-text>
  </dt-stack>
</dt-box>

2. Layout and Spacing #

Two Dialtone-defined design token scales answer distinct UI questions. Their base units are fixed across consuming projects:

The previous space and size scales were ordinal with the suffix describing a token's position in a list, not a value someone could reasonably calculate. One had to look up why one stop meant 16px and another meant 128px. The new names and bases make that distinction explicit.

The suffix multiplies the fixed base rather than marking a token's position in an arbitrary list. If someone wants to add 16px of padding, knowing that the spacing base is 8px, they'd reach for spacing-200 (8px × 2). Similarly, when building something with 128px sizing, they'd reach for layout-200 (64px × 2). Off-scale exceptions include explicit values with the unit, e.g. layout-1px.

.thing {
  padding: var(--dt-spacing-200); /* 16px */
  width: var(--dt-layout-200); /* 128px */
}

<el class="d-p-200 d-w-200">
  <!--
    Same multiplier, different base scales:
    d-p-200: 2 × 8px = 16px
    d-w-200: 2 × 64px = 128px
  -->
</el>

3. The Mode Directive #

Some UI regions often need a different mode (e.g. light, dark) from their surroundings, often called "inverted regions". Current product examples include the call bar, an inverted hovercard, or portions of a Dialpad Meeting. The Mode Directive scopes that decision to the element and its children.

Previously these implementations often depended on custom local styles to invert color design tokens, which proved hard to maintain and upgrade. Moving mode to the containing element allows elements within to use their normal semantic tokens and render accordingly.

<dt-box v-dt-mode:invert>
  <!-- Opposite mode of parent -->
</dt-box>
<dt-box v-dt-mode:dark>
  <!-- always dark -->
</dt-box>
<dt-box v-dt-mode:light>
  <!-- always light -->
</dt-box>

Design Foundations #

Theming #

Theming is now a layered system with four independent dimensions.

1. Brand: controls product-wrapper colors.
2. Mode: light or dark appearance.
3. Contrast: strengthens the foreground elements and borders.
4. Material: changes the neutral palette of most foreground, surface, and border design tokens.

This layered dimension approach allows changing one independently, without encoding the others into the same theme name.

The use case for the Brand dimension remains deliberately narrow: it changes the wrapper areas such as navigation without recoloring every content surface. The base brand theme loads once, then data-dt-* attributes or runtime setters apply only the selected brand, mode, contrast, and material as overrides.

Color #

Every base color ramp (e.g. red, purple, black, etc.) now uses the same twelve stops from 50 through 1000, replacing the irregular stops that had accumulated over time (e.g. 550). Semantic foreground, surface, and border tokens remain the intended product interface; the Product Color Palette documents the current set.

All colors are now defined using OKLCH rather than HSL. OKLCH gives Dialtone more predictable control over perceived lightness and chroma across different hues. Relative color syntax then applies opacity from a complete color token, removing the separate channel variables previously needed for each color.

Dialtone can now shape lightness, chroma, and hue independently while keeping the ramps structurally and perceptually consistent.

Refactoring to OKLCH allowed for the removal of over 3,200 CSS custom properties (aka CSS variables) and reduced the CSS build by ~33%.

Typography #

The default body size moves from 15px to 16px, and the text scale has expanded from the previous limited set.

The new DtText component is the recommended way to apply styled product typography. It provides semantic variants through props but does not expose every raw size as a variant. When you need a different size, layer in size on top of the initial variant.

<dt-text variant="headline-md" as="h4"> Demo </dt-text>
<dt-text
  as="p"
  variant="body-md"
  tone="tertiary"
  max-lines="2"
  density="300"
>
  Lorem ipsum dolor, sit amet consectetur adipisicing elit. Eius voluptas quasi animi corporis deserunt iusto suscipit. Delectus deleniti a animi doloribus assumenda, nobis, iusto neque beatae, quibusdam obcaecati aliquid harum. Placeat distinctio doloremque officia consequuntur fugit at repudiandae pariatur sint amet quidem cumque ipsa suscipit nisi, laudantium temporibus. Distinctio voluptatibus sunt exercitationem id aspernatur ab maiores totam reiciendis velit in? Pariatur, nisi culpa asperiores at, cumque commodi quasi doloremque est id quae voluptatibus voluptate earum eos accusantium, ducimus sit dolorem. Ipsam illum iste, debitis accusantium sint optio ducimus et dicta.
</dt-text>

Components #

Every Dialtone component was touched via the visual refresh, and some received new APIs or behavior.

New #

DtFilterPill

DtFilterPill filters a list or data set, with multi-select and single-select patterns for narrowing results.

DtSegmentedControl

DtSegmentedControl switches between views or formats of the same content while keeping one option selected.

DtResizable

DtResizable creates adjustable panel layouts and split views with draggable, keyboard-accessible handles.

DtProse

DtProse applies Dialtone typography to raw or rendered HTML such as Markdown, help content, and assistant output.

<dt-prose>
  <h1>Headings and paragraphs</h1>
  <p>This is a standard paragraph of body text. It contains enough words to wrap across multiple lines.</p>
  <p>This is another standard paragraph of body text. </p>
  <h2>Heading Level 2</h2>
  <p>This is a standard paragraph of body text. It contains enough words to wrap across multiple lines.</p>
  <h3>Heading Level 3</h3>
  <p>This is a standard paragraph of body text. It contains enough words to wrap across multiple lines.</p>
  <h4>Heading Level 4</h4>
  <p>This is a standard paragraph of body text. It contains enough words to wrap across multiple lines.</p>
  <h5>Heading Level 5</h5>
  <p>This is a standard paragraph of body text.</p>
</dt-prose>

DtTextList

DtTextList provides semantic ordered, unordered, nested, and custom-marker lists without manual list CSS utilities.

DtProgressCircle

DtProgressCircle shows determinate progress for work such as uploads or processing.

Visual refresh across the library #

The new color, type, spacing, and surface foundations affect the component library as a whole. The examples below are selected highlights. The Visual Changes for Designers guide compares the most significant changes and explains which differences are intentional during migration.

DtAvatar and DtPresence

DtAvatar moves from a circle to a rounded square, adds a deterministic color system with 12 hue families, and allows group avatars to render at full size. Deactivated styling is clearer, and presence indicators cut space from the avatar instead of adding a border. DtPresence replaces color-only dots with shape-coded statuses. Avatar migration is manual; use the Avatar migration guide for the required review.

DtButton and form controls

DtButton now has slightly squarer corners, medium-weight labels, softer outlined borders, and darker primary hover and active states. DtInput and DtSelectMenu were adjusted alongside it so controls remain aligned at matching sizes.

DtTabs

Selected and hover colors were remapped, and the selection indicator now slides between tabs.

Feedback components

DtValidationMessages, DtNotice, DtBanner, and DtToast use refreshed typography and retuned status colors. Validation messages add an info state; toasts add a leading status icon and larger radius.

Layered surfaces

DtPopover, DtHovercard, DtModal, and other layered components now use a dedicated overlay surface. The difference is subtle in light mode and clearer in dark mode, where overlays appear lighter than the page behind them.

Other visible changes

DtLink has a thicker, closer underline that breaks around descenders, and links configured without an underline now add one on hover. DtEmptyState uses tighter spacing and smaller headings.

Other component updates #

Scroller, overlays, form controls, Rich Text Editor, icons, and localization also received smaller API, behavior, accessibility, or content updates. Two changes require direct action: DtChip now requires :interactive="true" when a chip should respond to click or keyboard input, and the scrollbar directive's never modifier is now named always. Use the Chip migration guide and Scrollbar migration guide for those changes. The release notes contain the complete inventory.

The broader set includes better control over Scroller content and events, more flexible overlay anchors and boundaries, input fixes for composition and keyboard events, and Shadow DOM support in places where product surfaces need it. Rich Text Editor, icon, and locale additions are summarized in the release notes rather than repeated here.

Engineering foundations #

CSS architecture #

Dialtone CSS now uses named cascade layers for reset, base, components, and utilities. Layer order makes utility precedence predictable while leaving unlayered application CSS in control during phased adoption. The cascade layers guide explains the available builds and what application overrides need to consider.

Registered @property declarations stop opacity utilities from inheriting into descendants, and selected :where() selectors make component styles easier to override without adding specificity.

Platform and packages #

DtModal now renders a native <dialog> while retaining Dialtone's focus trapping and close behavior. Its DOM and top-layer behavior changed, so consumers that target internals should read the native dialog guide.

The focusgroup and focustrap directives make shared keyboard navigation and focus containment available to components and product interfaces. Product-specific recipes moved into distinct UI Kits; the recipes migration guide maps the old imports. Dialtone 10 is Vue 3 only, with remaining Vue 2 consumers covered by the Vue 2 removal guide.

Reusable interaction behavior now relies more on browser primitives and shared directives to improve accessibility, while product-specific composition lives with the teams that manage those interfaces.

Logical naming #

Props, slots, and CSS utilities now use logical style properties instead of physical ones.

.thing {
  padding-left: val;
  border-left: val;
}

<el class="d-pl-100">...</el>

.thing {
  padding-inline-start: val;
  border-inline-start: val;
}

<el class="d-pis-100">...</el>

Component APIs #

Affected components now share a smaller vocabulary for common concepts. Most can be categorized by four key changes:

Numeric sizes align component APIs with the token scale. Open state, severity names, and navigation behavior no longer vary by component. Supported internal customization points also expose documented *-class props instead of requiring selectors that depend on private class names.

Positive boolean names follow the same rule: affected hide* props become show*, so enabling a feature no longer means setting a negative prop to false. Overlay labels and form events also move toward shared names where the affected components support them.

Accessibility #

Color-assistive and high-contrast themes are first-class theme values. Shared focus directives, native dialog semantics, the WAI-ARIA Tabs pattern, and focus-ring tokens improve keyboard and visual access across the component set. These changes still depend on product context, so component pages and Accessibility and inclusive design remain the source for implementation guidance.

CI runs accessibility tests for relevant Dialtone Vue changes. Visual regression and bundle-size checks run on eligible pull requests under their path and label conditions.

Documentation experience #

Rebuilt with a focus on a shared source for people and coding assistants. Find and test current guidance with the Component Playground and better examples. Raw Markdown and integrations for MCP, CLI, and VS Code make guidance discoverable with the tools we're already using.

Component Playground #

Component pages now lead with the Component Playground. Choose a preset, change a prop or slot, inspect the result, and copy the generated Vue. The Button page is a good place to explore that now. Play around with the prop panel, compare variants, and copy its code for immediate use.

Raw Markdown #

All documentation has a raw Markdown counterpart for quick access via page controls to copy its Markdown, its link, or even open it directly in a coding assistant. The site also publishes llms.txt and llms-full.txt for tools that discover documentation through those indexes.

The generated pages remove interactive-only markup and convert API and data tables to plain Markdown. That gives people and tools the same published guidance without requiring an assistant to interpret the rendered documentation interface.

MCP Server, CLI, Linting, and text editor extensions #

1. The Dialtone MCP Server gives compatible coding assistants searchable component, design tokens, utility, icon, and guide context, including replacements for deprecated patterns.
2. The Dialtone CLI provides direct terminal lookup and resolves installed-package data when it is available.
3. The VS Code extension brings component, prop, token, and utility auto-complete and guidance directly in VSCode-based editors.
4. The ESLint and Stylelint plugins check for deprecated patterns and provide guidance in the editor.

Migrating #

Start with the health check #

The migration guide orders changes by dependency so later conversions build on earlier ones. Most statically detectable work has automation; each guide separates that work from its manual checks. Start with the health check:

npx dialtone-migrate --health-check --cwd ./src

Use the results to choose the relevant guides. Color, token, component, and framework migrations stay in a defined sequence because later tools expect earlier names and foundations to be in place.

What remains manual #

Tooling cannot choose application cascade-layer adoption, place Mode directives, review each Avatar use, complete a Vue 2 migration, or verify interaction changes. After automation, run component tests, interaction checks, theme smoke tests, and design QA. Visual Changes for Designers identifies intentional differences and the surfaces expected to remain unchanged.

Review representative product states rather than only default component examples. Include nested overlays, disabled and loading states, long or localized text, keyboard navigation, and each supported appearance combination.

What stays the same #

Semantic renames do not intentionally change meaning, and some deprecated aliases remain during migration. Visual differences should come from the refreshed foundations or documented component changes, not from a vocabulary rename alone. Treat each migration guide as the compatibility contract for its change.

Next steps by role #

• Designers: Review affected surfaces with Visual Changes for Designers and current component pages, then classify each difference as intended or a regression.
• Engineers: Run the health check, follow the migration guide in order, then complete its manual and product-level verification.
• Product managers: Plan design QA, interaction testing, and theme smoke testing for each migrated surface.

Contributors #

Dialtone 10 is the work of many contributors across Dialtone Engineering, Design Engineering, and Product Design.

• Brad Paugh: component API and event standardization, migration tooling and CLI, theming API.
• Francis Rupert: theming system, component visual refresh, new components, CSS architecture, design tokens, primitives, directives, migration tooling, Component Playground, doc site redesign.
• Belu Montoya: AI-readable documentation and validation, llms.txt, MCP Server architecture and doc search, migration guides.
• Ignacio Ropolo: component naming and slot-class APIs, UI Kit migration, Vue 2 removal, migration guides.
• Joshua Hynes: Dialtone CLI, DtResizable, Avatar refresh, content guidelines.
• Paulo Reis: Component Playground, accessibility fixes, Visual Changes guide.
• Nina Repetto: Shadow DOM and native-dialog integration across theme setters, Modal, Popover, Tooltip.
• Josh Everhart: UI Kit strategy and documentation.
• Josh Carter: Color theme design tokens.
• Zach Allott: Marketing design documentation, Downloads, themes.
• Tamara Paluch: Project management, migration coordination, documentation.